Find file
Fetching contributors…
Cannot retrieve contributors at this time
1331 lines (1023 sloc) 48.3 KB
This is, produced by makeinfo version 3.12i from
* pax utilities: (paxutils). pax and other archiving utilities.
* cpio: (paxutils)cpio invocation. Handling cpio archives.
* pax: (paxutils)pax invocation. The POSIX archiver.
* tar: (paxutils)tar invocation. Making tape (or disk) archives.
* mt: (paxutils)mt invocation. Basic tape positioning.
* rmt: (paxutils)rmt invocation. The remote tape facility.
This file documents `paxutils' 2.4i.
Copyright (C) 1992, 1994, 1995, 1996, 1997, 1998 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.

File:, Node: Full dumps, Next: Incremental dumps, Prev: Backup levels, Up: Backup levels
Using `tar' to perform full dumps
Full dumps should only be made when no other people or programs are
modifying files in the filesystem. If files are modified while `tar'
is making the backup, they may not be stored properly in the archive,
in which case you won't be able to restore them if you have to. (Files
being modified are written with no trouble, and do not corrupt the
entire archive.)
You will want to use the `--label=ARCHIVE-LABEL' (`-V
ARCHIVE-LABEL') option to give the archive a volume label, so you can
tell what this archive is even if the label falls off the tape, or
anything like that.
Unless the filesystem you are dumping is guaranteed to fit on one
volume, you will need to use the `--multi-volume' (`-M') option. Make
sure you have enough tapes on hand to complete the backup.
If you want to dump each filesystem separately you will need to use
the `--one-file-system' (`-l') option to prevent `tar' from crossing
filesystem boundaries when storing (sub)directories.
The `--incremental' (`-G') option is not needed, since this is a
complete copy of everything in the filesystem, and a full restore from
this backup would only be done onto a completely empty disk.
Unless you are in a hurry, and trust the `tar' program (and your
tapes), it is a good idea to use the `--verify' (`-W') option, to make
sure your files really made it into the dump properly. This will also
detect cases where the file was modified while (or just after) it was
being archived. Not all media (notably cartridge tapes) are capable of
being verified, unfortunately.
`--listed-incremental=SNAPSHOT-FILE' (`-g SNAPSHOT-FILE') always
takes a file name argument. If the file doesn't exist, `tar' runs a
level zero dump, creating the file. If the file exists, `tar' uses
that file to see what has changed.
`--incremental' (`-G') handles old extended format incremental
The `--incremental' (`-G') option means the archive is an incremental
backup. Its meaning depends on the command that it modifies.
When this option is used for creating an incremental backup of a
filesystem, `tar' writes, at the beginning of the archive, an entry for
each of the directories that will be operated on. The entry for a
directory includes a list of all the files in the directory at the time
the dump was done, and a flag for each file indicating whether the file
is going to be put in the archive. This information is used when doing
a complete incremental restore.
Note that this option causes `tar' to create a non-standard archive
that may not be readable by other versions of the `tar' program.
If the `--incremental' (`-G') option is used with `--list' (`-t'),
`tar' will list, for each directory in the archive, the list of files in
that directory at the time the archive was created. This information
is put out in a format that is not easy for humans to read, but which
is unambiguous for a program: each file name is preceded by either a
`Y' if the file is present in the archive, an `N' if the file is not
included in the archive, or a `D' if the file is a directory (and is
included in the archive). Each file name is terminated by a null
character. The last file is followed by an additional null and a
newline to indicate the end of the data.
If the `--incremental' (`-G') option is used with `--extract'
(`--get', `-x'), then when the entry for a directory is found, all
files that currently exist in that directory but are not listed in the
archive _are deleted from the directory_.
This behavior is convenient when you are restoring a damaged file
system from a succession of incremental backups: it restores the entire
state of the file system to that which obtained when the backup was
made. If you don't use `--incremental' (`-G'), the file system will
probably fill up with files that shouldn't exist any more.
`--listed-incremental=SNAPSHOT-FILE' (`-g SNAPSHOT-FILE') handles
new extended format incremental backup.
`--listed-incremental=SNAPSHOT-FILE' (`-g SNAPSHOT-FILE') acts like
`--incremental' (`-G'), but when used in conjunction with `--create'
(`-c') will also cause `tar' to use the file FILE, which contains
information about the state of the filesystem at the time of the last
backup, to decide which files to include in the archive being created.
That file will then be updated by `tar'. If the file FILE does not
exist when this option is specified, `tar' will create it, and include
all appropriate files in the archive.
The file, which is archive independent, contains the date it was last
modified and a list of devices, inode numbers and directory names.
`tar' will archive files with newer mod dates or inode change times,
and directories with an unchanged inode number and device but a changed
directory name. The file is updated after the files to be archived are
determined, but before the new archive is actually created.
When restoring, only files newer than the saved time are restored,
and the directory list is used to speed up subcommands.
`tar' actually writes the file twice: once before the data is
written, and once after.

File:, Node: Incremental dumps, Prev: Full dumps, Up: Backup levels
Using `tar' to perform incremental dumps
Performing incremental dumps is similar to performing full dumps,
although a few more options will usually be needed.
You will need to use the `-N DATE' option to tell `tar' to only
store files that have been modified since DATE. DATE should be the
date and time of the last full/incremental dump. *Note after-date::.
A standard scheme is to do a _monthly_ (full) dump once a month, a
_weekly_ dump once a week of everything since the last monthly, and a
_daily_ dump every day of everything since the last (weekly or monthly)
Here is a copy of the script used to dump the filesystems of the
machines here at the Free Software Foundation. This script is run via
`cron' late at night when people are least likely to be using the
machines. This script dumps several filesystems from several machines
at once (via NFS). The operator is responsible for ensuring that all
the machines will be up at the time the dump happens. If a machine is
not running, its files will not be dumped, and the next day's
incremental dump will _not_ store files that would have gone onto that
# Dump thingie
set now = `date`
set then = `cat date.nfs.dump`
/u/hack/bin/tar -c -G -v\
-f /dev/rtu20\
-b 126\
-N "$then"\
-V "Dump from $then to $now"\
echo $now > date.nfs.dump
mt -f /dev/rtu20 rew
Output from this script is stored in a file, for the operator to
read later.
This script uses the file `date.nfs.dump' to store the date and time
of the last dump.
Since this is a streaming tape drive, no attempt to verify the
archive is made. This is also why the high blocking factor (126) is
used. The tape drive must also be rewound by the `mt' command after
the dump is made.

File:, Node: Backup parameters, Next: Scripted backups, Prev: Backup levels, Up: Backups
Setting parameters for backups and restoration
The file `backup-specs' specifies backup parameters for the backup
and restoration scripts provided with `tar'. You must edit
`backup-specs' to fit your system configuration and schedule before
using these scripts.
*Note Script syntax::, for an explanation of this syntax.
`backup-specs' specifies the following parameters:
The user name of the backup administrator.
The hour at which the backups are done. This can be a number from
0 to 23, or the string `now'.
The device `tar' writes the archive to. This device should be
attached to the host on which the dump scripts are run.
The command to use to obtain the status of the archive device,
including error count. On some tape drives there may not be such a
command; in that case, simply use `TAPE_STATUS=false'.
The blocking factor `tar' will use when writing the dump archive.
*Note blocking-factor::.
A list of file systems to be dumped. You can include any directory
name in the list--subdirectories on that file system will be
included, regardless of how they may look to other networked
machines. Subdirectories on other file systems will be ignored.
The host name specifies which host to run `tar' on, and should
normally be the host that actually contains the file system.
However, the host machine must have `tar' installed, and must be
able to access the directory containing the backup scripts and
their support files using the same file name that is used on the
machine where the scripts are run (that is, what `pwd' will print
when in that directory on that machine). If the host that
contains the file system does not have this capability, you can
specify another host as long as it can access the file system
through NFS.
A list of individual files to be dumped. These should be
accessible from the machine on which the backup script is run.
* Menu:
* backup-specs example:: An example text of `backup-specs'
* Script syntax:: Syntax for `backup-specs'

