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[BDeEFhilnopPqvw@[0-7]][bfk][X...]	 [blocksize]  [tarfile]	[size]
       [exclude-file...] {file | -I include-file | -C directory	file} ...

       tar r[BDeEFhilnqvw@[0-7]][bfk] [blocksize]  [tarfile]  [size]  {file  |
       -I include-file | -C directory file} ...

       tar   t[BeFhilnqv[0-7]][fk][X...]  [tarfile]  [size]  [exclude-file...]
       {file | -I include-file}	...

       tar u[BDeEFhilnqvw@[0-7]][bfk] [blocksize] [tarfile] [size] file...

       tar x[BeFhilmnopqvw[0-7]][fk][X...] [tarfile] [size]  [exclude-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),
       depending 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 operands are supported:

       -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 relative
			       path names for file.  If	file is	 ".",  archive
			       all  files  in  directory. This operand enables
			       archiving files from multiple  directories  not
			       related by a close common parent.

       -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  entire  line	(apart
			       from the	newline) will be used to match against
			       the initial string of files to include.	In the
			       case where excluded files (see X	function modi-
			       fier) 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.

       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 applies to all of	the files and  (recur-
			       sively) subdirectories of that directory.

			       When  a	file  is archived, and the E flag (see
			       Function	Modifiers) is not specified, the file-
			       name 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 characters and the name	is  no
			       longer  than 100	characters. If E is specified,
			       a name of up  to	 PATH_MAX  characters  may  be

			       For  example,  a	 file whose basename is	longer
			       than 100	characters could not be	archived with-
			       out  using  the	E flag.	A file whose directory
			       portion is 200 characters and whose basename is
			       50  characters 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 headers.

       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
		attributes in the tarfile are listed. With the v function mod-
		ifier,	additional information for the specified files is dis-

       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
		modified 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 Func-
		tion Modifiers).  A file created without extended headers can-
		not be modified	with extended 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
		using  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
		written	  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. Character-special and block-special	devices	 (cre-
		ated  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 extracting	 files	from  the  ar-
		chive. 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 blocksize     Blocking	Factor.	Use when reading  or  writing  to  raw
		       magnetic	archives (see f	below).	The blocksize argument
		       specifies the number of	512-byte  tape	blocks	to  be
		       included	 in  each read or write	operation 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  device  involved  (see mtio(7I) for details.) The
		       maximum cannot exceed 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 blocksize argument,	or the default
		       value if	the b  modifier	 is  not  specified).  If  the
		       actual  blocking	 factor	 is  greater  than the nominal
		       blocking	factor,	a read error will result. See  Example
		       5 in EXAMPLES.

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

       D	       Data change warnings. Used with c,  r,  or  u  function
		       letters.	 Ignored  with t or x function letters.	If the
		       size of	a   file  changes  while  the  file  is	 being
		       archived,  treat	this condition as a warning instead of
		       as an error. A warning message will still  be  written,
		       but the exit status is not affected.

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

       E	       Write a tarfile with extended headers. (Used with c, r,
		       or  u  function	letters.  Ignored with t or x function
		       letters.) When a	tarfile	is written with	extended head-
		       ers,  the modification time is maintained with a	granu-
		       larity of microseconds rather than  seconds.  In	 addi-
		       tion, filenames no longer than PATH_MAX characters that
		       could not be archived without E,	and file sizes greater
		       than  8GB,  are supported. The E	flag is	required when-
		       ever 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 variable, if set.
		       Otherwise, tar 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	specifications from the	file. For example,

		       tar -c 2/tmp/*

		       writes  the  output to the device specified as archive2
		       in /etc/default/tar.

		       If the name of the tarfile is "-", tar  writes  to  the
		       standard	 output	 or  reads  from  the  standard	input,
		       whichever is appropriate. 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  suffix, and all files named
		       errs, core, and a.out. The SYSV3	 environment  variable
		       overrides  the default behavior.	(See ENVIRONMENT VARI-
		       ABLES section below.)

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

       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	speci-
		       fied, no	error messages are printed.

       m	       Modify. The modification	time of	the file is  the  time
		       of  extraction.	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
		       identifiers  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 applicable, ignoring the	present	umask(1). This
		       is  the	default	behavior if invoked as super-user with
		       the x function letter specified.	If super-user, SETUID,
		       and  sticky  information	 are also extracted, and files
		       are restored with their	original  owners  and  permis-
		       sions,  rather  than  owned by root. When this function
		       modifier	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	occurrence of a	file.

       v	       Verbose.	Output the name	of each	file preceded  by  the
		       function	 letter. With the t function, v	provides addi-
		       tional information about	the tarfile entries. The list-
		       ing  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 affirmative,	the action is performed;  oth-
		       erwise, the action is not performed. This function mod-
		       ifier cannot be used with the t function.

       X	       Exclude.	Use the	exclude-file argument as a  file  con-
		       taining	a  list	 of  relative path names for files (or
		       directories) to be excluded 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.	 Lines	in the
		       exclude file are	matched	 exactly,  so  an  entry  like
		       "/var"  will  not  exclude the /var directory if	tar is
		       backing up relative pathnames. The  entry  should  read
		       "./var" under these circumstances. The tar command does
		       not expand shell	metacharacters in the exclude file, so
		       specifying  entries like	"*.o" will not have the	effect
		       of excluding all	files with names suffixed  with	 ".o".
		       If  a  complex  list  of	 files	is to be excluded, the
		       exclude file should be generated	by some	means such  as
		       the find(1) command with	appropriate conditions.

		       Multiple	X arguments may	be used, with one exclude-file
		       per argument. In	the case where included	files (see  -I
		       include-file  operand) 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

       @	       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 spe-
		       cial files with a special type label. When  this	 modi-
		       fier  is	 used with the x function, extended attributes
		       are extracted from the tape along with the normal  file
		       data.  Extended	attribute  files can only be extracted
		       from an archive as  part	 of  a	normal	file  extract.
		       Attempts	 to  explicitly	 extract attribute records are

       [0-7]	       Select an  alternative  drive  on  which	 the  tape  is
		       mounted.	  The	default	  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
       encountering 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

       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

       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
       arguments 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 compat-
		       ibility	purposes  only.) When set, the following func-
		       tion modifiers behave differently:

		       F filename      Uses filename to	obtain a list of  com-
				       mand  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
				       volume. If the file will	not fit	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.







       /etc/default/tar		       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),
       find(1),	  ls(1),   mt(1),  pax(1),  setfacl(1),	 umask(1),  mknod(1M),
       vold(1M), archives(4),  attributes(5),  environ(5),  fsattr(5),	large-
       file(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
       devices	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 function letter nor the u function	 letter	 can  be  used
       with  quarter-inch  archive  tapes,  since  these  tape	drives	cannot

       Since tar has no	options, the standard "--" argument that  is  normally
       used  in	 other	utilities  to  terminate recognition of	options	is not
       needed. If used,	it is recognized only as the  first  argument  and  is

       Since  -C  directory  file and -I include-file are multi-argument oper-
       ands, any of the	following methods can be used to archive or extract  a
       file named -C or	-I:

       1.  Specify  them  using	 file operands containing a / character	on the
	   command line	(such as /home/joe/-C or ./-I).

       2.  Include them	in an include file with	-I include-file.

       3.  Specify the directory in which the file resides:

	   -C directory	-C


	   -C directory	-I

       4.  Specify the entire directory	in which the file resides:

	   -C directory	.

SunOS 5.10			  13 Feb 2004				tar(1)


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

home | help