This is Info file tar.info, produced by Makeinfo version 1.67 from the
input file tar.texi.

START-INFO-DIR-ENTRY
* tar: (tar).			Making tape (or disk) archives.
END-INFO-DIR-ENTRY

   This file documents GNU `tar', a utility used to store, backup, and
transport files.

   Copyright (C) 1992, 1994, 1995, 1996, 1997 Free Software Foundation,
Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.

   This file documents GNU `tar', which is a utility used to store,
backup, and transport files.  `tar' is a tape (or disk) archiver.  This
manual documents the release 1.12a.


File: tar.info,  Node: after,  Next: recurse,  Prev: Wildcards,  Up: Choosing

Operating Only on New Files
===========================

     *(This message will disappear, once this node revised.)*

   The `--after-date=DATE' (`--newer=DATE', `-N DATE') option causes
`tar' to only work on files whose modification or inode-changed times
are newer than the DATE given.  If you use this option when creating or
appending to an archive, the archive will only include new files.  If
you use `--after-date' when extracting an archive, `tar' will only
extract files newer than the DATE you specify.

   If you only want `tar' to make the date comparison based on
modification of the actual contents of the file (rather than inode
changes), then use the `--newer-mtime=DATE' option.

   You may use these options with any subcommand.  Note that these
options differ from the `--update' (`-u') subcommand in that they allow
you to specify a particular date against which `tar' can compare when
deciding whether or not to archive the files.

`--after-date=DATE'
`--newer=DATE'
`-N DATE'
     Only store files newer than DATE.

     Acts on files only if their modification or inode-changed times are
     later than DATE.  Use in conjunction with any subcommand.

`--newer-mtime=DATE'
     Acts like `--after-date=DATE' (`--newer=DATE', `-N DATE'), but
     only looks at modification times.

   These options limit `tar' to only operating on files which have been
modified after the date specified.  A file is considered to have
changed if the contents have been modified, or if the owner,
permissions, and so forth, have been changed.  (For more information on
how to specify a date, see *Note Date input formats::; remember that the
entire date argument must be quoted if it contains any spaces.)

   Gurus would say that `--after-date=DATE' (`--newer=DATE', `-N DATE')
tests both the `mtime' (time the contents of the file were last
modified) and `ctime' (time the file's status was last changed: owner,
permissions, etc) fields, while `--newer-mtime=DATE' tests only `mtime'
field.

   To be precise, `--after-date=DATE' (`--newer=DATE', `-N DATE')
checks *both* `mtime' and `ctime' and processes the file if either one
is more recent than DATE, while `--newer-mtime=DATE' only checks
`mtime' and disregards `ctime'.  Neither uses `atime' (the last time the
contents of the file were looked at).

   The MS-DOS/MS-Windows file systems record only one time stamp per
file (Windows 9X and NT file systems usually do have all three time
fields).  On those file systems, `--after-date=DATE' (`--newer=DATE',
`-N DATE') and `--newer-mtime=DATE' will have the same effect.  MS-DOS
stores file time with 2-second granularity; you need to consider this
when setting the value of DATE for these two options.

   Date specifiers can have embedded spaces.  Because of this, you may
need to quote date arguments to keep the shell from parsing them as
separate arguments.

     *Please Note:* `--after-date=DATE' (`--newer=DATE', `-N DATE') and
     `--newer-mtime=DATE' should not be used for incremental backups.
     Some files (such as those in renamed directories) are not selected
     properly by these options.  *Note incremental and
     listed-incremental::.

   To select files newer than the modification time of a file that
already exists, you can use the `--reference' (`-r') option of GNU
`date', available in GNU shell utilities 1.13 or later.  For example,
you could say,

     $ tar -cf ARCHIVE.TAR --newer="`date -r FILE`" /home

It returns the timestamp of that already existing file; this timestamp
expands to become the referent date which `--newer' uses to determine
which files to archive


File: tar.info,  Node: recurse,  Next: one,  Prev: after,  Up: Choosing

Descending into Directories
===========================

     *(This message will disappear, once this node revised.)*

   Usually, `tar' will recursively explore all directories (either
those given on the command line or through the
`--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') option) for the
various files they contain.  However, you may not always want `tar' to
act this way.

   The `--no-recursion' option inhibits `tar''s recursive descent into
specified directories.  If you specify `--no-recursion', you can use
the `find' utility for hunting through levels of directories to
construct a list of file names which you could then pass to `tar'.
`find' allows you to be more selective when choosing which files to
archive; see *Note files:: for more information on using `find' with
`tar'.

`--no-recursion'
     Prevents `tar' from recursively descending directories.

   When you use `--no-recursion', GNU `tar' grabs directory entries
themselves, but does not descend on them recursively.  Many people use
`find' for locating files they want to back up, and since `tar'
*usually* recursively descends on directories, they have to use the
`! -d' option to `find'  as they usually do not want all the files in a
directory.  They then use the {No Value For "op-file-from"} option to
archive the files located via `find'.

   The problem when restoring files archived in this manner is that the
directories themselves are not in the archive; so the
`--same-permissions' (`--preserve-permissions', `-p') option does not
affect them--while users might really like it to.  Specifying
`--no-recursion' is a way to tell `tar' to grab only the directory
entries given to it, adding no new files on its own.