File:, Node: backup-specs example, Next: Script syntax, Prev: Backup parameters, Up: Backup parameters
An example text of `backup-specs'
The following is the text of `backup-specs' as it appears at FSF:
# site-specific parameters for file system backup.
BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]"

File:, Node: Script syntax, Prev: backup-specs example, Up: Backup parameters
Syntax for `backup-specs'
`backup-specs' is in shell script syntax. The following conventions
should be considered when editing the script:
A quoted string is considered to be contiguous, even if it is on more
than one line. Therefore, you cannot include commented-out lines
within a multi-line quoted string. BACKUP_FILES and BACKUP_DIRS are
the two parameters most likely to be multi-line.
A quoted string typically cannot contain wildcards. In
`backup-specs', however, the parameters BACKUP_DIRS and BACKUP_FILES
can contain wildcards.

File:, Node: Scripted backups, Next: Scripted restoration, Prev: Backup parameters, Up: Backups
Using the backup scripts
The syntax for running a backup script named SCRIPT-NAME is:
where TIME-TO-BE-RUN can be a specific system time, or can be `now'.
If you do not specify a time, the script runs at the time specified in
`backup-specs' (*note Script syntax::.).
You should start a script with a tape or disk mounted. Once you
start a script, it prompts you for new tapes or disks as it needs them.
Media volumes don't have to correspond to archive files--a
multi-volume archive can be started in the middle of a tape that
already contains the end of another multi-volume archive. The
`restore' script prompts for media by its archive volume, so to avoid
an error message you should keep track of which tape (or disk) contains
which volume of the archive. *Note Scripted restoration::.
The backup scripts write two files on the file system. The first is
a record file in `/etc/tar-backup/', which is used by the scripts to
store and retrieve information about which files were dumped. This
file is not meant to be read by humans, and should not be deleted by
them. *Note incremental listed-incremental::, for a more detailed
explanation of this file.
The second file is a log file containing the names of the file
systems and files dumped, the time when the backup was made, and any
error messages that were generated, as well as how much space was left
in the media volume after the last volume of the archive was written.
You should check this log file after every backup. The file name is
`log-MMM-DDD-YYYY-level-1' or `log-MMM-DDD-YYYY-full'.
The script also prints the name of each system being dumped to the
standard output.

