Manual Pages for UNIX Darwin command on man gnutar

TAR(1) BSD General Commands Manual TAR(1)

NAME

ttaarr - tape archiver; manipulate "tar" archive files

SYNOPSIS

ttaarr [[-]bundled-options Args] [gnu-style-flags]

[filenames | -CC directory-name] ...

DESCRIPTION

TTaarr is short for ``tape archiver'', so named for historical reasons; the ttaarr program creates, adds files to, or extracts files from an archive file in ttaarr 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 ttaarr 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 AA, cc, dd, rr, tt, uu, xx, 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 argu-

ments from the command line in the order they are specified in the com-

mand word (review the EXAMPLES section). Functions and function modi-

fiers 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. FFUUNNCCTTIIOONNSS Exactly one of the following functions must be specified.

-AA

--ccaatteennaattee

--ccoonnccaatteennaattee Append the contents of named file, which must itself be a

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

-cc

--ccrreeaattee Create a new archive (or truncates an old one) and writes

the named files to it.

-dd

--ddiiffff

--ccoommppaarree Find differences between files in the archive and corre-

sponding files in the file system.

--ddeelleettee Delete named files from the archive. (Does not work on

quarter-inch tapes).

-rr

--aappppeenndd Append files to the end of an archive. (Does not work on

quarter-inch tapes).

-tt

--lliisstt List the contents of an archive; if filename arguments are

given, only those files are listed, otherwise the entire table of contents is listed.

-uu

--uuppddaattee Append the named files if the on-disk version has a modi-

fication date more recent than their copy in the archive

(if any). Does not work on quarter-inch tapes.

-xx

--eexxttrraacctt

--ggeett 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 direc-

tory). If the archive contains multiple entries corre-

sponding to the same file (see the --aappppeenndd command

above), the last one extracted will overwrite all earlier versions. OOPPTTIIOONNSS

The other options to ttaarr 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).

--hheellpp Prints a message listing and briefly describing

all the command options to ttaarr.

--aattiimmee-pprreesseerrvvee Restore the access times on files which are writ-

ten to tape (note that this will change the

inode-change time!).

-bb

--bblloocckk-ssiizzee number Sets the block size for reading or writing to

number * 512-byte blocks.

-BB

--rreeaadd-ffuullll-bblloocckkss Re-assemble short reads into full blocks (for

reading 4.2BSD pipes).

-CC directory

--ddiirreeccttoorryy directory Change to directory before processing the remain-

ing arguments.

--cchheecckkppooiinntt Print number of buffer reads/writes while read-

ing/writing the archive.

-ff [hostname:]file

--ffiillee [hostname:]file Read or write the specified file (default is

/dev/sa0). If a hostname is specified, ttaarr will use rmt(8) to read or write the specified file on

a remote machine. ``-'' may be used as a file-

name, for reading or writing to/from stdin/std-

out.

--ffoorrccee-llooccaall Archive file is local even if it has a colon.

-FF file

--iinnffoo-ssccrriipptt file

--nneeww-vvoolluummee-ssccrriipptt file

Run a script at the end of each archive volume

(implies -MM).

--ffaasstt-rreeaadd Stop after all non-wildcard extraction targets

have been found in the archive.

-GG

--iinnccrreemmeennttaall Create/list/extract old GNU-format incremental

backup.

-gg file

--lliisstteedd-iinnccrreemmeennttaall file

Create/list/extract new GNU-format incremental

backup.

-hh

--ddeerreeffeerreennccee Don't write symlinks as symlinks; write the data

of the files they name.

-ii

--iiggnnoorree-zzeerrooss Ignore blocks of zeroes in archive (usually means

End-Of-File).

--iiggnnoorree-ffaaiilleedd-rreeaadd Don't exit with non-zero status on unreadable

files.

-jj

--bbzziipp

--bbzziipp22

--bbuunnzziipp22 Filter the archive through bzip2(1).

-kk

--kkeeeepp-oolldd-ffiilleess Keep files which already exist on disk; don't

overwrite them from the archive.

-KK file

--ssttaarrttiinngg-ffiillee file Begin at file in the archive.

-ll

--oonnee-ffiillee-ssyysstteemm Stay in local file system when creating an ar-

chive (do not cross mount points).

-LL number

--ttaappee-lleennggtthh number Change tapes after writing number * 1024 bytes.