File: tar.info,  Node: one,  Prev: recurse,  Up: Choosing

Crossing Filesystem Boundaries
==============================

     *(This message will disappear, once this node revised.)*

   `tar' will normally automatically cross file system boundaries in
order to archive files which are part of a directory tree.  You can
change this behavior by running `tar' and specifying
`--one-file-system' (`-l').  This option only affects files that are
archived because they are in a directory that is being archived; `tar'
will still archive files explicitly named on the command line or
through `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES'), regardless
of where they reside.

`--one-file-system'
`-l'
     Prevents `tar' from crossing file system boundaries when
     archiving.  Use in conjunction with any write subcommand.

   The `--one-file-system' option causes `tar' to modify its normal
behavior in archiving the contents of directories.  If a file in a
directory is not on the same filesystem as the directory itself, then
`tar' will not archive that file.  If the file is a directory itself,
`tar' will not archive anything beneath it; in other words, `tar' will
not cross mount points.

   It is reported that using this option, the mount point *is*
archived, but nothing under it is.

   This option is useful for making full or incremental archival
backups of a single file system.  If this option is used in conjunction
with `--verbose' (`-v'), files that are excluded are mentioned by name
on the standard error.

* Menu:

* directory::                   Changing Directory
* absolute::                    Absolute File Names


File: tar.info,  Node: directory,  Next: absolute,  Prev: one,  Up: one

Changing the Working Directory
------------------------------

     *(This message will disappear, once this node revised.)*

   To change the working directory in the middle of a list of file
names, either on the command line or in a file specified using
`--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES'), use
`--directory=DIRECTORY' (`-C DIRECTORY').  This will change the working
directory to the directory DIRECTORY after that point in the list.

`--directory=DIRECTORY'
`-C DIRECTORY'
     Changes the working directory in the middle of a command line.

   For example,

     $ tar -c -f jams.tar grape prune -C food cherry

will place the files `grape' and `prune' from the current directory
into the archive `jams.tar', followed by the file `cherry' from the
directory `food'.  This option is especially useful when you have
several widely separated files that you want to store as if they were
in the same directory.

   Note that the file `cherry' is recorded in the archive under the
precise name `cherry', *not* `food/cherry'.  Thus, the archive will
contain three files that all appear to have come from the same
directory; if the archive is extracted with plain `tar --extract', all
three files will be written in the current directory.

   Contrast this with the command,

     $ tar -c -f jams.tar grape prune food/cherry

which records the third file in the archive under the name
`food/cherry' so that, if the archive is extracted using `tar
--extract', the third file will be written in a subdirectory named
`food'.

   You can use the `--directory=DIRECTORY' (`-C DIRECTORY') option to
make the archive independent of the original name of the directory
holding the files.  The following command places the files
`/etc/passwd', `/etc/hosts', and `/lib/libc.a' into the archive
`foo.tar':

     $ tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a

However, the names of the archive members will be exactly what they were
on the command line: `passwd', `hosts', and `libc.a'.  They will not
appear to be related by file name to the original directories where
those files were located.

   Note that `--directory=DIRECTORY' (`-C DIRECTORY') options are
interpreted consecutively.  If `--directory=DIRECTORY' (`-C DIRECTORY')
specifies a relative file name, it is interpreted relative to the then
current directory, which might not be the same as the original current
working directory of `tar', due to a previous `--directory' option.

   When using `--files-from' (*note files::.), you can put `-C' options
in the file list.  Unfortunately, you cannot put `--directory' options
in the file list.  (This interpretation can be disabled by using the
`--null' option.)


File: tar.info,  Node: absolute,  Prev: directory,  Up: one

Absolute File Names
-------------------

     *(This message will disappear, once this node revised.)*

`-P'
`--absolute-names'
     Do not strip leading slashes from file names.

   By default, GNU `tar' drops a leading `/' on input or output.  This
option turns off this behavior; it is equivalent to changing to the
root directory before running `tar' (except it also turns off the usual
warning message).

   When `tar' extracts archive members from an archive, it strips any
leading slashes (`/') from the member name.  This causes absolute
member names in the archive to be treated as relative file names.  This
allows you to have such members extracted wherever you want, instead of
being restricted to extracting the member in the exact directory named
in the archive.  For example, if the archive member has the name
`/etc/passwd', `tar' will extract it as if the name were really
`etc/passwd'.

   On MS-DOS and MS-Windows, `tar' also strips the drive letter and the
colon that follows it, if the original file names include them.

   Other `tar' programs do not do this.  As a result, if you create an
archive whose member names start with a slash, they will be difficult
for other people with a non-GNU `tar' program to use.  Therefore, GNU
`tar' also strips leading slashes from member names when putting
members into the archive.  For example, if you ask `tar' to add the
file `/bin/ls' to an archive, it will do so, but the member name will
be `bin/ls'.

   If you use the `--absolute-names' (`-P') option, `tar' will do
neither of these transformations.

   To archive or extract files relative to the root directory, specify
the `--absolute-names' (`-P') option.

   Normally, `tar' acts on files relative to the working
directory--ignoring superior directory names when archiving, and
ignoring leading slashes when extracting.  (On MS-DOS/MS-Windows, it
also ignores any drive specifications, a letter and a colon, so
`d:/foo/bar' is archived as `foo/bar'.)

   When you specify `--absolute-names' (`-P'), `tar' stores file names