File:, Node: Scripted restoration, Prev: Scripted backups, Up: Backups
Using the restore script
*Warning:* The `tar' distribution does _not_ provide any such
`restore' script yet. This section is only listed here for
documentation maintenance purposes. In any case, all contents are
subject to change as things develop.
To restore files that were archived using a scripted backup, use the
`restore' script. The syntax for the script is:
where ***** are the file systems to restore from, and ***** is a
regular expression which specifies which files to restore. If you
specify `--all', the script restores all the files in the file system.
You should start the restore script with the media containing the
first volume of the archive mounted. The script will prompt for other
volumes as they are needed. If the archive is on tape, you don't need
to rewind the tape to its beginning--if the tape head is positioned
past the beginning of the archive, the script will rewind the tape as
needed. *Note Media::, for a discussion of tape positioning.
If you specify `--all' as the FILES argument, the `restore' script
extracts all the files in the archived file system into the active file
*Warning:* The script will delete files from the active file
system if they were not in the file system when the archive was
*Note incremental::, and *Note listed-incremental::, for an
explanation of how the script makes that determination.

File:, Node: All options, Next: Date input formats, Prev: Backups, Up: Top
All `tar' options
This appendix contain an alphabetical listing of all `tar'
subcommands and options, with brief descriptions and cross-references
to more in-depth explanations in the body of the manual. It also
contains an alphabetically arranged table of the short option forms
with their corresponding long option. You can use this table as a
reference for deciphering `tar' commands in scripts.
* Menu:
* Subcommand summary:: Subcommands
* Option summary:: `tar' options
* Short option summary:: Short options cross-reference

