home | help 
UNTITLED()			      LOCAL			      UNTITLED()

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

SYNOPSIS
     tar [[-]bundled-options Args] [gnu-style-flags]
	 [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 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  (re-
     view 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 pat-
     tern 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 there-
		    fore 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 corre-
		    sponding 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 ta-
		    ble of contents is listed.
     -u
     --update	    Append  the named files if the on-disk version has a modifi-
		    cation 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 di-
		    rectory on the tape, that directory and its contents are ex-
		    tracted (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  argu-
     ments  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
			     number * 512-byte blocks.
     -B
     --read-full-blocks      Re-assemble short reads into full blocks (for read-
			     ing 4.2BSD pipes).
     -C directory
     --directory directory   Change to directory before processing the remaining
			     arguments.
     --checkpoint	     Print number of  buffer  reads/writes  while  read-
			     ing/writing the archive.
     -f [hostname:]file
     --file [hostname:]file  Read  or  write  the  specified  file  (default  is
			     /dev/sa0).  If a hostname is  specified,  tar  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 (im-
			     plies -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
     --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
     -y
     --bzip
     --bzip2
     --bunzip2		     Filter the archive through bzip2(1).
     -k
     --keep-old-files	     Keep files which already exist on disk; don't over-
			     write 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.
     -m
     --modification-time     Don't extract file modified time.
     -M
     --multi-volume	     Create/list/extract multi-volume archive.
     -n
     --norecurse	     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.
     -o
     --old-archive
     --portability	     Write a V7 format archive, rather than  POSIX  for-
			     mat.
     -O
     --to-stdout	     Extract files to standard output.
     -p
     --same-permissions
     --preserve-permissions  Extract all protection information.
     --preserve 	     Has the effect of -p -s.
     -P
     --absolute-paths	     Don't strip leading `/' from file names.
     -R
     --record-number	     Show  record  number  within archive with each mes-
			     sage.
     --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.
     --show-omitted-dirs     Show  directories which were omitted while process-
			     ing the archive.
     -S
     --sparse		     Handle "sparse" files efficiently.
     -T file
     -I 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
     --unlink-first	     Unlink files before creating them.
     -v
     --verbose		     Lists files written to archive with --create or ex-
			     tracted with --extract; lists file  protection  in-
			     formation 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  ac-
			     cept -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.

ENVIRONMENT
     The  environment variable TAR_OPTIONS can hold a set of default options for
     tar.  These options are interpreted first and can	be  overwritten  by  ex-
     plicit command line parameters.

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	command-
     line 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 sin-
     gle-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 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).

     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 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 overrid-
		      den by the -f flag).

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

FILES
     /dev/sa0  The default tape drive.

COMPATIBILITY
     The  -y is a FreeBSD localism.  The GNU tar maintainer has now chosen -j as
     the offical bzip2(1) compression option in GNU tar 1.13.18 and later.   The
     -I option is for compatibility with Solaris's tar.

SEE ALSO
     bzip2(1), compress(1), gzip(1), pax(1), 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  con-
     tributed 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 tar programs, and is probably
     untrustworthy.

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

     The tar 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 ab-
     sorb our 32 bit (8 major, 16+8 minor) numbers.

FreeBSD 5.5			December 23, 2000			  TAR(1)
home | help