including all superior directory names, and preserves leading slashes
(and drive specs on MS-DOS/MS-Windows).  If you only invoked `tar' from
the root directory you would never need the `--absolute-names' (`-P')
option, but using this option may be more convenient than switching to
root.

`--absolute-names'
     Preserves full file names (inclusing superior dirctory names) when
     archiving files.  Preserves leading slash when extracting files.

   `tar' prints out a message about removing the `/' from file names.
This message appears once per GNU `tar' invocation.  It represents
something which ought to be told; ignoring what it means can cause very
serious surprises, later.  (On MS-DOS/MS-Windows, `tar' also reports
the removing of drive spec.)

   Some people, nevertheless, do not want to see this message.  Wanting
to play really dangerously, one may of course redirect `tar' standard
error to the sink.  For example, under `sh':

     $ tar -c -f archive.tar /home 2> /dev/null

Another solution, both nicer and simpler, would be to change to the `/'
directory first, and then avoid absolute notation.  For example:

     $ (cd / && tar -c -f archive.tar home)
     $ tar -c -f archive.tar -C  / home


File: tar.info,  Node: Date input formats,  Next: Formats,  Prev: Choosing,  Up: Top

Date Input Formats
******************

     Our units of temporal measurement, from seconds on up to months,
     are so complicated, asymmetrical and disjunctive so as to make
     coherent mental reckoning in time all but impossible.  Indeed, had
     some tyrannical god contrived to enslave our minds to time, to
     make it all but impossible for us to escape subjection to sodden
     routines and unpleasant surprises, he could hardly have done
     better than handing down our present system.  It is like a set of
     trapezoidal building blocks, with no vertical or horizontal
     surfaces, like a language in which the simplest thought demands
     ornate constructions, useless particles and lengthy
     circumlocutions.  Unlike the more successful patterns of language
     and science, which enable us to face experience boldly or at least
     level-headedly, our system of temporal calculation silently and
     persistently encourages our terror of time.

     ...  It is as though architects had to measure length in feet,
     width in meters and height in ells; as though basic instruction
     manuals demanded a knowledge of five different languages.  It is
     no wonder then that we often look into our own immediate past or
     future, last Tuesday or a week from Sunday, with feelings of
     helpless confusion.  ...

     -- Robert Grudin, `Time and the Art of Living'.

   This section describes the textual date representations that GNU
programs accept.  These are the strings you, as a user, can supply as
arguments to the various programs.  The C interface (via the `getdate'
function) is not described here.

   Although the date syntax here can represent any possible time since
zero A.D., computer integers are not big enough for such a
(comparatively) long time.  The earliest date semantically allowed on
Unix systems is midnight, 1 January 1970 UCT.

* Menu:

* General date syntax::         Common rules.
* Calendar date item::          19 Dec 1994.
* Time of day item::            9:20pm.
* Timezone item::               EST, DST, BST, UCT, AHST, ...
* Day of week item::            Monday and others.
* Relative item in date strings::  next tuesday, 2 years ago.
* Pure numbers in date strings::  19931219, 1440.
* Authors of getdate::          Bellovin, Salz, Berets, et al.


File: tar.info,  Node: General date syntax,  Next: Calendar date item,  Prev: Date input formats,  Up: Date input formats

General Date Syntax
===================

   A "date" is a string, possibly empty, containing many items
separated by whitespace.  The whitespace may be omitted when no
ambiguity arises.  The empty string means the beginning of today (i.e.,
midnight).  Order of the items is immaterial.  A date string may contain
many flavors of items:

   * calendar date items

   * time of the day items

   * time zone items

   * day of the week items

   * relative items

   * pure numbers.

We describe each of these item types in turn, below.

   A few numbers may be written out in words in most contexts.  This is
most useful for specifying day of the week items or relative items (see
below).  Here is the list: `first' for 1, `next' for 2, `third' for 3,
`fourth' for 4, `fifth' for 5, `sixth' for 6, `seventh' for 7, `eighth'
for 8, `ninth' for 9, `tenth' for 10, `eleventh' for 11 and `twelfth'
for 12.  Also, `last' means exactly -1.

   When a month is written this way, it is still considered to be
written numerically, instead of being "spelled in full"; this changes
the allowed strings.

   Alphabetic case is completely ignored in dates.  Comments may be
introduced between round parentheses, as long as included parentheses
are properly nested.  Hyphens not followed by a digit are currently
ignored.  Leading zeros on numbers are ignored.


File: tar.info,  Node: Calendar date item,  Next: Time of day item,  Prev: General date syntax,  Up: Date input formats

Calendar Date Item
==================

   A "calendar date item" specifies a day of the year.  It is specified
differently, depending on whether the month is specified numerically or
literally.  All these strings specify the same calendar date:

     1970-09-17           # ISO 8601.
     70-9-17              # This century assumed by default.
     70-09-17             # Leading zeros are ignored.
     9/17/72              # Common U.S. writing.
     24 September 1972
     24 Sept 72           # September has a special abbreviation.
     24 Sep 72            # Three-letter abbreviations always allowed.
     Sep 24, 1972
     24-sep-72
     24sep72

   The year can also be omitted.  In this case, the last specified year
is used, or the current year if none.  For example:

     9/17
     sep 17

   Here are the rules.

   For numeric months, the ISO 8601 format `YEAR-MONTH-DAY' is allowed,
where YEAR is any positive number, MONTH is a number between 01 and 12,
and DAY is a number between 01 and 31.  A leading zero must be present
if a number is less than ten.  If YEAR is less than 100, then 1900 is
added to it to force a date in this century.  The construct
`MONTH/DAY/YEAR', popular in the United States, is accepted.  Also
`MONTH/DAY', omitting the year.

   Literal months may be spelled out in full: `January', `February',
`March', `April', `May', `June', `July', `August', `September',
`October', `November' or `December'.  Literal months may be abbreviated
to their first three letters, possibly followed by an abbreviating dot.
It is also permitted to write `Sept' instead of `September'.

   When months are written literally, the calendar date may be given as
any of the following:

     DAY MONTH YEAR
     DAY MONTH
     MONTH DAY YEAR
     DAY-MONTH-YEAR

   Or, omitting the year:

     MONTH DAY


File: tar.info,  Node: Time of day item,  Next: Timezone item,  Prev: Calendar date item,  Up: Date input formats

Time of Day Item
================

   A "time of day item" in date strings specifies the time on a given
day.  Here are some examples, all of which represent the same time:

     20:02:0
     20:02
     8:02pm
     20:02-0500      # In EST (Eastern U.S. Standard Time).

   More generally, the time of the day may be given as
`HOUR:MINUTE:SECOND', where HOUR is a number between 0 and 23, MINUTE
is a number between 0 and 59, and SECOND is a number between 0 and 59.
Alternatively, `:SECOND' can be omitted, in which case it is taken to
be zero.

   If the time is followed by `am' or `pm' (or `a.m.' or `p.m.'), HOUR
is restricted to run from 1 to 12, and `:MINUTE' may be omitted (taken
to be zero).  `am' indicates the first half of the day, `pm' indicates
the second half of the day.  In this notation, 12 is the predecessor of
1: midnight is `12am' while noon is `12pm'.

   The time may alternatively be followed by a timezone correction,