File:, Node: Subcommand summary, Next: Option summary, Prev: All options, Up: All options
Any particular division of all options into subcommands and
fine-tuning options is debatable, and surely subject to change. The
following table gives a particular view, which may help users to
acquire a better grasp of the main operating modes for `tar'.
`--append' (`-r')
Appends files to the end of the archive. *Note append::.
Same as `--concatenate'. *Note concatenate::.
`--compare' (`--diff', `-d')
Compares archive members with their counterparts in the file
system, and reports differences in file size, mode, owner,
modification date and contents. *Note compare::.
`--concatenate' (`--catenate', `-A')
Appends other `tar' archives to the end of the archive. *Note
`--create' (`-c')
Creates a new `tar' archive. *Note create::.
Deletes members from the archive. Don't try this on an archive on
a magnetic tape! *Note delete::.
Same as `--compare'. *Note compare::.
`--extract' (`--get', `-x')
Extracts members from the archive into the file system. *Note
Same as `--extract'. *Note extract::.
`--list' (`-t')
Lists the members in an archive. *Note list::.
`--update' (`-u')
Adds files to the end of the archive, but only if they are newer
than their counterparts already in the archive, or if they do not
already exist in the archive. *Note update::.

File:, Node: Option summary, Next: Short option summary, Prev: Subcommand summary, Up: All options
`tar' options
Here is an alphabetical listing of all options accepted by `tar',
whether they appear or not in the summary of subcommands (*note
Subcommand summary::.. Each option is accompanied by a reference to
where it is more fully explained.
Specify drive and density. *Note lmh::.
`--absolute-names' (`-P')
Normally when creating an archive, `tar' converts absolute file
names to relative, by stripping an initial `/' from member names
(on MS-DOS and MS-Windows, `tar' also strips the drive letter and
the colon that follows it). This option disables that behavior.
*Note absolute-names::.
This obsolete option has been replaced with `--absolute-names'.
`--after-date=DATE' (`--newer=DATE', `-N DATE')
When creating an archive, `tar' will only add files that have
changed since DATE. *Note after-date::.
`--append' (`-r')
Appends files to the end of the archive. *Note append::.
Tells `tar' to preserve the access (and modification) times field
in a file's inode when dumping it. *Note atime-preserve::.
Rather than deleting files from the file system, `tar' will back
them up using simple or numbered backups, depending upon METHOD.
*Note backup::.
This obsolete option has been deleted, as `tar' now decides
automatically about when to reblock the output of the compression
`--block-number' (`-R')
With this option present, `tar' prints error messages for read
errors with the block number in the archive file. *Note
This obsolete option has been replaced by `--blocking-factor'.
`--blocking-factor=BLOCKS' (`-b BLOCKS')
Sets the blocking factor `tar' uses to BLOCKING x 512 bytes per
record. *Note blocking-factor::.
Same as `--concatenate'. *Note concatenate::.
This option directs `tar' to print periodic checkpoint messages as
it reads through the archive. *Note checkpoint::.
`--compare' (`--diff', `-d')
Compares archive members with their counterparts in the file
system, and reports differences in file size, mode, owner,
modification date, and contents. *Note compare::.
`--compress' (`-Z')
`tar' will use the `compress' program when reading or writing the
archive. This allows you to act directly on archives while saving
space. *Note compress::.
`--concatenate' (`--catenate', `-A')
Appends other `tar' archives to the end of the archive. *Note
Same as `--interactive'. *Note interactive::.
`--create' (`-c')
Creates a new `tar' archive. *Note create::.
Deletes members from the archive. Don't try this on an archive on
a magnetic tape! *Note delete::.
`--dereference' (`-h')
When creating a `tar' archive, `tar' will archive the file that a
symbolic link points to, rather than archiving the symlink. *Note
Same as `--compare'. *Note compare::.
`--directory=DIRECTORY' (`-C DIRECTORY')
When this option is specified, `tar' will change its current
directory to DIR before performing any subcommands. When this
option is used during archive creation, it is order-sensitive.
*Note directory::.
When performing subcommands, `tar' will skip files that match
PATTERN. *Note exclude::.
Similar to `--exclude', except that `tar' will use the list of
patterns in the file FILE. *Note exclude-from::.
`--extract' (`--get', `-x')
Extracts members from the archive into the file system. *Note
`tar' will use the file ARCHIVE as the `tar' archive it performs
subcommands on, rather than `tar''s compilation-dependent default.
*Note file::.
`--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES')
`tar' will use the contents of FILE as a list of archive members
or files to operate on, in addition to those specified on the
command line. *Note files-from::.
Forces `tar' to interpret the filename given to
`--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') as a local file, even if
it looks like a remote tape drive name. *Note force-local::.
Same as `--extract'. *Note extract::.
Files added to the `tar' archive will have a group id of GROUP,
rather than the group from the source file. *Note group::.
This obsolete option has been replaced by `--gzip'.
`--gzip' (`-z')
This option tells `tar' to read or write archives through `gzip',
allowing `tar' to directly operate on several kinds of compressed
archives transparently. *Note gzip::.
`tar' will print out a short message summarizing the subcommands
and options to `tar' and exit. *Note help::.
Instructs `tar' to exit successfully if it encounters an
unreadable file. *Note ignore-failed-read::.
`--ignore-zeros' (`-i')
With this option, `tar' will ignore zeroed blocks in the archive,
which normally signals the end of the archive file. *Note
`--incremental' (`-G')
Used to inform `tar' that it is working with an old extended format
incremental backup archive. It is intended primarily for backward
compatibility. *Note incremental::.
`--info-script=SCRIPT-NAME' (`--new-volume-script=SCRIPT-NAME', `-F SCRIPT-NAME')
When `tar' is performing multi-tape backups, SCRIPT-NAME is run at
the end of each tape. *Note info-script::.
`--interactive' (`--confirmation', `-w')
Specifies that `tar' should ask the user for confirmation before
performing potentially destructive operations, such as overwriting
files. *Note interactive::.
`--keep-old-files' (`-k')
When extracting files from an archive, `tar' will not overwrite
existing files if this option is present. *Note keep-old-files::.
When creating an archive, instructs `tar' to write NAME as a name
record in the archive. When extracting or listing archives, `tar'
will only operate on archives that have a label matching the
pattern specified in NAME. *Note label::.
`--list' (`-t')
Lists the members in an archive. *Note list::.
`--listed-incremental=SNAPSHOT-FILE' (`-g SNAPSHOT-FILE')
During a `--create' (`-c') subcommand, specifies that the archive
that `tar' creates is a new extended format incremental backup,
using SNAPSHOT-FILE to determine which files to backup. With other
subcommands, informs `tar' that the archive is in incremental
format. *Note listed-incremental::.
When adding files to an archive, `tar' will use PERMISSIONS for
the archive members, rather than the permissions from the files.
*Note mode::.
This obsolete option has been replaced by `--touch'.
`--multi-volume' (`-M')
Informs `tar' that it should create or otherwise operate on a
multi-volume `tar' archive. *Note multi-volume::.
To prepend the given prefix to each archive file name as it is
gathered into the archive. This prefix won't show in any
`--verbose' (`-v') progress message, but it will if you list the
archive. *Note name-prefix::.
Same as `--info-script'. *Note info-script::.
Same as `--after-date'. *Note after-date::.
`tar' will only add files whose contents have changed (as opposed
to just `--after-date', which will also back up files for which
any status information has changed). On MS-DOS, where there is
only one time stamp for a file, `--after-date' and `--newer-mtime'
have identical effect. *Note newer-mtime::.
`tar' will not try restoring any file attribute while extracting
files. This option might disappear in some later version. *Note
With this option, `tar' will not recurse into directories unless a
directory is explicitly named as an argument to `tar'. *Note
When `tar' is using the `--files-from=FILE-OF-NAMES' (`-T
FILE-OF-NAMES') option, this option instructs `tar' to expect
filenames terminated with `NUL', so `tar' can correctly work with
file names that contain newlines. *Note null::.
This option will notify `tar' that it should use numeric user and
group IDs when creating a `tar' file, rather than names. *Note
`--old-archive' (`-o')
Tells `tar' to create an archive that is compatible with Unix V7
`tar'. *Note old-archive::.
`--one-file-system' (`-l')
Used when creating an archive. Prevents `tar' from recursing into
directories that are on different file systems from the current
directory. *Note one-file-system::.
Specifies that `tar' should use USER as the owner of members when
creating archives, instead of the user associated with the source
file. *Note owner::.
Same as `--old-archive'. *Note old-archive::.
Instructs `tar' to create a POSIX compliant `tar' archive. *Note
Synonymous with specifying both `--same-permissions' and
`--same-order'. *Note preserve::.
Same as `--same-order'. *Note same-order::.
Same as `--same-permissions'. *Note same-permissions::.
This obsolete option has been replaced by `--read-full-records'.
`--read-full-records' (`-B')
Specifies that `tar' should reblock its input, for reading from
pipes on systems with buggy implementations. *Note
This obsolete option has been replaced by `--block-number'.
Instructs `tar' to use SIZE bytes per record when accessing the
archive. *Note record-size::.
Similar to the `--unlink-first' (`-U') option, removing existing
directory hierarchies before extracting directories of the same
name from the archive. *Note recursive-unlink::.
Directs `tar' to remove the source file from the file system after
appending it to an archive. *Note remove-files::.
Notifies `tar' that is should use CMD to communicate with remote
devices. *Note rsh-command::.
`--same-order' (`--preserve-order', `-s')
This option is an optimization for `tar' when running on machines
with small amounts of memory. It informs `tar' that the list of
file arguments has already been sorted to match the order of files
in the archive. *Note same-order::.
When extracting an archive, `tar' will attempt to preserve the
owner specified in the `tar' archive with this option present.
*Note same-owner::.
`--same-permissions' (`--preserve-permissions', `-p')
When `tar' is extracting an archive, it normally subtracts the
user's umask from the permissions specified in the archive and
uses that number as the permissions to create the destination
file. Specifying this option instructs `tar' that it should use
the permissions directly from the archive. *Note
Instructs `tar' to mention directories it's skipping over when
operating on a `tar' archive. *Note show-omitted-dirs::.
`--sparse' (`-S')
Invokes an extended format when adding files to an archive that
handles sparse files efficiently. *Note sparse::.
`--starting-file=NAME' (`-K NAME')
This option affects extraction only; `tar' will skip extracting
files in the archive until it finds one that matches NAME. *Note
Alters the suffix `tar' uses when backing up files from the default
`~'. *Note suffix::.
`--tape-length=KBYTES' (`-L KBYTES')
Specifies the length of tapes that `tar' is writing as NUM x 1024
bytes long. *Note tape-length::.
`--to-stdout' (`-O')
During extraction, `tar' will extract files to stdout rather than
to the file system. *Note to-stdout::.
Displays the total number of bytes written after creating an
archive. *Note totals::.
`--touch' (`-m')
Sets the modification time of extracted files to the extraction
time, rather than the modification time stored in the archive.
*Note touch::.
This obsolete option has been replaced with `--compress'.
This obsolete option has been replaced with `--gzip'.
`--unlink-first' (`-U')
Directs `tar' to remove the corresponding file from the file system
before extracting it from the archive. *Note unlink-first::.
`--update' (`-u')
Adds files to the end of the archive, but only if they are newer
than their counterparts already in the archive, or if they do not
already exist in the archive. *Note update::.
Instructs `tar' to access the archive through PROG, which is
presumed to be a compression program of some sort. *Note
`--verbose' (`-v')
Specifies that `tar' should be more verbose about the subcommands
it is performing. This option can be specified multiple times for
some subcommands to increase the amount of information displayed.
*Note verbose::.
`--verify' (`-W')
Verifies that the archive was correctly written when creating an
archive. *Note verify::.
`tar' will print an informational message about what version it is,
a copyright message, and some credits, and then exit. *Note
This obsolete option has been replaced with `--backup'.
Used in conjunction with `--multi-volume' (`-M'). `tar' will keep
track of which volume of a multi-volume archive it is working on in
FILE. *Note volno-file::.

