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

FreeBSD Manual Pages


home | help
tar(1)				 User Commands				tar(1)

       tar - create tape archives and add or extract files

       tar  c  [  bBeEfFhiklnopPqvwX@  [0-7]] [block] [tarfile]	[exclude-file]
       {-I include-file	| -C directory | file |	file} ...

       tar r [ bBeEfFhiklnqvw@ [0-7]] [block] {-I include-file |  -C directory
       | file |	file} ...

       tar t [ BefFhiklnqvX [0-7]] [tarfile] [exclude-file] {-I	include-file |
       file} ...

       tar u [ bBeEfFhiklnqvw@ [0-7]] [block] [tarfile]	file...

       tar x [ BefFhiklmnopqvwX	[0-7]] [tarfile] [exclude-file]	[file...]

       The tar command archives	and extracts files to and from a  single  file
       called  a  tarfile. A tarfile is	usually	a magnetic tape, but it	can be
       any file. tar's actions are controlled by the key argument. The key  is
       a  string of characters containing exactly one function letter (c, r, t
       , u, or x) and zero or more function modifiers (letters or digits), de-
       pending	on  the	function letter	used. The key string contains no SPACE
       characters. Function modifier arguments are listed on the command  line
       in  the	same order as their corresponding function modifiers appear in
       the key string.

       The -I include-file, -C directory  file,	 and  file  arguments  specify
       which  files  or	 directories  are  to be archived or extracted.	In all
       cases, appearance of a directory	name refers to the files  and  (recur-
       sively)	subdirectories	of  that directory. Arguments appearing	within
       braces ({}) indicate that one of	the arguments must be specified.

       The following options are supported:

       -I include-file
	     Opens include-file	containing a list of files, one	per line,  and
	     treats  it	 as  if	 each  file appeared separately	on the command
	     line. Be careful of trailing white	spaces.	Also beware of leading
	     white  spaces, since, for each line in the	included file, the en-
	     tire line (apart from the newline)	will be	used to	match  against
	     the  initial  string  of  files to	include. In the	case where ex-
	     cluded files (see X function modifier) are	also  specified,  they
	     take  precedence  over all	included files.	If a file is specified
	     in	both the exclude-file and the include-file (or on the  command
	     line), it will be excluded.

       -C directory file
	     Performs  a chdir (see cd(1)) operation on	directory and performs
	     the c (create) or r (replace) operation on	file. Use short	 rela-
	     tive  path	 names for file.  If file is `.', archive all files in
	     directory.	This option enables archiving files from multiple  di-
	     rectories not related by a	close common parent.

       The following operands are supported:

       file  A	path  name of a	regular	file or	directory to be	archived (when
	     the c, r or u functions are specified), extracted (x)  or	listed
	     (t).  When	 file  is the path name	of a directory,	the action ap-
	     plies to all of the files	and  (recursively)  subdirectories  of
	     that directory.

	     When  a file is archived, and the E flag (see Function Modifiers)
	     is	not specified, the filename cannot exceed 256  characters.  In
	     addition,	it  must  be possible to split the name	between	parent
	     directory names so	that the prefix	is no longer than 155  charac-
	     ters and the name is no longer than 100 characters. If E is spec-
	     ified, a name of up to PATH_MAX characters	may be specified.

	     For example, a file whose basename	is longer than 100  characters
	     could  not	be archived without using the E	flag. A	file whose di-
	     rectory portion is	200 characters and whose basename is 50	 char-
	     acters  could be archived (without	using E) if a slash appears in
	     the directory name	somewhere in character positions 151-156.

   Function Letters
       The function portion of the key is specified by one  of	the  following

       c     Create.  Writing  begins at the beginning of the tarfile, instead
	     of	at the end.

       r     Replace. The named	files are written at the end of	the tarfile. A
	     file  created with	extended headers must be updated with extended
	     headers (see E flag under Function	 Modifiers).  A	 file  created
	     without  extended	headers	cannot be modified with	extended head-

       t     Table of Contents.	The names of the specified  files  are	listed
	     each  time	 they  occur  in  the tarfile.	If no file argument is
	     given, the	names of all files and	any  associated	 extended  at-
	     tributes in the tarfile are listed. With the v function modifier,
	     additional	information for	the specified files is displayed.

       u     Update. The named files are written at the	end of the tarfile  if
	     they  are	not already in the tarfile, or if they have been modi-
	     fied since	last written to	that tarfile. An update	can be	rather
	     slow.  A  tarfile	created	on a 5.x system	cannot be updated on a
	     4.x system. A file	created	with extended headers must be  updated
	     with  extended  headers (see E flag under Function	Modifiers).  A
	     file created without extended headers cannot be modified with ex-
	     tended headers.

       x     Extract  or  restore.  The	 named	files  are  extracted from the
	     tarfile and written to the	directory specified  in	 the  tarfile,
	     relative to the current directory.	Use the	relative path names of
	     files and directories to be extracted.

	     Absolute path names contained in the tar archive are unpacked us-
	     ing  the  absolute	path names, that is, the leading forward slash
	     (/) is not	stripped off.

	     If	a named	file matches a directory whose contents	has been writ-
	     ten  to the tarfile, this directory is recursively	extracted. The
	     owner, modification time, and mode	are  restored  (if  possible);
	     otherwise,	 to restore owner, you must be the super-user. Charac-
	     ter-special and block-special devices (created by mknod(1M))  can
	     only  be  extracted  by  the  super-user.	If no file argument is
	     given, the	entire content of the tarfile  is  extracted.  If  the
	     tarfile  contains	several	files with the same name, each file is
	     written to	the appropriate	directory,  overwriting	 the  previous
	     one.  Filename substitution wildcards cannot be used for extract-
	     ing files from the	archive. Rather, use a command of the form:

       tar xvf ... /dev/rmt/0 `tar tf ... /dev/rmt/0 | \
	    grep 'pattern' `

       When extracting tapes created with the r	or u functions,	directory mod-
       ification  times	 may not be set	correctly. These same functions	cannot
       be used with many tape drives due to tape drive limitations such	as the
       absence of backspace or append capabilities.

       When  using  the	 r,  u,	or x functions or the X	function modifier, the
       named files must	match exactly the corresponding	files in the  tarfile.
       For  example,  to  extract ./thisfile, you must specify ./thisfile, and
       not thisfile. The t function displays how each file was archived.

   Function Modifiers
       The characters below may	be used	in conjunction with  the  letter  that
       selects the desired function.

       b     Blocking  Factor. Use when	reading	or writing to raw magnetic ar-
	     chives (see f below). The block argument specifies	the number  of
	     512-byte  tape blocks to be included in each read or write	opera-
	     tion performed on the tarfile. The	minimum	is 1, the  default  is
	     20.  The  maximum	value  is  a  function of the amount of	memory
	     available and the blocking	requirements of	the specific tape  de-
	     vice  involved (see mtio(7I) for details.)	The maximum cannot ex-
	     ceed INT_MAX/512 (4194303).

	     When a tape archive is being read,	 its  actual  blocking	factor
	     will  be automatically detected, provided that it is less than or
	     equal to the nominal blocking factor (the value of	the block  ar-
	     gument, or	the default value if the b modifier is not specified).
	     If	the actual blocking factor is greater than the nominal	block-
	     ing factor, a read	error will result. See Example 5 in EXAMPLES.

       B     Block. Force tar to perform multiple reads	(if necessary) to read
	     exactly enough bytes to fill a block. This	function modifier  en-
	     ables  tar	 to  work across the Ethernet, since pipes and sockets
	     return partial blocks even	when more data is coming. When reading
	     from  standard  input, '-', this function modifier	is selected by
	     default to	ensure that tar	can recover from short reads.

       e     Error. Exit immediately with a positive exit status if any	 unex-
	     pected errors occur. The SYSV3 environment	variable overrides the
	     default behavior. (See ENVIRONMENT	VARIABLES section below.)

       E     Write a tarfile with extended headers. (Used with c, r, or	u  op-
	     tions;  ignored  with  t or x options.) When a tarfile is written
	     with extended headers, the	modification time is maintained	with a
	     granularity  of  microseconds  rather  than seconds. In addition,
	     filenames no longer than PATH_MAX characters that	could  not  be
	     archived  without	E,  and	 file sizes greater than 8GB, are sup-
	     ported. The E flag	is required whenever the larger	 files	and/or
	     files  with longer	names, or whose	UID/GID	exceed 2097151,	are to
	     be	archived, or if	time granularity of microseconds is desired.

       f     File. Use the tarfile argument as the name	of the tarfile.	 If  f
	     is	 specified, /etc/default/tar is	not searched. If f is omitted,
	     tar will use the device indicated by the TAPE  environment	 vari-
	     able,  if	set; otherwise,	it will	use the	default	values defined
	     in	/etc/default/tar.  The number matching the archiveN string  is
	     used  as  the output device with the blocking and size specifica-
	     tions from	the file. For example,

	     tar -c 2/tmp/*

	     writes the	output to the device specified as archive2 in /etc/de-

	     If	 the  name  of	the tarfile is '-', tar	writes to the standard
	     output or reads from the standard input, whichever	 is  appropri-
	     ate.  tar	can be used as the head	or tail	of a pipeline. tar can
	     also be used to move hierarchies with the command:

       example%	cd fromdir; tar	cf - .|	(cd todir; tar xfBp -)

       F     With one F	argument, tar excludes all directories named SCCS  and
	     RCS  from	the  tarfile. With two arguments, FF, tar excludes all
	     directories named SCCS and	RCS, all files with .o as  their  suf-
	     fix,  and	all files named	errs, core, and	a.out. The SYSV3 envi-
	     ronment variable overrides	the default behavior. (See ENVIRONMENT
	     VARIABLES section below.)

       h     Follow  symbolic  links  as if they were normal files or directo-
	     ries. Normally, tar does not follow symbolic links.

       i     Ignore directory checksum errors.

       k size
	     Requires tar to use the size argument as the size of  an  archive
	     in	 kilobytes.  This is useful when the archive is	intended for a
	     fixed size	device such as floppy  disks.  Large  files  are  then
	     split across volumes if they do not fit in	the specified size.

       l     Link.  Output error message if unable to resolve all links	to the
	     files being archived. If l	is not specified,  no  error  messages
	     are printed.

       m     Modify.  The modification time of the file	is the time of extrac-
	     tion. This	function modifier is valid only	with the x function.

       n     The file being read is a non-tape device. Reading of the  archive
	     is	faster since tar can randomly seek around the archive.

       o     Ownership.	 Assign	 to extracted files the	user and group identi-
	     fiers of the user running	the  program,  rather  than  those  on
	     tarfile.  This is the default behavior for	users other than root.
	     If	the o function modifier	is not set and the user	is  root,  the
	     extracted	files  will  take on the group and user	identifiers of
	     the files on tarfile (see chown(1)	for more information).	The  o
	     function modifier is only valid with the x	function.

       p     Restore  the named	files to their original	modes, and ACLs	if ap-
	     plicable, ignoring	the present umask(1). This is the default  be-
	     havior if invoked as super-user with the x	function letter	speci-
	     fied. If super-user, SETUID, and sticky information are also  ex-
	     tracted,  and  files  are restored	with their original owners and
	     permissions, rather than owned by root. When this function	 modi-
	     fier is used with the c function, ACLs are	created	in the tarfile
	     along with	other information. Errors will occur  when  a  tarfile
	     with ACLs is extracted by previous	versions of tar.

       P     Suppress  the  addition of	a trailing "/" on directory entries in
	     the archive.

       q     Stop after	extracting the first occurrence	of the named file. tar
	     will  normally  continue reading the archive after	finding	an oc-
	     currence of a file.

       v     Verbose. Output the name of each file preceded  by	 the  function
	     letter.  With  the	 t function, v provides	additional information
	     about the tarfile entries.	The listing is similar to  the	format
	     produced by the -l	option of the ls(1) command.

       w     What.  Output  the	 action	 to be taken and the name of the file,
	     then await	the user's confirmation. If the	response  is  affirma-
	     tive,  the	action is performed; otherwise,	the action is not per-
	     formed. This function modifier cannot be used with	 the  t	 func-

       X     Exclude.  Use  the	 exclude-file  argument	as a file containing a
	     list of relative path names for files (or directories) to be  ex-
	     cluded  from  the tarfile when using the functions	c, x, or t. Be
	     careful of	trailing white spaces. Also beware  of	leading	 white
	     spaces,  since,  for  each	 line in the excluded file, the	entire
	     line (apart from the newline) will	be used	to match  against  the
	     initial  string  of files to exclude. Multiple X arguments	may be
	     used, with	one exclude-file per argument. In the case  where  in-
	     cluded files (see -I include-file option) are also	specified, the
	     excluded files take precedence over all included files. If	a file
	     is	specified in both the exclude-file and the include-file	(or on
	     the command line),	it will	be excluded.

       @     Include extended attributes in archive. By	default, tar does  not
	     place  extended  attributes  in  the archive. With	this flag, tar
	     will look for extended attributes on the files to	be  placed  in
	     the  archive  and add them	to the archive.	Extended attributes go
	     in	the archive as special files with a special type  label.  When
	     this  modifier  is	 used with the x function, extended attributes
	     are extracted from	the tape along with the	normal file data.  Ex-
	     tended  attribute	files can only be extracted from an archive as
	     part of a normal file extract. Attempts to	explicitly extract at-
	     tribute records are ignored.

       [0-7] Select an alternative drive on which the tape is mounted. The de-
	     fault entries are specified in /etc/default/tar. If no digit or f
	     function  modifier	 is  specified,	 the entry in /etc/default/tar
	     with digit	"0" is the default.

       See largefile(5)	for the	description of the behavior of	tar  when  en-
       countering files	greater	than or	equal to 2 Gbyte ( 2**31 bytes).

       The automatic determination of the actual blocking factor may be	fooled
       when reading from a pipe	or a socket (see the B function	 modifier  be-

       1/4"  streaming	tape  has  an inherent blocking	factor of one 512-byte
       block. It can be	read or	written	using any blocking factor.

       This function modifier works for	archives on disk files and block  spe-
       cial  devices,  among  others, but is intended principally for tape de-

       For information on tar header format, see archives(4).

       Example 1: Creating an archive of your home directory

       The following is	an example using tar to	create an archive of your home
       directory on a tape mounted on drive /dev/rmt/0:

       example%	cd
       example%	tar cvf	/dev/rmt/0 .
       messages	from tar

       The c function letter means create the archive. The v function modifier
       outputs messages	explaining what	tar is doing. The f function  modifier
       indicates that the tarfile is being specified (/dev/rmt/0 in this exam-
       ple). The dot (.) at the	end of the command line	indicates the  current
       directory and is	the argument of	the f function modifier.

       Display	the  table  of contents	of the tarfile with the	following com-

       example%	tar tvf	/dev/rmt/0

       The output will be similar to the following for the POSIX locale:

       rw-r--r--   1677/40    2123    Nov  7 18:15 1985	   ./test.c

       The columns have	the following meanings:

	  o  column 1 is the access permissions	to ./test.c

	  o  column 2 is the user-id/group-id of ./test.c

	  o  column 3 is the size of ./test.c in bytes

	  o  column 4 is the modification date of ./test.c. When  the  LC_TIME
	     category  is  not set to the POSIX	locale,	a different format and
	     date order	field may be used.

	  o  column 5 is the name of ./test.c

       To extract files	from the archive:

       example%	tar xvf	/dev/rmt/0
       messages	from tar

       If there	are multiple archive files on a	tape, each is  separated  from
       the following one by an EOF marker. To have tar read the	first and sec-
       ond archives from a tape	with multiple archives on it, the  non-rewind-
       ing  version  of	 the tape device name must be used with	the f function
       modifier, as follows:

       example%	tar xvfp /dev/rmt/0n read first	archive	from tape
       messages	from tar
       example%	tar xvfp /dev/rmt/0n read second archive from tape
       messages	from tar

       Notice that in some earlier releases, the above scenario	did  not  work
       correctly, and intervention with	mt(1) between tar invocations was nec-
       essary. To emulate the old behavior, use	 the  non-rewind  device  name
       containing the letter b for BSD behavior. See the Close Operations sec-
       tion of the mtio(7I) manual page.

       Example 2: Archiving files from /usr/include and	from /etc  to  default
       tape drive 0

       To  archive files from /usr/include and from /etc to default tape drive

       example%	tar c -C /usr  include -C /etc .

       The table of contents from the resulting	tarfile	would  produce	output
       like the	following:

       and all the other files in /usr/include ...
       ./chown and all the other files in /etc

       To extract all files in the include directory:

       example%	tar xv include
       x include/, 0 bytes, 0 tape blocks \
	   and all files under include ...

       Example 3: Transferring files across the	network

       The following is	an example using tar to	transfer files across the net-
       work. First, here is how	to archive files from the local	machine	(exam-
       ple) to a tape on a remote system (host):

       example%	tar cvfb - 20 files | \
	   rsh host dd of=/dev/rmt/0  obs=20b
       messages	from tar

       In  the example above, we are creating a	tarfile	with the c key letter,
       asking for verbose output from tar with the v function modifier,	speci-
       fying the name of the output tarfile using the f	function modifier (the
       standard	output is where	the tarfile appears, as	indicated by  the  `-'
       sign),  and specifying the blocksize (20) with the b function modifier.
       If you want to change the blocksize, you	must change the	blocksize  ar-
       guments both on the tar command and on the dd command.

       Example	4:  Retrieving	files from a tape on the remote	system back to
       the local system

       The following is	an example that	uses tar to retrieve files from	a tape
       on the remote system back to the	local system:

       example%	rsh -n host dd if=/dev/rmt/0 bs=20b | \
	   tar xvBfb - 20 files
       messages	from tar

       In the example above, we	are extracting from the	tarfile	with the x key
       letter, asking for verbose output from tar with the  v  function	 modi-
       fier,  telling  tar it is reading from a	pipe with the B	function modi-
       fier, specifying	the name of the	input tarfile  using  the  f  function
       modifier	(the standard input is where the tarfile appears, as indicated
       by the `-' sign), and specifying	the blocksize (20) with	the b function

       Example 5: Creating an archive of the home directory

       The  following  example	creates	 an  archive  of the home directory on
       /dev/rmt/0 with an actual blocking factor of 19:

       example%	tar cvfb /dev/rmt/0 19 $HOME

       To recognize this archive's actual blocking factor without using	the  b
       function	modifier:

       example%	tar tvf	/dev/rmt/0
       tar: blocksize =	19

       To recognize this archive's actual blocking factor using	a larger nomi-
       nal blocking factor:

       example%	tar tvf	/dev/rmt/0 30
       tar: blocksize =	19

       Attempt to recognize this archive's actual blocking factor using	a nom-
       inal blocking factor that is too	small:

       example%	tar tvf	/dev/rmt/0 10
       tar: tape read error

       SYSV3 This  variable  is	 used to override the default behavior of tar,
	     provide compatibility with	INTERACTIVE UNIX Systems and SCO  UNIX
	     installation  scripts, and	should not be used in new scripts. (It
	     is	intended for compatibility purposes only.) When	set, the  fol-
	     lowing options behave differently:

	     -F	filename
		   Uses	filename to obtain a list of command line switches and
		   files on which to operate.

	     -e	   Prevents files from being split across volumes. If there is
		   insufficient	room on	one volume, tar	prompts	for a new vol-
		   ume.	If the file will not fix on the	new volume, tar	 exits
		   with	an error.

       See  environ(5) for descriptions	of the following environment variables
       that affect the execution of tar: LC_CTYPE, LC_MESSAGES,	 LC_TIME,  TZ,
       and NLSPATH.

       The following exit values are returned:

       0     Successful	completion.

       >0    An	error occurred.







	     Settings may look like this:










       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |Availability		     |SUNWcsu			   |
       |CSI			     |Enabled			   |
       |Interface Stability	     |Stable			   |

       ar(1),  basename(1),  cd(1),  chown(1),	cpio(1),  csh(1),  dirname(1),
       ls(1), mt(1), pax(1), setfacl(1), umask(1),  mknod(1M),	vold(1M),  ar-
       chives(4), attributes(5), environ(5), fsattr(5),	largefile(5), mtio(7I)

       Diagnostic  messages  are  output  for  bad  key	 characters  and  tape
       read/write errors, and for insufficient memory to hold the link tables.

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

       Tape errors are handled ungracefully.

       When the	Volume Management daemon is running, accesses  to  floppy  de-
       vices   through	 the   conventional   device   names   (for   example,
       /dev/rdiskette) may not succeed.	See vold(1M) for further details.

       The tar archive format allows UIDs and GIDs up to 2097151 to be	stored
       in the archive header. Files with UIDs and GIDs greater than this value
       will be archived	with the UID and GID of	60001.

       If an archive is	created	that contains files whose names	 were  created
       by  processes  running in multiple locales, a single locale that	uses a
       full 8-bit codeset (for example,	the en_US locale) should be used  both
       to create the archive and to extract files from the archive.

       Neither	the  -r	option nor the -u option can be	used with quarter-inch
       archive tapes, since these tape drives cannot backspace.

SunOS 5.9			  27 Jun 2001				tar(1)


Want to link to this manual page? Use this URL:

home | help