expressed as `SHHMM', where S is `+' or `-', HH is a number of zone
hours and MM is a number of zone minutes.  When a timezone correction
is given this way, it forces interpretation of the time in UTC,
overriding any previous specification for the timezone or the local
timezone.  The MINUTE part of the time of the day may not be elided
when a timezone correction is used.  This is the only way to specify a
timezone correction by fractional parts of an hour.

   Either `am'/`pm' or a timezone correction may be specified, but not
both.


File: tar.info,  Node: Timezone item,  Next: Day of week item,  Prev: Time of day item,  Up: Date input formats

Timezone Item
=============

   A "timezone item" specifies an international timezone, indicated by
a small set of letters.  Any included period is ignored.  Military
timezone designations use a single letter.  Currently, only integral
zone hours may be represented in a timezone item.  See the previous
section for a finer control over the timezone correction.

   Here are many non-daylight-savings-time timezones, indexed by the
zone hour value.

`+000'
     `GMT' for Greenwich Mean, `UT' or `UTC' for Universal
     (Coordinated), `WET' for Western European and `Z' for militaries.

`+100'
     `WAT' for West Africa and `A' for militaries.

`+200'
     `AT' for Azores and `B' for militaries.

`+300'
     `C' for militaries.

`+400'
     `AST' for Atlantic Standard and `D' for militaries.

`+500'
     `E' for militaries and `EST' for Eastern Standard.

`+600'
     `CST' for Central Standard and `F' for militaries.

`+700'
     `G' for militaries and `MST' for Mountain Standard.

`+800'
     `H' for militaries and `PST' for Pacific Standard.

`+900'
     `I' for militaries and `YST' for Yukon Standard.

`+1000'
     `AHST' for Alaska-Hawaii Standard, `CAT' for Central Alaska, `HST'
     for Hawaii Standard and `K' for militaries.

`+1100'
     `L' for militaries and `NT' for Nome.

`+1200'
     `IDLW' for International Date Line West and `M' for militaries.

`-100'
     `CET' for Central European, `FWT' for French Winter, `MET' for
     Middle European, `MEWT' for Middle European Winter, `N' for
     militaries and `SWT' for Swedish Winter.

`-200'
     `EET' for Eastern European, USSR Zone 1 and `O' for militaries.

`-300'
     `BT' for Baghdad, USSR Zone 2 and `P' for militaries.

`-400'
     `Q' for militaries and `ZP4' for USSR Zone 3.

`-500'
     `R' for militaries and `ZP5' for USSR Zone 4.

`-600'
     `S' for militaries and `ZP6' for USSR Zone 5.

`-700'
     `T' for militaries and `WAST' for West Australian Standard.

`-800'
     `CCT' for China Coast, USSR Zone 7 and `U' for militaries.

`-900'
     `JST' for Japan Standard, USSR Zone 8 and `V' for militaries.