File:, Node: Short option summary, Prev: Option summary, Up: All options
Short options cross-reference
Here is an alphabetized list of all of the short option forms,
matching them with the equivalent long option.
-A --concatenate
-B --read-full-records
-C --directory
-F --info-script
-G --incremental
-K --starting-file
-L --tape-length
-M --multi-volume
-N --newer
-O --to-stdout
-P --absolute-names
-R --block-number
-S --sparse
-T --files-from
-U --unlink-first
-V --label
-W --verify
-X --exclude-from
-Z --compress
-b --blocking-factor
-c --create
-d --compare
-f --file
-g --listed-incremental
-h --dereference
-i --ignore-zeros
-k --keep-old-files
-l --one-file-system
-m --touch
-o --portability
-p --same-permissions
-r --append
-s --same-order
-t --list
-u --update
-v --verbose
-w --interactive
-x --extract
-z --gzip

File:, Node: Date input formats, Next: Archive format, Prev: All options, 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
-- Robert Grudin, `Time and the Art of Living'.
This section describes the textual date representations that some
free 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, 1970-01-01 UCT.
* Menu:
* General date syntax:: General date syntax
* Calendar date item:: Calendar date item
* Time of day item:: Time of day item
* Timezone item:: Timezone item
* Day of week item:: Day of week item
* Relative item in date strings:: Relative item in date strings
* Pure numbers in date strings:: Pure numbers in date strings
* Authors of getdate:: Authors of `getdate'

