tar(1)

tar -- file archiver

Synopsis

   /usr/sbin/tar -c[vwfbLkFhienA[num]] [device] [block] [volsize] [incfile] [files]...
   
   /usr/sbin/tar -c[vwfbLkXhienA[num]] [device] [block] [volsize] [excfile] [files]...
   

   /usr/sbin/tar -r[vwfbLkFhienA[num]] [device] [block] [volsize] [incfile] [files]...
   

   /usr/sbin/tar -r[vwfbLkXhienA[num]] [device] [block] [volsize] [excfile] [files]...
   

   /usr/sbin/tar -t[vfLXien[num] device excfile [files...]
   

   /usr/sbin/tar -u[vwfbLkXhienA[num]] [device] [block] [volsize] [excfile] [files]...
   

   /usr/sbin/tar -u[vwfbLkFhienA[num]] [device] [block] [volsize] [incfile] [files]...
   

   /usr/sbin/tar -x[lmovwfLXpienA[num]] device excfile [files... ]

Description

tar saves files on an archive medium (such as a floppy diskette or a tape) and restores them from that medium. Its actions are controlled by a string of characters containing one option (c, r, t, u, or x), and possibly followed by one or more modifiers (v, w, f, b, L, k, F, X, h, i, e, n, A, l, m, o, p, and num). Other arguments to the command are files (or directory names) specifying which files are to be dumped or restored. In all cases, appearance of a directory name refers to the files and (recursively) subdirectories of that directory.

tar uses the following criteria, listed in descending order of precedence, to determine which device to use:

Is -f device specified on the command line?
Is the TAPE environment variable set?
Is the num modifier used on the command line? (tar looks up the specified device in /etc/default/tar.)
If none of the above are true, tar uses the default device specified by the entry ``archive='' in /etc/default/tar.

The options are as follows:

-c: Create a new archive; writing begins at the beginning of the archive, instead of after the last file.
-r: The named files are written on the end of an existing archive. This option cannot be used if the archive is a tape. You may need to use the n modifier with this option.
-t: The names and other information for the specified files are listed each time they occur on the archive. This is true only if the v modifier is used. With no v, you get only pathnames. The listing is similar to the format produced by the ls -l command. (See ls(1)). If no files argument is given, all the names in the archive are listed.
-u: The named files are added to the archive if they are not already there, or have been modified since last written on that archive. This option cannot be used if the archive is a tape. You may need to use the n modifier with this option.
-x: The named files are extracted from the archive. If a named file matches a directory whose contents have been written onto the archive, this directory is (recursively) extracted. Use the file or directory's relative path when appropriate, or tar will not find a match. The owner, modification time, and mode are restored (if possible). If no files argument is given, the entire contents of the archive are extracted.

The modifiers below may be used in the order shown in the synopsis.

num

This modifier allows you to specify, via the file /etc/default/tar, the device to be used for creating or extracting an archive. Specify a number up to 9999 as the value of num. tar looks for the ``archivenum='' entry in /etc/default/tar and uses the device name specified there. By default (that is, if you specify neither -f nor num on the command line), tar looks for the ``archive='' entry.

In addition to the device name, an entry in /etc/default/tar specifies the blocking factor and the volume size to be used for that device (see the b and t modifiers). An optional fourth field indicates whether or not the device is a tape (see n modifier). A word starting with ``n'' or ``N'' indicates it is not a tape. Anything else means it is a tape. If the fourth field is not present, tar considers the device a tape if the volume size field (third field) is 0, and not a tape if it is non-zero. For example, the default device entry in /etc/default/tar might look like:

   archive=/dev/rdsk/f05ht 15 1200 N

where 15 is the blocking factor, 1200 is the volume size (in kilobytes), and the device is not a tape.

v

Normally, tar does its work silently. The v (verbose) modifier causes it to print the name of each file it treats, preceded by the option. With the -t option, v gives more information about the archive entries than just the name.

w

This modifier causes tar to print the action to be taken, followed by the name of the file, and then wait for your confirmation. If a word beginning with y is given, the action is performed. Any other input means no. This is not valid with the -t option.

f

This causes tar to use the device argument as the name of the archive instead of the default. If the name of the file is -, tar writes to the standard output or reads from the standard input, whichever is appropriate. Thus, tar can be used as the head or tail of a pipeline. tar can also be used to move hierarchies with the command:

   cd fromdir; tar cf - . | (cd todir; tar xf -)

b

This modifier causes tar to use the block argument as the blocking factor for archive records. The default is 1. The maximum is 20. This modifier should not be supplied when operating on regular archives or block special devices. It is mandatory however, when reading archives on raw magnetic tape archives (see f above). The blocking factor is determined automatically when reading tapes created on block special devices (options x and t). The block size is 512 bytes.

l

This modifier causes tar to complain if it cannot resolve all of the links to the files being dumped. If the l modifier is not specified, no error messages are printed.

m

This modifier causes tar to not restore the modification times. The modification time of the file will be the time of extraction.

o

This modifier causes extracted files to take on the user and group identifier of the user running the program, rather than those on tape. This is valid only with the -x option.

L

Follow symbolic links. This modifier causes symbolic links to be followed. By default, symbolic links are not followed. This modifier means the same thing as the h modifier (below). Both are provided for backwards compatibility.

k

This modifier, which must be used with multi-volume archives, uses the volsize argument as the size, in kilobytes per volume, for tape and non-tape devices (such as floppy drives). The argument to -k should be a multiple of the blocking factor; if it isn't, tar will round it down to the nearest such multiple. A value of 0 for volsize causes multi-volume mode to be disabled (interpreted as an infinite volume size). This modifier may be used with the -c, -r, and -u options.

When restoring from a multi-volume archive, tar prompts for a new volume only if a split file has been partially restored. Otherwise tar exits at the end of the volume. If this happens, run the tar command again for the next volume.

F

This modifier uses the incfile argument as a file containing a list of named files (or directories) to be included in the archive. This modifier may only be used with the -c, -r, and -u options. This modifier may not be used with the X modifier.

X

This modifier uses the excfile argument as a file containing a list of named files (or directories) to be excluded. This modifier may not be used with the F modifier.

h

This modifier causes tar to follow symbolic links as if they were normal files or directories. Normally tar does not follow symbolic links. The h modifier may be used with the -c, -r, and -u options.

p

This modifier restores the named file arguments to their original modes, ignoring the present value returned by umask. (See umask(2)). setuid and sticky bit information are also restored if the effective user ID is root. This modifier may only be used with the -x option.

i

This modifier causes tar to ignore directory checksum errors.

e

This modifier causes tar to quit when certain minor errors are encountered. Otherwise tar will continue when minor errors are encountered.

n

This modifier is used to tell tar that the device is not a tape. If tar has an incorrect idea of whether of not the device is a tape, undesirable results may occur. If tar gets the device entry from /etc/default/tar, it will use this entry to determine whether the device is a tape, as described under the num modifier. Otherwise, tar assumes the device is a tape, unless this modifier is used.

A

This modifier causes absolute pathnames for files to be suppressed, and may be used with the -r, -c, -u, and -x options. This causes all pathnames to be interpreted as relative to the current working directory.

If you set the TAPE environment variable to /dev/rmt/ctape1n and run the command tar -cf /dev/rmt/ctape1, the default device used will be /dev/rmt/ctape1.

If you set the TAPE environment variable to /dev/rmt/ctape1n and run the command tar -c0h, the device used will be /dev/rmt/ctape1n rather than the ``0'' entry of /etc/default/tar.

Reading from magnetic tape in any fixed-length block length besides the block length that the media was written in originally will cause an I/O error. If you want to read a tape that was written using a block-length besides the default of 512, you must use the tapecntl(1) command ( qv ) to either set the block-length of the drive to match the block length of the media or to set the drive into variable block length mode.

Files

/etc/default/tar
/tmp/tar
/usr/lib/locale/locale/LC_MESSAGES/uxcore: language-specific message file (See LANG on environ(5)).

Exit codes

tar complains about tape read/write errors.

tar complains if insufficient memory is available to hold the link tables.

References

ar(1), cpio(1), ls(1), umask(2)

Notices

There is no way to ask for the n-th occurrence of a file.

Currently, filename length is limited to 100 characters in the final component (the filename itself), and 155 characters in all preceding components (including slashes).

Because cpio can recognize archives that have been formatted with tar, it can be used as an alternative command for reading tar archives.

On a pre-Release 4 system, you cannot restore archives of directories, subdirectories, or files within directories that have been created with UNIX System V Release 4 tar. (That is, only files at the level of the current directory can be restored.) If you try to do so, you will get error messages saying files cannot be created.

Using variable-length block mode when writing magnetic tapes is discouraged because it may not work correctly in releases before SVR4.2 MP. Magnetic tape should always be written in fixed-length block mode, even though you are free to change the default fixed-block length from 512 bytes to any other fixed-block mode the tape drive supports.

Reading from magnetic tape in any fixed-length block length, besides the block length that the media was written in originally, will cause an I/O error. In order to read a tape that was written using some block length besides the default of 512, use the tapecntl(1) command (qv) to either set the block length of the drive to match the block length of the media, or to set the drive into variable block length mode.