Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
TAR(1)			FreeBSD	General	Commands Manual			TAR(1)

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

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	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 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
		    table of contents is listed.
     -u
     --update	    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.
     -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 direc-
		    tory).  If the archive contains multiple entries corre-
		    sponding 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 arguments 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 writ-
			     ten 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
			     reading 4.2BSD pipes).
     -C	directory
     --directory directory   Change to directory before	processing the remain-
			     ing 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 file-
			     name, for reading or writing to/from stdin/std-
			     out.
     --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).
     --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
			     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	ar-
			     chive (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 ar-
			     chive.
     --show-omitted-dirs     Show directories which were omitted while pro-
			     cessing 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
			     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.
     --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
			     accept -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
     explicit 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
     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 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 over-
		      ridden 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	origi-
     nated 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 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 tar programs,	and is proba-
     bly untrustworthy.

     The -A command should work	to join	an arbitrary number of tar 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 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
     absorb our	32 bit (8 major, 16+8 minor) numbers.

FreeBSD	10.1		       December	23, 2000		  FreeBSD 10.1

NAME | SYNOPSIS | DESCRIPTION | FUNCTIONS | OPTIONS | ENVIRONMENT | EXAMPLES | ENVIRONMENT | FILES | COMPATIBILITY | SEE ALSO | HISTORY | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=tar&sektion=1&manpath=FreeBSD+5.2-RELEASE>

home | help