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), 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 operands are supported:

       -C directory file       Performs	 a  chdir (see cd(1)) operation	on di-
			       rectory and performs the	c (create) or  r  (re-
			       place)  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 ap-
			       peared separately on the	command	line. Be care-
			       ful 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  ac-
			       tion  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, in-
		stead 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  at-
		tributes  in the tarfile are listed. With the v	function modi-
		fier, 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  up-
		dated  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  ex-
		tracted.  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 in-
		       cluded in each read or write operation performed	on the
		       tarfile.	The minimum is 1, the default is 20. The maxi-
		       mum value is a function of the amount of	memory	avail-
		       able 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 ac-
		       tual blocking factor is greater than the	nominal	block-
		       ing  factor, a read error will result. See Example 5 in

       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 in-
		       dicated by the TAPE environment variable, if set.  Oth-
		       erwise,	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 hi-
		       erarchies 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  re-
		       sponse  is affirmative, the action is performed;	other-
		       wise, the action	is not performed. This function	 modi-
		       fier 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 di-
		       rectories)  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  ex-
		       clude 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 ex-
		       pand shell metacharacters in the	exclude	file, so spec-
		       ifying 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  in-
		       clude-file  (or	on  the	 command line),	it will	be ex-

       @	       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. At-
		       tempts to explicitly extract attribute records are  ig-

       [0-7]	       Select  an  alternative	drive  on  which  the  tape is
		       mounted.	The default entries are	specified in  /etc/de-
		       fault/tar. If no	digit or f function modifier is	speci-
		       fied, 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 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 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 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 ig-

       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