`-1000'
     `EAST' for East Australian Standard, `GST' for Guam Standard, USSR
     Zone 9 and `W' for militaries.

`-1100'
     `X' for militaries.

`-1200'
     `IDLE' for International Date Line East, `NZST' for New Zealand
     Standard, `NZT' for New Zealand and `Y' for militaries.

   Here are many DST timezones, indexed by the zone hour value.  Also,
by following a non-DST timezone by the string `DST' in a separate word
(that is, separated by some whitespace), the corresponding DST timezone
may be specified.

`0'
     `BST' for British Summer.

`+400'
     `ADT' for Atlantic Daylight.

`+500'
     `EDT' for Eastern Daylight.

`+600'
     `CDT' for Central Daylight.

`+700'
     `MDT' for Mountain Daylight.

`+800'
     `PDT' for Pacific Daylight.

`+900'
     `YDT' for Yukon Daylight.

`+1000'
     `HDT' for Hawaii Daylight.

`-100'
     `MEST' for Middle European Summer, `MESZ' for Middle European
     Summer, `SST' for Swedish Summer and `FST' for French Summer.

`-700'
     `WADT' for West Australian Daylight.

`-1000'
     `EADT' for Eastern Australian Daylight.

`-1200'
     `NZDT' for New Zealand Daylight.


File: tar.info,  Node: Day of week item,  Next: Relative item in date strings,  Prev: Timezone item,  Up: Date input formats

Day of Week Item
================

   The explicit mention of a day of the week will forward the date
(only if necessary) to reach that day of the week in the future.

   Days of the week may be spelled out in full: `Sunday', `Monday',
`Tuesday', `Wednesday', `Thursday', `Friday' or `Saturday'.  Days may
be abbreviated to their first three letters, optionally followed by a
period.  The special abbreviations `Tues' for `Tuesday', `Wednes' for
`Wednesday' and `Thur' or `Thurs' for `Thursday' are also allowed.

   A number may precede a day of the week item to move forward
supplementary weeks.  It is best used in expression like `third
monday'.  In this context, `last DAY' or `next DAY' is also acceptable;
they move one week before or after the day that DAY by itself would
represent.

   A comma following a day of the week item is ignored.


File: tar.info,  Node: Relative item in date strings,  Next: Pure numbers in date strings,  Prev: Day of week item,  Up: Date input formats

Relative Item in Date Strings
=============================

   "Relative items" adjust a date (or the current date if none) forward
or backward.  The effect of relative items accumulate.  Here are some
examples:

     1 year
     1 year ago
     3 years
     2 days

   The unit of time displacement may be selected by the string `year'