File:, 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 (that
is, 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:, 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
The year can also be omitted. In this case, the last specified year
is used, or the current year if none. For example:
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:
Or, omitting the year:

File:, 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-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

File:, 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.
`GMT' for Greenwich Mean, `UT' or `UTC' for Universal
(Coordinated), `WET' for Western European and `Z' for military.
`WAT' for West Africa and `A' for military.
`AT' for Azores and `B' for military.
`C' for military.
`AST' for Atlantic Standard and `D' for military.
`E' for military and `EST' for Eastern Standard.
`CST' for Central Standard and `F' for military.
`G' for military and `MST' for Mountain Standard.
`H' for military and `PST' for Pacific Standard.
`I' for military and `YST' for Yukon Standard.
`AHST' for Alaska-Hawaii Standard, `CAT' for Central Alaska, `HST'
for Hawaii Standard and `K' for military.
`L' for military and `NT' for Nome.
`IDLW' for International Date Line West and `M' for military.
`CET' for Central European, `FWT' for French Winter, `MET' for
Middle European, `MEWT' for Middle European Winter, `N' for
military and `SWT' for Swedish Winter.
`EET' for Eastern European, USSR Zone 1 and `O' for military.
`BT' for Baghdad, USSR Zone 2 and `P' for military.
`Q' for military and `ZP4' for USSR Zone 3.
`R' for military and `ZP5' for USSR Zone 4.
`S' for military and `ZP6' for USSR Zone 5.
`T' for military and `WAST' for West Australian Standard.
`CCT' for China Coast, USSR Zone 7 and `U' for military.
`JST' for Japan Standard, USSR Zone 8 and `V' for military.
`EAST' for East Australian Standard, `GST' for Guam Standard, USSR
Zone 9 and `W' for military.
`X' for military.
`IDLE' for International Date Line East, `NZST' for New Zealand
Standard, `NZT' for New Zealand and `Y' for military.
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.
`BST' for British Summer.
`ADT' for Atlantic Daylight.
`EDT' for Eastern Daylight.
`CDT' for Central Daylight.
`MDT' for Mountain Daylight.
`PDT' for Pacific Daylight.
`YDT' for Yukon Daylight.
`HDT' for Hawaii Daylight.
`MEST' for Middle European Summer, `MESZ' for Middle European
Summer, `SST' for Swedish Summer and `FST' for French Summer.
`WADT' for West Australian Daylight.
`EADT' for Eastern Australian Daylight.
`NZDT' for New Zealand Daylight.

File:, 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 an 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
A comma following a day of the week item is ignored.

File:, 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
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' (14 days), `week' (7 days), `day' (24 hours), `hour'
(60 minutes), `minute' or `min' (60 seconds), and `second' or `sec'
(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 multiplier with value -1.
The string `tomorrow' equates to one day in the future (equivalent
to `day'), the string `yesterday' equates to one day in the past
(equivalent to `day ago').
The strings `now' and `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
altered by previous items. They may be used to stress other items, as
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 causes 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:, 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 interpretation of a pure decimal number is dependent on
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:, 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
(<>) 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 (<>) and
Jim Berets (<>) in 1990-08. Various revisions for the
GNU system were made by David MacKenzie, Jim Meyering, and others.
Franc,ois Pinard (<>) wrote the above
description out of the `getdate.y' source code. K. Berry
(<>) later edited it.