TAR(1)

NAME
tar - tape archiver; manipulate "tar" archive files

SYNOPSIS
tar [[-]] [bundled-options] [[gnu-style-flags]] [tarfile] [blocksize] [exclude-file] [filenames] [-C directory-name]

DESCRIPTION
tar is short for “tape archiver,” so named for historical reasons; the tar program creates, adds files to, or extracts files from an archive file in “tar” format, called a tarfile. A tarfile is often a magnetic tape, but can be a floppy diskette or any regular disk file.

The first argument word of the tar command line is usually a command word of bundled function and modifier letters, optionally preceeded by a dash; it must contain exactly one function letter from the set A, c, d, r, t, u, x, for append, create, difference, replace, table of contents, update, and extract (further described below). The command word can also contain other function modifiers described below, some of which will take arguments from the command line in the order they are specified in the command word (review the EXAMPLES section). Functions and function modifiers can also be specified with the GNU argument convention (preceeded by two dashes, one function or modifier per word. Command-line arguments that specify files to add to, extract from, or list from an archive may be given as shell pattern matching strings.

FUNCTIONS
Exactly one of the following functions must be specified.

-A
--catenate
--concatenate
    Append the contents of named file, which must itself be a tar archive, to the end of the archive (erasing the old end-of-archive block). This has the effect of adding the files contained in the named file to the first archive, rather than adding the second archive as an element of the first. Note: This option requires a rewritable tarfile, and therefore does not work on quarter-inch cartridge tapes.
-c
--create
    Create a new archive (or truncates an old one) and writes the named files to it.
-d
--diff
--compare
    Find differences between files in the archive and corresponding files in the file system.
--delete
    Delete named files from the archive (Does not work on quarter-inch tapes).
-r
--append
    Append files to the end of an archive (Does not work on quarter-inch tapes).
-t
--list
    List the contents of an archive; if filename arguments are given, only those files are listed, otherwise the entire table of contents is listed.
-u
--update
    Append the named files if the on-disk version has a modification date more recent than their copy in the archive (if any). Does not work on quarter-inch tapes.
-x
--extract
--get
    Extract files from an archive. The owner, modification time, and file permissions are restored, if possible. If no file arguments are given, extract all the files in the archive. If a filename argument matches the name of a directory on the tape, that directory and its contents are extracted (as well as all directories under that directory). If the archive contains multiple entries corresponding to the same file (see the --append command above), the last one extracted will overwrite all earlier versions.

OPTIONS
The other options to tar may be combined arbitrarily; single-letter options may be bundled in with the command word. Verbose options which take arguments will be followed by the argument; single-letter options will consume successive command line arguments (see the EXAMPLES below).

--help
    Prints a message listing and briefly describing all the command options to tar.
--atime-preserve
    Restore the access times on files which are written to tape (note that this will change the inode-change time!).
-b
--block-size number
    Sets the block size for reading or writing to N 512-byte blocks.
-B
--read-full-blocks
    Re-assemble short readsinto full blocks (for reading 4.2BSD pipes).
-C directory
--directory directory
    Change to directory for extraction.
--checkpoint
    Print directory names while reading the archive.
-f [hostname:]file
--file [hostname:]file
    Read or write the specified file (default is /dev/rst0). If a hostname is specified, tar will use rmt(8) to read or write the specified file on a remote machine.
-F file
--info-script file
--new-volume-script file
    Run a script at the end of each archive volume (implies -M).
--fast-read
    Stop after all non-wildcard extraction targets have been found in the archive.
-G
--incremental
    Create/list/extract old GNU-format incremental backup.
-g file
--listed-incremental file
    Create/list/extract new GNU-format incremental backup.
-h  Don't write symlinks as symlinks; write the data of the files they name.
-i
--ignore-zeros
    Ignore blocks of zeroes in archive (usually means End-Of-File).
--ignore-failed-read
    Don't exit with non-zero status on unreadable files.
-k  -It Fl -keep-old-files Keep files which already exist on disk; don't overwrite them from the archive.
-K file
--starting-file file
    Begin at file in the archive.
-l
--one-file-system
    Stay in local filesystem when creating an archive (do not cross mount points).
-L number
--tape-length number
    Change tapes after writing N*1024 bytes.
-m
--modification-time
    Don't extract file modified time.
-M
--multi-volume
    Create/list/extract multi-volume archive.
-N date
--after-date date
--newer date
    Only store files newer than date.
-o
--old-archive
--portability
    Write a V7 format archive, rather than POSIX format.
-O
--to-stdout
    Extract files to standard output.
-p
--same-permissions
--preserve-permissions
    Extract all protection information.
--preserve
    Has the effect of -p -s.
-R
--record-number
    Show record number within archive with each message.
--remove-files
    Remove files after adding them to the archive.
-s
--same-order
--preserve-order
    List of names to extract is sorted to match archive.
-S
--sparse
    Handle "sparse" files efficiently.
-T file
--files-from file
    Get names of files to extract or create from file, one per line.
--null
    Modifies behavior of -T to expect null-terminated names; disables -C.
--totals
    Prints total bytes written with --create.
-v
--verbose
    Lists files written to archive with --create or extracted with --extract; lists file protection information along with file names with --list.
-V volume-name
--label volume-name
    Create archive with the given volume-name.
--version
    Print tar program version number.
-w
--interactive
--confirmation
    Ask for confirmation for every action.
-W
--verify
    Attempt to verify the archive after writing it.
--exclude pattern
    Exclude files matching the pattern (don't extract them, don't add them, don't list them).
-X file
--exclude-from file
    Exclude files listed in file.
-Z
--compress
--uncompress
    Filter the archive through compress(1).
-z
--gzip
--gunzip
    Filter the archive through gzip(1).
--use-compress-program program
    Filter the archive through program (which must accept -d to mean ``decompress'').
--block-compress
    Block the output of compression program for tapes or floppies (otherwise writes will be of odd length, which device drivers may reject).
-[0-7][lmh]
    Specify tape drive and density.
--norecurse
    Don't recurse into subdirectories when creating.
--unlink
    Unlink files before creating them.

EXAMPLES
To create an archive on tape drive /dev/rst0 with a block size of 20 blocks, containing files named "bert" and "ernie", you can enter
    tar cfb /dev/rst0 20 bert ernie
or
    tar --create --file /dev/rst0 --block-size 20 bert ernie
Note that the -f and -b flags both require arguments, which they take from the command line in the order they were listed in the command word.

Because /dev/rst0 is the default device, and 20 is the default block size, the above example could have simply been
    tar c bert ernie

To extract all the C sources and headers from an archive named "backup.tar", type
    tar xf backup.tar *.[ch]
Note that the pattern must be quoted to prevent the shell from attempting to expand it according the files in the current working directory (the shell does not have access to the list of files in the archive, of course).

To create a compressed archive on diskette, using gzip, use a command-line like
    tar --block-compress -z -c -v -f /dev/rfd1a -b 36 tar/
Note that you cannot mix bundled flags and --style flags; you can use single-letter flags in the manner above, rather than having to type
    tar --block-compress --gzip --verbose --file /dev/rfd1a --block-size 20 tar/

The above-created diskette can be listed with
    tar tvfbz /dev/rfd1a 36

To join two tar archives into a single archive, use
    tar Af archive1.tar archive2.tar
which will add the files contained in archive2.tar onto the end of archive1.tar (note that this can't be done by simply typing
    cat archive2.tar >> archive1.tar
because of the end-of-file block at the end of a tar archive).

ENVIRONMENT
The tar program examines the following environment variables.

POSIXLY-CORRECT
    Normally, tar will process flag arguments that appear in the file list If set in the environment, this causes tar to consider the first non-flag argument to terminate flag processing, as per the POSIX specification.

SHELL
    In interactive mode, a permissible response to the prompt is to request to spawn a subshell, which will be "/bin/sh" unless the SHELL variable is set.

TAPE
    Changes tar's default tape drive (which is still overridden by the -f flag).

FILES

/dev/rst0
    The default tape drive.

SEE ALSO
compress(1), gzip(1), pax(1), ft(8), rmt(8)

HISTORY
The tar format has a rich history, dating back to Sixth Edition UNIX. The current implementation of tar is the GNU implementation, which originated as the public-domain tar written by John Gilmore.

AUTHORS
A cast of thousands, including [as listed in the ChangeLog file in the source] John Gilmore (author of original public domain version), Jay Fenlason (first GNU author), Joy Kendall, Jim Kingdon, David J. MacKenzie, Michael I Bushnell, Noah Friedman, and innumerable others who have contributed fixes and additions. Obtained by the FreeBSD group from the NetBSD 1.0 release.

BUGS
The -C feature does not work like historical tar programs, and is probably untrustworthy.

The -A command should work to join an arbitrary number of tar archives together, but it does not; attempting to do so leaves the end-of-archive blocks in place for the second and subsequent archives.