or `month' for moving by whole years or months.  These are fuzzy units,
as years and months are not all of equal duration.  More precise units
are `fortnight' which is worth 14 days, `week' worth 7 days, `day'
worth 24 hours, `hour' worth 60 minutes, `minute' or `min' worth 60
seconds, and `second' or `sec' worth one second.  An `s' suffix on
these units is accepted and ignored.

   The unit of time may be preceded by a multiplier, given as an
optionally signed number.  Unsigned numbers are taken as positively
signed.  No number at all implies 1 for a multiplier.  Following a
relative item by the string `ago' is equivalent to preceding the unit
by a multiplicator with value -1.

   The string `tomorrow' is worth one day in the future (equivalent to
`day'), the string `yesterday' is worth one day in the past (equivalent
to `day ago').

   The strings `now' or `today' are relative items corresponding to
zero-valued time displacement, these strings come from the fact a
zero-valued time displacement represents the current time when not
otherwise change by previous items.  They may be used to stress other
items, like in `12:00 today'.  The string `this' also has the meaning
of a zero-valued time displacement, but is preferred in date strings
like `this thursday'.

   When a relative item makes the resulting date to cross the boundary
between DST and non-DST (or vice-versa), the hour is adjusted according
to the local time.


File: tar.info,  Node: Pure numbers in date strings,  Next: Authors of getdate,  Prev: Relative item in date strings,  Up: Date input formats

Pure Numbers in Date Strings
============================

   The precise intepretation of a pure decimal number is dependent of
the context in the date string.

   If the decimal number is of the form YYYYMMDD and no other calendar
date item (*note Calendar date item::.) appears before it in the date
string, then YYYY is read as the year, MM as the month number and DD as
the day of the month, for the specified calendar date.

   If the decimal number is of the form HHMM and no other time of day
item appears before it in the date string, then HH is read as the hour
of the day and MM as the minute of the hour, for the specified time of
the day.  MM can also be omitted.

   If both a calendar date and a time of day appear to the left of a
number in the date string, but no relative item, then the number
overrides the year.


File: tar.info,  Node: Authors of getdate,  Prev: Pure numbers in date strings,  Up: Date input formats

Authors of `getdate'
====================

   `getdate' was originally implemented by Steven M. Bellovin
(`smb@research.att.com') while at the University of North Carolina at
Chapel Hill.  The code was later tweaked by a couple of people on
Usenet, then completely overhauled by Rich $alz (`rsalz@bbn.com') and
Jim Berets (`jberets@bbn.com') in August, 1990.  Various revisions for
the GNU system were made by David MacKenzie, Jim Meyering, and others.

   Franc,ois Pinard (`pinard@iro.umontreal.ca') wrote the above
description out of the `getdate.y' source code, K. Berry
(`kb@cs.umb.edu') later edited it.


File: tar.info,  Node: Formats,  Next: Media,  Prev: Date input formats,  Up: Top

Controlling the Archive Format
******************************

* Menu:

* Portability::                 Making `tar' Archives More Portable
* Compression::                 Using Less Space through Compression
* Attributes::                  Handling File Attributes
* Standard::                    The Standard Format
* Extensions::                  GNU Extensions to the Archive Format
* cpio::                        Comparison of `tar' and `cpio'


File: tar.info,  Node: Portability,  Next: Compression,  Prev: Formats,  Up: Formats

Making `tar' Archives More Portable
===================================

   Creating a `tar' archive on a particular system that is meant to be
useful later on many other machines and with other versions of `tar' is
more challenging than you might think.  `tar' archive formats have been
evolving since the first versions of Unix.  Many such formats are
around, and are not always comptible with each other.  This section
discusses a few problems, and gives some advice about making `tar'
archives more portable.

   One golden rule is simplicity.  For example, limit your `tar'
archives to contain only regular files and directories, avoiding other
kind of special files.  Do not attempt to save sparse files or
contiguous files as such.  Let's discuss a few more problems, in turn.

* Menu:

* Portable Names::              Portable Names
* dereference::                 Symbolic Links
* old::                         Old V7 Archives
* posix::                       POSIX archives
* Checksumming::                Checksumming Problems


File: tar.info,  Node: Portable Names,  Next: dereference,  Prev: Portability,  Up: Portability

Portable Names
--------------

   Use *straight* file and directory names, made up of printable ASCII
characters, avoiding colons, slashes, backslashes, spaces, and other
*dangerous* characters.  Avoid deep directory nesting.  Accounting for
oldish System V machines, limit your file and directory names to 14
characters or less.

   If you intend to have your `tar' archives to be read under MS-DOS,
you should not rely on case distinction for file names, and you might
use the GNU `doschk' program for helping you further diagnosing illegal
MS-DOS names, which are even more limited than System V's.  `tar'
compiled for MS-DOS *does* try to cope with filenames which are illegal
on MS-DOS file systems (*note Basic tar::.), but the best portability
strategy is to avoid such problems in the first place.  Even newer
versions of MS-Windows, such as Windows 9X and Windows/NT, still have
some restrictions on characters which can appear in a file name.
Typically, characters which are special to the shell, like `?', `*' and
`|' are not allowed and should be avoided.


File: tar.info,  Node: dereference,  Next: old,  Prev: Portable Names,  Up: Portability

Symbolic Links
--------------

   Normally, when `tar' archives a symbolic link, it writes a block to
the archive naming the target of the link.  In that way, the `tar'
archive is a faithful record of the filesystem contents.
`--dereference' (`-h') is used with `--create' (`-c'), and causes `tar'
to archive the files symbolic links point to, instead of the links
themselves.  When this option is used, when `tar' encounters a symbolic
link, it will archive the linked-to file, instead of simply recording
the presence of a symbolic link.

   The name under which the file is stored in the file system is not
recorded in the archive.  To record both the symbolic link name and the
file name in the system, archive the file under both names.  If all
links were recorded automatically by `tar', an extracted file might be
linked to a file name that no longer exists in the file system.

   If a linked-to file is encountered again by `tar' while creating the
same archive, an entire second copy of it will be stored.  (This
*might* be considered a bug.)

   So, for portable archives, do not archive symbolic links as such,
and use `--dereference' (`-h'): many systems do not support symbolic
links, and moreover, your distribution might be unusable if it contains
unresolved symbolic links.


File: tar.info,  Node: old,  Next: posix,  Prev: dereference,  Up: Portability

Old V7 Archives
---------------

   Certain old versions of `tar' cannot handle additional information
recorded by newer `tar' programs.  To create an archive in V7 format
(not ANSI), which can be read by these old versions, specify the
`--old-archive' (`-o') option in conjunction with the `--create'
(`-c').  `tar' also accepts `--portability' for this option.  When you
specify it, `tar' leaves out information about directories, pipes,
fifos, contiguous files, and device files, and specifies file ownership
by group and user IDs instead of group and user names.

   When updating an archive, do not use `--old-archive' (`-o') unless
the archive was created using this option.

   In most cases, a *new* format archive can be read by an *old* `tar'
program without serious trouble, so this option should seldom be
needed.  On the other hand, most modern `tar's are able to read old
format archives, so it might be safer for you to always use
`--old-archive' (`-o') for your distributions.


File: tar.info,  Node: posix,  Next: Checksumming,  Prev: old,  Up: Portability

GNU `tar' and POSIX `tar'
-------------------------

   GNU `tar' was based on an early draft of the POSIX 1003.1 `ustar'
standard.  GNU extensions to `tar', such as the support for file names
longer than 100 characters, use portions of the `tar' header record
which were specified in that POSIX draft as unused.  Subsequent changes
in POSIX have allocated the same parts of the header record for other
purposes.  As a result, GNU `tar' is incompatible with the current
POSIX spec, and with `tar' programs that follow it.

   We plan to reimplement these GNU extensions in a new way which is
upward compatible with the latest POSIX `tar' format, but we don't know
when this will be done.

   In the mean time, there is simply no way of telling what might
happen if you read a GNU `tar' archive, which uses the GNU extensions,
using some other `tar' program.  So if you want to read the archive
with another `tar' program, be sure to write it using the
`--old-archive' option (`-o').

   Traditionally, old `tar's have a limit of 100 characters.  GNU `tar'
attempted two different approaches to overcome this limit, using and
extending a format specified by a draft of some P1003.1.  The first way
was not that successful, and involved `@MaNgLeD@' file names, or such;
while a second approach used `././@LongLink' and other tricks, yielding
better success.  In theory, GNU `tar' should be able to handle file
names of practically unlimited length.  So, if GNU `tar' fails to dump
and retrieve files having more than 100 characters, then there is a bug
in GNU `tar', indeed.

   But, being strictly POSIX, the limit was still 100 characters.  For
various other purposes, GNU `tar' used areas left unassigned in the
POSIX draft.  POSIX later revised P1003.1 `ustar' format by assigning
previously unused header fields, in such a way that the upper limit for
file name length was raised to 256 characters.  However, the actual
POSIX limit oscillates between 100 and 256, depending on the precise
location of slashes in full file name (this is rather ugly).  Since GNU
`tar' use the same fields for quite other purposes, it became
incompatible with the latest POSIX standards.

   For longer or non-fitting file names, we plan to use yet another set
of GNU extensions, but this time, complying with the provisions POSIX
offers for extending the format, rather than conflicting with it.
Whenever an archive uses old GNU `tar' extension format or POSIX
extensions, would it be for very long file names or other specialities,
this archive becomes non-portable to other `tar' implementations.  In
fact, anything can happen.  The most forgiving `tar's will merely
unpack the file using a wrong name, and maybe create another file named
something like `@LongName', with the true file name in it.  `tar's not
protecting themselves may segment violate!

   Compatibility concerns make all this thing more difficult, as we
will have to support *all* these things together, for a while.  GNU
`tar' should be able to produce and read true POSIX format files, while
being able to detect old GNU `tar' formats, besides old V7 format, and
process them conveniently.  It would take years before this whole area
stabilizes...

   There are plans to raise this 100 limit to 256, and yet produce POSIX
conformant archives.  Past 256, I do not know yet if GNU `tar' will go
non-POSIX again, or merely refuse to archive the file.

   There are plans so GNU `tar' support more fully the latest POSIX
format, while being able to read old V7 format, GNU (semi-POSIX plus
extension), as well as full POSIX.  One may ask if there is part of the
POSIX format that we still cannot support.  This simple question has a
complex answer.  Maybe that, on intimate look, some strong limitations
will pop up, but until now, nothing sounds too difficult (but see
below).  I only have these few pages of POSIX telling about `Extended
tar Format' (P1003.1-1990 - section 10.1.1), and there are references
to other parts of the standard I do not have, which should normally
enforce limitations on stored file names (I suspect things like fixing
what `/' and `<NUL>' means).  There are also some points which the
standard does not make clear.  Existing practice will then drive what I
should do.

   POSIX mandates that, when a file name cannot fit within 100 to 256
characters (the variance comes from the fact a `/' is ideally needed as
the 156'th character), or a link name cannot fit within 100 characters,
a warning should be issued and the file *not* be stored.  Unless some
`--posix' option is given (or `POSIXLY_CORRECT' is set), I suspect that
GNU `tar' should disobey this specification, and automatically switch
to using GNU extensions to overcome file name or link name length
limitations.

   There is a problem, however, which I have not intimately studied yet.
Given a truly POSIX archive with names having more than 100 characters,
I guess that GNU `tar' up to 1.11.8 will process it as if it were an
old V7 archive, and be fooled by some fields which are coded
differently.  So, the question is to decide if the next generation of
GNU `tar' should produce POSIX format by default, whenever possible,
producing archives older versions of GNU `tar' might not be able to read
correctly.  I fear that we will have to suffer such a choice one of
these days, if we want GNU `tar' to go closer to POSIX.  We can rush it.
Another possibility is to produce the current GNU `tar' format by
default for a few years, but have GNU `tar' versions from some 1.POSIX
and up able to recognize all three formats, and let older GNU `tar'
fade out slowly.  Then, we could switch to producing POSIX format by
default, with not much harm to those still having (very old at that
time) GNU `tar' versions prior to 1.POSIX.

   POSIX format cannot represent very long names, volume headers,
splitting of files in multi-volumes, sparse files, and incremental
dumps; these would be all disallowed if `--posix' or `POSIXLY_CORRECT'.
Otherwise, if `tar' is given long names, or `-[VMSgG]', then it should
automatically go non-POSIX.  I think this is easily granted without
much discussion.

   Another point is that only `mtime' is stored in POSIX archives,
while GNU `tar' currently also store `atime' and `ctime'.  If we want
GNU `tar' to go closer to POSIX, my choice would be to drop `atime' and
`ctime' support on average.  On the other hand, I perceive that full
dumps or incremental dumps need `atime' and `ctime' support, so for
those special applications, POSIX has to be avoided altogether.

   A few users requested that `--sparse' (`-S') be always active by
default, I think that before replying to them, we have to decide if we
want GNU `tar' to go closer to POSIX on average, while producing files.
My choice would be to go closer to POSIX in the long run.  Besides
possible double reading, I do not see any point of not trying to save
files as sparse when creating archives which are neither POSIX nor
old-V7, so the actual `--sparse' (`-S') would become selected by
default when producing such archives, whatever the reason is.  So,
`--sparse' (`-S') alone might be redefined to force GNU-format
archives, and recover its previous meaning from this fact.

   GNU-format as it exists now can easily fool other POSIX `tar', as it
uses fields which POSIX considers to be part of the file name prefix.
I wonder if it would not be a good idea, in the long run, to try
changing GNU-format so any added field (like `ctime', `atime', file
offset in subsequent volumes, or sparse file descriptions) be wholly
and always pushed into an extension block, instead of using space in
the POSIX header block.  I could manage to do that portably between
future GNU `tar's.  So other POSIX `tar's might be at least able to
provide kind of correct listings for the archives produced by GNU
`tar', if not able to process them otherwise.

   Using these projected extensions might induce older `tar's to fail.
