diff options
Diffstat (limited to 'gnu/usr.bin/tar/tar.1')
| -rw-r--r-- | gnu/usr.bin/tar/tar.1 | 573 |
1 files changed, 573 insertions, 0 deletions
diff --git a/gnu/usr.bin/tar/tar.1 b/gnu/usr.bin/tar/tar.1 new file mode 100644 index 0000000..3cc2ea7 --- /dev/null +++ b/gnu/usr.bin/tar/tar.1 @@ -0,0 +1,573 @@ +.\" Copyright (c) 1991, 1992, 1993 Free Software Foundation -*- nroff -*- +.\" See /usr/src/gnu/COPYING for conditions of redistribution +.\" +.\" Written by John F. Woods <jfw@jfwhome.funhouse.com> +.\" Updated by Robert Eckardt <roberte@mep.ruhr-uni-bochum.de> +.\" +.\" $FreeBSD$ +.\" +.Dd December 23, 2000 +.Os +.Dt TAR 1 +.Sh NAME +.Nm tar +.Nd "tape archiver; manipulate ""tar"" archive files" +.Sh SYNOPSIS +.Nm +.Op Oo Fl Oc Ns Ar bundled-options Ar Args +.Op Ar gnu-style-flags +.Op Ar filenames | Fl C Ar directory-name +.Ar ... +.Sh DESCRIPTION +.Nm Tar +is short for +.Dq tape archiver , +so named for historical reasons; the +.Nm +program creates, adds files to, or extracts files from an archive file +in +.Nm +format, called a +.Ar tarfile . +A +.Ar tarfile +is often a magnetic tape, but can be a floppy diskette or any +regular disk file. +.Pp +The first argument word of the +.Nm +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 +.Cm A , +.Cm c , +.Cm d , +.Cm r , +.Cm t , +.Cm u , +.Cm x , +for +.Em append , +.Em create , +.Em difference , +.Em replace , +.Em table of contents , +.Em update , +and +.Em 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 +.Sx 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. +.Sh FUNCTIONS +Exactly one of the following functions must be specified. +.Pp +.Bl -tag -width "--concatenate" -compact +.It Fl A +.It Fl -catenate +.It Fl "-concatenate" +Append the contents of named file, which must itself be a +.Nm +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. +.Em Note : +This option requires a rewritable +.Ar tarfile , +and therefore does not work on quarter-inch cartridge tapes. +.It Fl c +.It Fl -create +Create a new archive (or truncates an old one) and writes the named files +to it. +.It Fl d +.It Fl -diff +.It Fl -compare +Find differences between files in the archive and corresponding files in +the file system. +.It Fl -delete +Delete named files from the archive. +(Does not work on quarter-inch tapes). +.It Fl r +.It Fl -append +Append files to the end of an archive. +(Does not work on quarter-inch tapes). +.It Fl t +.It Fl -list +List the contents of an archive; if +.Ar filename +arguments are given, only those +files are listed, otherwise the entire table of contents is listed. +.It Fl u +.It Fl -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. +.It Fl x +.It Fl -extract +.It Fl -get +Extract files from an archive. +The owner, modification time, and file permissions are restored, if possible. +If no +.Ar file +arguments are given, extract all the files in the archive. +If a +.Ar 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 +.Fl -append +command above), the last one extracted will overwrite all earlier versions. +.El +.Sh OPTIONS +The other options to +.Nm +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 +.Sx EXAMPLES +below). +.Pp +.Bl -tag -width "--preserve-permissions" -compact +.It Fl -help +Prints a message listing and briefly describing all the command +options to +.Nm . +.It Fl -atime-preserve +Restore the access times on files which are written to tape (note that +this will change the inode-change time!). +.It Fl b +.It Fl -block-size Ar number +Sets the block size for reading or writing to +.Ar number +* 512-byte blocks. +.It Fl B +.It Fl -read-full-blocks +Re-assemble short reads into full blocks (for reading +.Bx 4.2 +pipes). +.It Fl C Ar directory +.It Fl -directory Ar directory +Change to +.Ar directory +before processing the remaining arguments. +.It Fl -checkpoint +Print number of buffer reads/writes while reading/writing the archive. +.It Fl f Xo +.Oo Ar hostname : Oc Ns Ar file +.Xc +.It Fl -file Xo +.Oo Ar hostname : Oc Ns Ar file +.Xc +Read or write the specified +.Ar file +(default is +.Pa /dev/sa0 ) . +If a +.Ar hostname +is specified, +.Nm +will use +.Xr rmt 8 +to read or write the specified +.Ar file +on a remote machine. +.Dq Ar - +may be used as a filename, for reading +or writing to/from stdin/stdout. +.It Fl -force-local +Archive file is local even if it has a colon. +.It Fl F Ar file +.It Fl -info-script Ar file +.It Fl -new-volume-script Ar file +Run a script at the end of each archive volume (implies +.Fl M ) . +.It Fl -fast-read +Stop after all non-wildcard extraction targets have been found +in the archive. +.It Fl G +.It Fl -incremental +Create/list/extract old GNU-format incremental backup. +.It Fl g Ar file +.It Fl -listed-incremental Ar file +Create/list/extract new GNU-format incremental backup. +.It Fl h +.It Fl -dereference +Don't write symlinks as symlinks; write the data of the files they name. +.It Fl i +.It Fl -ignore-zeros +Ignore blocks of zeroes in archive (usually means End-Of-File). +.It Fl -ignore-failed-read +Don't exit with non-zero status on unreadable files. +.It Fl j +.It Fl y +.It Fl -bzip +.It Fl -bzip2 +.It Fl -bunzip2 +Filter the archive through +.Xr bzip2 1 . +.It Fl k +.It Fl -keep-old-files +Keep files which already exist on disk; don't overwrite them from the archive. +.It Fl K Ar file +.It Fl -starting-file Ar file +Begin at +.Ar file +in the archive. +.It Fl l +.It Fl -one-file-system +Stay in local filesystem when creating an archive (do not cross mount +points). +.It Fl L Ar number +.It Fl -tape-length Ar number +Change tapes after writing +.Ar number +* 1024 bytes. +.It Fl m +.It Fl -modification-time +Don't extract file modified time. +.It Fl M +.It Fl -multi-volume +Create/list/extract multi-volume archive. +.It Fl n +.It Fl -norecurse +Don't recurse into subdirectories when creating. +.It Fl -volno-file Ar file +File name with volume number to start with. +.It Fl N Ar date +.It Fl -after-date Ar date +.It Fl -newer Ar date +Only store files with creation time newer than +.Ar date . +.It Fl -newer-mtime Ar date +Only store files with modification time newer than +.Ar date . +.It Fl o +.It Fl -old-archive +.It Fl -portability +Write a V7 format archive, rather than POSIX format. +.It Fl O +.It Fl -to-stdout +Extract files to standard output. +.It Fl p +.It Fl -same-permissions +.It Fl -preserve-permissions +Extract all protection information. +.It Fl -preserve +Has the effect of +.Fl p s . +.It Fl P +.It Fl -absolute-paths +Don't strip leading +.Ql / +from file names. +.It Fl R +.It Fl -record-number +Show record number within archive with each message. +.It Fl -remove-files +Remove files after adding them to the archive. +.It Fl s +.It Fl -same-order +.It Fl -preserve-order +List of names to extract is sorted to match archive. +.It Fl -show-omitted-dirs +Show directories which were omitted while processing the archive. +.It Fl S +.It Fl -sparse +Handle +.Dq sparse +files efficiently. +.It Fl T Ar file +.It Fl I Ar file +.It Fl -files-from Ar file +Get names of files to extract or create from +.Ar file , +one per line. +.It Fl -null +Modifies behavior of +.Fl T +to expect null-terminated names; disables +.Fl C . +.It Fl -totals +Prints total bytes written with +.Fl -create . +.It Fl U +.It Fl -unlink +.It Fl -unlink-first +Unlink files before creating them. +.It Fl v +.It Fl -verbose +Lists files written to archive with +.Fl -create +or extracted with +.Fl -extract ; +lists file protection information along with file names with +.Fl -list . +.It Fl V Ar volume-name +.It Fl -label Ar volume-name +Create archive with the given +.Ar volume-name . +.It Fl -version +Print +.Nm +program version number. +.It Fl w +.It Fl -interactive +.It Fl -confirmation +Ask for confirmation for every action. +.It Fl W +.It Fl -verify +Attempt to verify the archive after writing it. +.It Fl -exclude Ar pattern +Exclude files matching the +.Ar pattern +(don't extract them, don't add them, don't list them). +.It Fl X Ar file +.It Fl -exclude-from Ar file +Exclude files listed in +.Ar file . +.It Fl Z +.It Fl -compress +.It Fl -uncompress +Filter the archive through +.Xr compress 1 . +.It Fl z +.It Fl -gzip +.It Fl -gunzip +Filter the archive through +.Xr gzip 1 . +.It Fl -use-compress-program Ar program +Filter the archive through +.Ar program +(which must accept +.Fl d +to mean +.Dq decompress ) . +.It Fl -block-compress +Block the output of compression program for tapes or floppies +(otherwise writes will be of odd length, which device drivers may reject). +.It Fl Xo +.Op Cm 0 Ns - Ns Cm 7 Ns +.Op Cm lmh +.Xc +Specify tape drive and density. +.El +.Sh ENVIRONMENT +The environment variable +.Ev TAR_OPTIONS +can hold a set of default options for +.Nm . +These options are interpreted first and can be overwritten by explicit command +line parameters. +.Sh EXAMPLES +To create an archive on tape drive +.Pa /dev/sa0 +with a block size of 20 blocks, containing files named +.Pa bert +and +.Pa ernie , +you can enter +.Dl "tar cfb /dev/sa0 20 bert ernie" +or +.Dl "tar --create --file /dev/sa0 --block-size 20 bert ernie" +Note that the +.Fl f +and +.Fl b +flags both require arguments, which they take from the command line in +the order they were listed in the command word. +.Pp +Because +.Pa /dev/sa0 +is the default device, and 20 is the default block +size, the above example could have simply been +.Dl "tar c bert ernie" +.Pp +To extract all the C sources and headers from an archive named +.Pa backup.tar , +type +.Dl "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). +.Pp +To move file hierarchies, use a command line like this: +.Bd -literal +tar -cf - -C srcdir . | tar xpf - -C destdir +.Ed +.Pp +To create a compressed archive on diskette, using +.Xr gzip 1 , +use a command-line like +.Dl "tar --block-compress -z -c -v -f /dev/fd1a -b 36 tar/" +.Pp +Note that you cannot mix bundled flags and +.Fl -style +flags; you can use +single-letter flags in the manner above, rather than having to type +.Dl "tar --block-compress --gzip --verbose --file /dev/fd1a --block-size 20 tar/" +.Pp +The above-created diskette can be listed with +.Dl "tar tvfbz /dev/fd1a 36" +.Pp +To join two +.Nm +archives into a single archive, use +.Dl "tar Af archive1.tar archive2.tar" +which will add the files contained in +.Pa archive2.tar +onto the end of +.Pa archive1.tar +(note that this can't be done by simply typing +.Dl "cat archive2.tar >> archive1.tar" +because of the end-of-file block at the end of a +.Nm +archive). +.Pp +To archive all files from the directory +.Pa srcdir , +which were modified +after Feb. 9th 1997, 13:00 h, use +.Dl "tar -c -f backup.tar --newer-mtime 'Feb 9 13:15 1997' srcdir/" +.Pp +Other possible time specifications are +.Sq "02/09/97 13:15" , +.Sq "1997-02-09 13:15" , +.Sq "13:15 9 Feb 1997" , +.Sq "9 Feb 1997 13:15" , +.Sq "Feb. 9, 1997 1:15pm" , +.Sq "09-Feb" , +.Sq "3 weeks ago" +or +.Sq "May first Sunday" . +To specify the correct time zone use either e.g.\& +.Sq "13:15 CEST" +or +.Sq "13:15+200" . +.Sh ENVIRONMENT +The +.Nm +program examines the following environment variables. +.Bl -tag -width "POSIXLY_CORRECT" +.It Ev POSIXLY_CORRECT +Normally, +.Nm +will process flag arguments that appear in the file list. +If set in the environment, this causes +.Nm +to consider the first +non-flag argument to terminate flag processing, as per the POSIX specification. +.It Ev SHELL +In interactive mode, a permissible response to the prompt is to +request to spawn a subshell, which will be +.Pa /bin/sh +unless the +.Ev SHELL +variable is set. +.It Ev TAPE +Changes +.Nm Ns 's +default tape drive (which is still overridden by the +.Fl f +flag). +.It TAR_RSH +The TAR_RSH environment variable allows you to override the default +shell used as the transport for +.Nm . +.El +.Sh FILES +.Bl -tag -width "/dev/sa0" +.It Pa /dev/sa0 +The default tape drive. +.El +.Sh COMPATIBILITY +The +.Fl y +is a +.Fx +localism. +The GNU +.Nm +maintainer has now choosen +.Fl j +as the offical +.Xr bzip2 1 +compression option in GNU +.Nm +1.13.18 and later. +The +.Fl I +option is for compatibility with Solaris's +.Nm . +.Sh SEE ALSO +.Xr bzip2 1 , +.Xr compress 1 , +.Xr gzip 1 , +.Xr pax 1 , +.Xr rmt 8 +.Sh HISTORY +The +.Nm +format has a rich history, dating back to Sixth Edition +.Ux . +The current implementation of +.Nm +is the GNU implementation, which +originated as the public-domain +.Nm +written by +.An John Gilmore . +.Sh AUTHORS +.An -nosplit +A cast of thousands, including [as listed in the +.Pa ChangeLog +file in the source] +.An John Gilmore +(author of original public domain version), +.An Jay Fenlason +(first GNU author), +.An Joy Kendall , +.An Jim Kingdon , +.An David J. MacKenzie , +.An Michael I Bushnell , +.An Noah Friedman , +and innumerable others who have contributed fixes and additions. +.Pp +Man page obtained by the +.Fx +group from the +.Nx 1.0 +release. +.Sh BUGS +The +.Fl C +feature does not work like historical +.Nm +programs, and is probably untrustworthy. +.Pp +The +.Fl A +command should work to join an arbitrary number of +.Nm +archives +together, but it does not; attempting to do so leaves the +end-of-archive blocks in place for the second and subsequent archives. +.Pp +The +.Nm +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. |
