Name

gnutar - tape archiver; manipulate
tar archive files

Synopsis

gnutar [[-]bundled-options Args] [gnu-style-flags] [filenames | -C directory-name] ...

Description

Tar is short for ``tape archiver'', so named for historical reasons; the gnutar program creates, adds files to, or extracts files from an archive file in gnutar 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 gnutar command line is usually a command word of bundled function and modifier letters, optionally preceded 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 (preceded 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 gnutar 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 gnutar 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). gnutar will properly handle option arguments passed either with or without a leading `=` (i.e. either --option=arg or --option arg).

--help

Prints a message listing and briefly describing all the command options to gnutar.

--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 --blocking-factor number

--record-size size

Sets the block size for reading or writing to number * 512-byte blocks. Or sets block size for reading or writing to size bytes which must be a multiple of 512. -B

--read-full-records

Re-assemble short reads into full records (for reading 4.2BSD pipes).

--backup control

Backup files before removal. Optionally, the user can specify a control argument to control how gnutar performs the backups. Supported values are listed bellow in the ENVIRONMENT section.

--suffix suffix

Backup files before removal. Override the normal backup suffix (default: `~'), using suffix instead. -C directory

--directory directory

Change to directory before processing the remaining arguments.

--checkpoint

Print number of buffer reads/writes while reading/writing the archive. -f [hostname:]file --file [hostname:]file Read or write the specified file (default is /dev/sa0). If a hostname is specified, gnutar will use rmt(8) to read or write the specified file on a remote machine. ``-'' may be used as a filename, for reading or writing to/from stdin/stdout.

--force-local

Archive file is local even if it has a colon. -F file --info-script file --new-volume-script file Run a script at the end of each archive volume (implies -M). -G

--incremental

Create/list/extract old GNU-format incremental backup. -g file --listed-incremental file Create/list/extract new GNU-format incremental backup.

--group name

Force group as group for added files. -h

--dereference

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. -j

--bzip2

Filter the archive through bzip2(1) . -k

--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 file system when creating an archive (do not cross mount points). -L number

--tape-length number

Change tapes after writing number * 1024 bytes.

--mode changes

Force changes to file mode of added files. -m

--modification-time

Don't extract file modified time. -M

--multi-volume

Create/list/extract multi-volume archive.

--no-recursion

Don't recurse into subdirectories when creating.

--volno-file file

File name with volume number to start with. -N date --after-date date

--newer date

Only store files with creation time newer than date.

--newer-mtime date

Only store files with modification time newer than date.

--no-same-owner

Do not preserve ownership when extracting files. Extract them all as owned by the current user. --no-same-permissions Do not extract permission information. Extract them using the default permissions for the current user.

--numeric-owner

Use numbers instead of names for owner/group names. -o --old-archive

--portability

Write a V7 format archive, rather than POSIX format. -O

--to-stdout

Extract files to standard output.

--owner name

Force name as owner for added files.

--overwrite

Overwrite existing files when extracting.

--overwrite-dir

Overwrite directory metadata when extracting. -p --same-permissions --preserve-permissions Extract all permission information.

--preserve

Has the effect of -p -s. -P

--absolute-names

Don't strip leading `/' from file names.

--posix

Instructs gnutar to create a POSIX compliant `tar' archive. -R

--block-number

Show record number within archive with each message.

--remove-files

Remove files after adding them to the archive.

--rsh-command command

Use command instead of rsh for remote archives/files. -s --same-order

--preserve-order

List of names to extract is sorted to match archive.

--same-owner

Try to preserve ownership when extracting files.

--show-omitted-dirs

Show directories which were omitted while processing the 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. -U

--unlink-first

Unlink files before creating them.

--recursive-unlink

Empty hierarchies prior to extracting directory. -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. When used with list or extract, volume-name is used as a globing pattern.

--version

Print gnutar 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.

--anchored

Exclude patterns match file name start (default).

--no-anchored

Exclude patterns match after any /.

--ignore-case

Exclude patterns ignore case.

--no-ignore-case

Exclude patterns are case sensitive (default).

--wildcards

Exclude patterns use wildcards (default).

--no-wildcards

Exclude patterns are plain strings. --wildcards-match-slash Exclude pattern wildcards match `/' (default). --no-wildcards-match-slash Exclude pattern wildcards do not match `/'. -Z --compress

--uncompress

Filter the archive through compress(1) . -z --gzip --ungzip

--gunzip

Filter the archive through gzip(1) . --use-compress-program program Filter the archive through program (which must accept -d to mean ``decompress'').

-[0-7][lmh]

Specify tape drive and density.

Environment

The gnutar program examines the following environment variables.

POSIXLY_CORRECT Normally, gnutar will process flag arguments that appear in the file list. If set in the environment, this causes gnutar 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.

SIMPLE_BACKUP_SUFFIX

Sets the backup suffix used by gnutar. Default is `~'.

TAPE

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

TAR_OPTIONS

The environment variable TAR_OPTIONS can hold a set of default options for gnutar. These options are interpreted first and can be overwritten by explicit command line parameters.

TAR_RSH

The TAR_RSH environment variable allows you to override the default shell used as the transport for gnutar.

VERSION_CONTROL Sets the backup method used by gnutar. Possible values:

t, numbered
make numbered backups

nil, existing
numbered if numbered backups exist, simple otherwise

never, simple
always make simple backups Default behaviour is `existing'.

Files

/dev/sa0 The default tape drive.

Examples

To create an archive on tape drive /dev/sa0 with a block size of 20 blocks, containing files named bert and ernie, you can enter tar cfb /dev/sa0 20 bert ernie
or
tar --create --file /dev/sa0 --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/sa0 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 move file hierarchies, use a command line like this:

tar -cf - -C srcdir . | tar xpf - -C destdir

To create a compressed archive on diskette, using gzip(1) , use a commandline like
tar --block-compress -z -c -v -f /dev/fd1a -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/fd1a --block-size 20 tar/

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

To join two gnutar 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 gnutar archive).

To archive all files from the directory srcdir, which were modified after Feb. 9th 1997, 13:00 h, use
tar -c -f backup.tar --newer-mtime `Feb 9 13:15 1997' srcdir/

Other possible time specifications are `02/09/97 13:15', `1997-02-09 13:15', `13:15 9 Feb 1997', `9 Feb 1997 13:15', `Feb. 9, 1997 1:15pm', `09-Feb', `3 weeks ago' or `May first Sunday'. To specify the correct time zone use either e.g. `13:15 CEST' or `13:15+200'.

See Also

bzip2(1) , compress(1) , gzip(1) , pax(1) , rmt(8) , info tar

History

The gnutar format has a rich history, dating back to Sixth Edition UNIX. The current implementation of gnutar is the GNU implementation, which originated as the public-domain gnutar 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.

Man page obtained by the FreeBSD group from the NetBSD 1.0 release.

Bugs

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

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

The gnutar file format is a semi fixed width field format, and the field for device numbers were designed for 16 bit (8 major, 8 minor) and can not absorb our 32 bit (8 major, 16+8 minor) numbers.

Table of Contents

• Name
• Synopsis
• Description
• Functions
• Options
• Environment
• Files
• Examples
• See Also
• History
• Authors
• Bugs