We would use the same approach as for POSIX.  I'll put out a `tar'
capable of reading POSIXier, yet extended archives, but will not produce
this format by default, in GNU mode.  In a few years, when newer GNU
`tar's will have flooded out `tar' 1.11.X and previous, we could switch
to producing POSIXier extended archives, with no real harm to users, as
almost all existing GNU `tar's will be ready to read POSIXier format.
In fact, I'll do both changes at the same time, in a few years, and
just prepare `tar' for both changes, without effecting them, from
1.POSIX.  (Both changes: 1--using POSIX convention for getting over 100
characters; 2--avoiding mangling POSIX headers for GNU extensions,
using only POSIX mandated extension techniques).

   So, a future `tar' will have a `--posix' flag forcing the usage of
truly POSIX headers, and so, producing archives previous GNU `tar' will
not be able to read.  So, *once* pretest will announce that feature, it
would be particularly useful that users test how exchangeable will be
archives between GNU `tar' with `--posix' and other POSIX `tar'.

   In a few years, when GNU `tar' will produce POSIX headers by
default, `--posix' will have a strong meaning and will disallow GNU
extensions.  But in the meantime, for a long while, `--posix' in GNU
tar will not disallow GNU extensions like `--label=ARCHIVE-LABEL' (`-V
ARCHIVE-LABEL'), `--multi-volume' (`-M'), `--sparse' (`-S'), or very
long file or link names.  However, `--posix' with GNU extensions will
use POSIX headers with reserved-for-users extensions to headers, and I
will be curious to know how well or bad POSIX `tar's will react to
these.

   GNU `tar' prior to 1.POSIX, and after 1.POSIX without `--posix',