-mm

--mmooddiiffiiccaattiioonn-ttiimmee Don't extract file modified time.

-MM

--mmuullttii-vvoolluummee Create/list/extract multi-volume archive.

-nn

--nnoorreeccuurrssee Don't recurse into subdirectories when creating.

--vvoollnnoo-ffiillee file File name with volume number to start with.

-NN date

--aafftteerr-ddaattee date

--nneewweerr date Only store files with creation time newer than

date.

--nneewweerr-mmttiimmee date Only store files with modification time newer

than date.

-oo

--oolldd-aarrcchhiivvee

--ppoorrttaabbiilliittyy Write a V7 format archive, rather than POSIX for-

mat.

-OO

--ttoo-ssttddoouutt Extract files to standard output.

-pp

--ssaammee-ppeerrmmiissssiioonnss

--pprreesseerrvvee-ppeerrmmiissssiioonnss Extract all protection information.

--pprreesseerrvvee Has the effect of -pp -ss.

-PP

--aabbssoolluuttee-ppaatthhss Don't strip leading `/' from file names.

-RR

--rreeccoorrdd-nnuummbbeerr Show record number within archive with each mes-

sage.

--rreemmoovvee-ffiilleess Remove files after adding them to the archive.

-ss

--ssaammee-oorrddeerr

--pprreesseerrvvee-oorrddeerr List of names to extract is sorted to match ar-

chive.

--sshhooww-oommiitttteedd-ddiirrss Show directories which were omitted while pro-

cessing the archive.

-SS

--ssppaarrssee Handle ``sparse'' files efficiently.

-TT file

--ffiilleess-ffrroomm file Get names of files to extract or create from

file, one per line.

--nnuullll Modifies behavior of -TT to expect null-terminated

names; disables -CC.

--ttoottaallss Prints total bytes written with --ccrreeaattee.

-UU

--uunnlliinnkk

--uunnlliinnkk-ffiirrsstt Unlink files before creating them.

-vv

--vveerrbboossee Lists files written to archive with --ccrreeaattee or

extracted with --eexxttrraacctt; lists file protection

information along with file names with --lliisstt.

-VV volume-name

--llaabbeell volume-name Create archive with the given volume-name.

--vveerrssiioonn Print ttaarr program version number.

-ww

--iinntteerraaccttiivvee

--ccoonnffiirrmmaattiioonn Ask for confirmation for every action.

-WW

--vveerriiffyy Attempt to verify the archive after writing it.

--eexxcclluuddee pattern Exclude files matching the pattern (don't extract

them, don't add them, don't list them).

-XX file

--eexxcclluuddee-ffrroomm file Exclude files listed in file.

-ZZ

--ccoommpprreessss

--uunnccoommpprreessss Filter the archive through compress(1).

-zz

--ggzziipp

--gguunnzziipp Filter the archive through gzip(1).

--uussee-ccoommpprreessss-pprrooggrraamm program

Filter the archive through program (which must

accept -dd to mean ``decompress'').

--bblloocckk-ccoommpprreessss Block the output of compression program for tapes

or floppies (otherwise writes will be of odd length, which device drivers may reject).

-[00-77][llmmhh] Specify tape drive and density.

ENVIRONMENT

The environment variable TAROPTIONS can hold a set of default options

for ttaarr. These options are interpreted first and can be overwritten by explicit command line parameters. EEXXAAMMPPLLEESS 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 -ff and -bb 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 command-

line like

tar -block-compress -z -c -v -f /dev/fd1a -b 36 tar/

Note that you cannot mix bundled flags and --ssttyyllee 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 ttaarr 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 ttaarr 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'. ENVIRONMENT The ttaarr program examines the following environment variables. POSIXLYCORRECT Normally, ttaarr will process flag arguments that appear in the file list. If set in the environment, this causes

ttaarr 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 ttaarr's default tape drive (which is still over-

ridden by the -ff flag).

TARRSH The TARRSH environment variable allows you to override the default shell used as the transport for ttaarr. FILES /dev/sa0 The default tape drive.

BUGS

The -CC feature does not work like historical ttaarr programs, and is proba-

bly untrustworthy.

The -AA command should work to join an arbitrary number of ttaarr 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 ttaarr 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 cannot absorb our 32 bit (8 major, 16+8 minor) numbers. BSD December 23, 2000 BSD