generates and checks `ustar  ', with two suffixed spaces.  This is
sufficient for older GNU `tar' not to recognize POSIX archives, and
consequently, wrongly decide those archives are in old V7 format.  It
is a useful bug for me, because GNU `tar' has other POSIX
incompatibilities, and I need to segregate GNU `tar' semi-POSIX
archives from truly POSIX archives, for GNU `tar' should be somewhat
compatible with itself, while migrating closer to latest POSIX
standards.  So, I'll be very careful about how and when I will do the
correction.


File: tar.info,  Node: Checksumming,  Prev: posix,  Up: Portability

Checksumming Problems
---------------------

   SunOS and HP-UX `tar' fail to accept archives created using GNU
`tar' and containing non-ASCII file names, that is, file names having
characters with the eight bit set, because they use signed checksums,
while GNU `tar' uses unsigned checksums when creating archives, as per
POSIX standards.  On reading, GNU `tar' computes both checksums and
accept any.  It is somewhat worrying that a lot of people may go around
doing backup of their files using faulty (or at least non-standard)
software, not learning about it until it's time to restore their
missing files with an incompatible file extractor, or vice versa.

   GNU `tar' computes checksums both ways, and accept any on read, so
GNU tar can read Sun tapes even with their wrong checksums.  GNU `tar'
produces the standard checksum, however, raising incompatibilities with
Sun.  That is to say, GNU `tar' has not been modified to *produce*
incorrect archives to be read by buggy `tar's.  I've been told that
more recent Sun `tar' now read standard archives, so maybe Sun did a
similar patch, after all?

   The story seems to be that when Sun first imported `tar' sources on
their system, they recompiled it without realizing that the checksums
were computed differently, because of a change in the default signing
of `char's in their compiler.  So they started computing checksums
wrongly.  When they later realized their mistake, they merely decided
to stay compatible with it, and with themselves afterwards.
Presumably, but I do not really know, HP-UX has chosen that their `tar'
archives to be compatible with Sun's.  The current standards do not
favor Sun `tar' format.  In any case, it now falls on the shoulders of
SunOS and HP-UX users to get a `tar' able to read the good archives
they receive.


File: tar.info,  Node: Compression,  Next: Attributes,  Prev: Portability,  Up: Formats

Using Less Space through Compression
====================================

* Menu:

* gzip::                        Creating and Reading Compressed Archives
* sparse::                      Archiving Sparse Files

