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

FreeBSD Manual Pages

  
 
  

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

NAME
       pax - portable archive interchange

SYNOPSIS
       pax  [-cdnv]  [-H | -L]	[-f archive]  [-o options]...  [-s replstr]...
       [pattern...]

       pax  -r	 [-cdiknuv]   [-H   |	-L]    [-f archive]    [-o options]...
       [-p string]...  [-s replstr]... [pattern...]

       pax   -w	  [-dituvX@]  [-H  |  -L]   [-b	blocksize]  [-a]  [-f archive]
       [-o options]...	[-s replstr]...	[-x format] [file...]

       pax -r -w [-diklntuvX@] [-H |  -L]    [-o  options]...	[-p string]...
       [-s replstr]... [file...] directory

DESCRIPTION
       The  pax	 utility reads,	writes,	and writes lists of the	members	of ar-
       chive files and copies directory	hierarchies. A variety of archive for-
       mats are	supported. See the -x format option.

   Modes of Operations
       The  action  to	be  taken  depends  on	the  presence of the -r	and -w
       options.	The four combinations of -r and	-w are referred	to as the four
       modes  of  operation:  list, read, write, and copy modes, corresponding
       respectively to the four	forms shown in the SYNOPSIS.

       list	In list	mode, that is, when neither -r nor -w  are  specified,
		pax  writes  the names of the members of the archive file read
		from the standard input, with path names matching  the	speci-
		fied  patterns,	 to  standard  output.	If  a  named  file has
		extended attributes, the extended attributes are also  listed.
		If  a  named  file  is	of  type directory, the	file hierarchy
		rooted at that file is listed as well.

       read	In read	mode, that is, when -r is specified, but  -w  is  not,
		pax  extracts  the  members  of	the archive file read from the
		standard input,	with path names	matching  the  specified  pat-
		terns.	If  an	extracted  file	is of type directory, the file
		hierarchy rooted at  that  file	 is  extracted	as  well.  The
		extracted  files  are  created performing path name resolution
		with the directory in which pax	was  invoked  as  the  current
		working	directory.

		If  an	attempt	is made	to extract a directory when the	direc-
		tory already exists, this is not considered an	error.	If  an
		attempt	 is  made  to  extract	a  FIFO	 when the FIFO already
		exists,	this is	not considered an error.

		The ownership, access and modification times, and file mode of
		the restored files are discussed under the -p option.

       write	In  write  mode, that is, when -w is specified,	but -r is not,
		pax writes the contents	of the file operands to	 the  standard
		output	in  an	archive	format.	If no file operands are	speci-
		fied, a	list of	files to copy, one per line, are read from the
		standard  input.  A file of type directory includes all	of the
		files in the file hierarchy rooted at the file.

       copy	In copy	mode, that is, when both -r and	-w are specified,  pax
		copies the file	operands to the	destination directory.

		If  no	file  operands are specified, a	list of	files to copy,
		one per	line, are read from the	standard input.	A file of type
		directory  includes  all  of  the  files in the	file hierarchy
		rooted at the file.

		The effect of the copy is as if	the copied files were  written
		to  an	archive	 file  and then	subsequently extracted,	except
		that there can be hard links  between  the  original  and  the
		copied	files.	If the destination directory is	a subdirectory
		of one of the files to be copied, the results are unspecified.
		It is an error if directory does not exist, is not writable by
		the user, or is	not a directory.

       In read or copy modes, if intermediate  directories  are	 necessary  to
       extract	an  archive  member,  pax  performs  actions equivalent	to the
       mkdir(2)	function, called with the following arguments:

	 o  The	intermediate directory used as the path	argument.

	 o  The	octal value of 777 or rwx (read, write,	 and  execute  permis-
	    sions) as the mode argument	(see chmod(1)).

       If  any	specified pattern or file operands are not matched by at least
       one file	or archive member, pax writes a	diagnostic message to standard
       error  for  each	 one that did not match	and exits with a non-zero exit
       status.

       The supported archive formats are automatically detected	on input.  The
       default output archive format is	tar(1).

       A  single  archive  can span multiple files. The	pax utility determines
       what file to read or write as the next file.

       If the selected archive format supports	the  specification  of	linked
       files,  it is an	error if these files cannot be linked when the archive
       is extracted, except if the files to be linked are symbolic  links  and
       the  system  is	not capable of making hard links to symbolic links. In
       that case, separate copies of the symbolic link	are  created  instead.
       Any  of	the  various names in the archive that represent a file	can be
       used to select the file for extraction. For archive formats that	do not
       store file contents with	each name that causes a	hard link, if the file
       that contains the data is not extracted during this pax session,	either
       the data	is restored from the original file, or a diagnostic message is
       displayed with the name of a file that can be used to extract the data.
       In  traversing directories, pax detects infinite	loops, that is,	enter-
       ing a previously	visited	directory that is an ancestor of the last file
       visited.	When it	detects	an infinite loop, pax writes a diagnostic mes-
       sage to standard	error and terminates.

OPTIONS
       The following options are supported:

       -a	       Appends files to	the end	of the	archive.  This	option
		       does  not  work	for  some  archive  devices,  such  as
		       1/4-inch	streaming tapes	and 8mm	tapes.

       -b blocksize    Blocks the output at a positive decimal integer	number
		       of bytes	per write to the archive file. Devices and ar-
		       chive formats  can  impose  restrictions	 on  blocking.
		       Blocking	 is automatically determined on	input.	Porta-
		       ble applications	must not  specify  a  blocksize	 value
		       larger  than  32256. Default blocking when creating ar-
		       chives depends on the archive format. See the -x	option
		       below.

       -c	       Matches all file	or archive members except those	speci-
		       fied by the pattern or file operands.

       -d	       Causes files of type directory being copied or archived
		       or archive members of type directory being extracted or
		       listed to match only the	file or	archive	member	itself
		       and not the file	hierarchy rooted at the	file.

       -f archive      Specifies the path name of the input or output archive,
		       overriding the default standard input (in list or  read
		       modes) or standard output (write	mode).

       -H	       If a symbolic link referencing a	file of	type directory
		       is specified on the command line, pax archives the file
		       hierarchy  rooted  in  the file referenced by the link,
		       using the name of the link as  the  root	 of  the  file
		       hierarchy.  Otherwise, if a symbolic link referencing a
		       file of any other file type which pax can normally  ar-
		       chive  is  specified  on	the command line, then pax ar-
		       chives the file referenced by the link, using the  name
		       of  the	link.  The  default behavior is	to archive the
		       symbolic	link itself.

       -i	       Interactively renames files  or	archive	 members.  For
		       each  archive member matching a pattern operand or file
		       matching	a file operand,	a prompt  is  written  to  the
		       file  /dev/tty.	 The  prompt  contains the name	of the
		       file or archive	member.	 A  line  is  then  read  from
		       /dev/tty.  If  this  line is blank, the file or archive
		       member is skipped. If this line consists	 of  a	single
		       period, the file	or archive member is processed with no
		       modification  to	 its  name.  Otherwise,	 its  name  is
		       replaced	with the contents of the line. pax immediately
		       exits with a non-zero exit  status  if  end-of-file  is
		       encountered when	reading	a response or if /dev/tty can-
		       not be opened for reading and writing.

		       The results of extracting a hard	link to	 a  file  that
		       has been	renamed	during extraction are unspecified.

       -k	       Prevents	the overwriting	of existing files.

       -l	       Links  files. In	copy mode, hard	links are made between
		       the source and destination  file	 hierarchies  whenever
		       possible.  If  specified	 in conjunction	with -H	or -L,
		       when a symbolic link is encountered, the	hard link cre-
		       ated  in	 the destination file hierarchy	is to the file
		       referenced by the symbolic link.	If specified when nei-
		       ther  -H	 nor  -L is specified, when a symbolic link is
		       encountered, the	implementation creates a hard link  to
		       the  symbolic  link  in	the  source  file hierarchy or
		       copies the symbolic link	to the destination.

       -L	       If a symbolic link referencing a	file of	type directory
		       is  specified on	the command line or encountered	during
		       the traversal of	a file	hierarchy,  pax	 archives  the
		       file  hierarchy	rooted	in  the	file referenced	by the
		       link, using the name of the link	as  the	 root  of  the
		       file hierarchy. Otherwise, if a symbolic	link referenc-
		       ing a file of any other file type which	pax  can  nor-
		       mally  archive  is  specified  on  the  command line or
		       encountered during the traversal	of a  file  hierarchy,
		       pax archives the	file referenced	by the link, using the
		       name of the link. The default behavior  is  to  archive
		       the symbolic link itself.

       -n	       Selects the first archive member	that matches each pat-
		       tern operand.  No  more	than  one  archive  member  is
		       matched	for  each  pattern,  although  members of type
		       directory still match the file hierarchy	rooted at that
		       file.

       -o options      Provides	 information  to  the implementation to	modify
		       the algorithm for  extracting  or  writing  files.  The
		       value  of  options  consists of one or more comma-sepa-
		       rated keywords of the form:

		       keyword[[:]=value][,keyword[[:]=value], ...]

		       Some keywords apply only	to certain  file  formats,  as
		       indicated  with	each description. Use of keywords that
		       are inapplicable	to the	file  format  being  processed
		       produces	undefined results.

		       Keywords	 in the	options	argument must be a string that
		       would be	a valid	portable filename.

		       Keywords	are not	expected to be	filenames,  merely  to
		       follow the same character composition rules as portable
		       filenames.

		       Keywords	can be preceded	with white  space.  The	 value
		       field  consists	of  zero  or  more  characters.	Within
		       value, the application precedes any literal comma  with
		       a  backslash, which is ignored, but preserves the comma
		       as part of value. A comma as the	final character, or  a
		       comma followed solely by	white space as the final char-
		       acters, in options is ignored. Multiple -o options  can
		       be  specified.  If  keywords given to these multiple -o
		       options conflict, the  keywords	and  values  appearing
		       later  in command line sequence take precedence and the
		       earlier ones are	silently ignored. The  following  key-
		       word  values of options are supported for the file for-
		       mats as indicated:

		       delete=pattern

			   This	keyword	is applicable only to the -x pax  for-
			   mat.	 When  used  in	 write or copy mode, pax omits
			   from	extended header	records	that it	 produces  any
			   keywords  matching the string pattern. When used in
			   read	or list	mode, pax ignores any keywords	match-
			   ing	the  string  pattern  in  the  extended	header
			   records. In both cases, matching is performed using
			   the pattern matching	notation. For example:

			   -o delete=security.*

			   would suppress security-related information.

			   When	 multiple -o delete=pattern options are	speci-
			   fied,  the  patterns	 are  additive.	 All  keywords
			   matching  the specified string patterns are omitted
			   from	extended header	records	that pax produces.

		       exthdr.name=string

			   This	keyword	is applicable only to the -x pax  for-
			   mat.	This keyword allows user control over the name
			   that	is written into	the ustar  header  blocks  for
			   the	extended  header.  The name is the contents of
			   string, after the following character substitutions
			   have	been made:

			   %d	    The	directory name of the file, equivalent
				    to the result of the  dirname  utility  on
				    the	translated path	name.

			   %f	    The	 filename  of  the file, equivalent to
				    the	result of the basename utility on  the
				    translated path name.

			   %p	    The	process	ID of the pax process.

			   %%	    A '%' character.

			   Any	other  '%'  characters in string produce unde-
			   fined results.

			   If no -o exthdr.name=string is specified, pax  uses
			   the following default value:

			   %d/PaxHeaders.%p/%f

		       globexthdr.name=string

			   This	 keyword is applicable only to the -x pax for-
			   mat.	When used in  write  or	 copy  mode  with  the
			   appropriate	options,  pax  creates global extended
			   header records with ustar header  blocks  that  are
			   treated  as	regular	 files by previous versions of
			   pax.	This keyword allows user control over the name
			   that	 is  written  into the ustar header blocks for
			   global extended header records.  The	 name  is  the
			   contents  of	 string, after the following character
			   substitutions have been made:

			   %n	    An integer that  represents	 the  sequence
				    number   of	 the  global  extended	header
				    record in the archive, starting at 1.

			   %p	    The	process	ID of the pax process.

			   %%	    A '%' character.

			   Any other '%' characters in	string	produce	 unde-
			   fined results.

			   If  no  -o globexthdr.name=string is	specified, pax
			   uses	the following default value:

			   $TMPDIR/GlobalHead.%p.%n

			   where $TMPDIR represents the	value  of  the	TMPDIR
			   environment	variable.  If  TMPDIR  is not set, pax
			   uses	/tmp.

		       invalid=action

			   This	keyword	is applicable only to the -x pax  for-
			   mat.	 This  keyword	allows	user  control over the
			   action pax takes upon  encountering	values	in  an
			   extended  header record that, in read or copy mode,
			   are invalid in the  destination  hierarchy  or,  in
			   list	 mode  ,  cannot be written in the codeset and
			   current locale of the implementation. The following
			   are invalid values that are recognized by pax:

			     o	In  read or copy mode, a filename or link name
				that contains character	encodings  invalid  in
				the  destination  hierarchy.  For example, the
				name can contain embedded NULs.

			     o	In read	or copy	mode, a	filename or link  name
				that is	longer than the	maximum	allowed	in the
				destination hierarchy, for either a path  name
				component or the entire	path name.

			     o	In  list  mode,	 any  character	 string	 value
				(filename, link	name, user name,  and  so  on)
				that cannot be written in the codeset and cur-
				rent locale of the implementation.

			   The	following  mutually-exclusive  values  of  the
			   action argument are supported:

			   bypass   In	read  or  copy	mode, pax bypasses the
				    file, causing no change to the destination
				    hierarchy.	In  list  mode,	pax writes all
				    requested valid values for the  file,  but
				    its	 method	 for writing invalid values is
				    unspecified.

			   rename   In read or copy mode, pax acts as  if  the
				    -i	option	were  in  effect for each file
				    with invalid filename or link name values,
				    allowing the user to provide a replacement
				    name  interactively.  In  list  mode,  pax
				    behaves  identically to the	bypass action.

			   UTF-8    pax	uses the actual	UTF-8 encoding for the
				    name  when	it  is	used in	read, copy, or
				    list mode and a filename, link name, owner
				    name,  or  any  other field	in an extended
				    header record cannot  be  translated  from
				    the	 pax UTF-8 codeset format to the code-
				    set	and current locale of the  implementa-
				    tion.

			   write    In read or copy mode, pax writes the file,
				    translating	 the   name,   regardless   of
				    whether  this  can	overwrite  an existing
				    file with a	valid name. In list mode,  pax
				    behaves  identically to the	bypass action.

			   If no -o invalid= option is specified, pax acts  as
			   if  -o invalid=bypass were specified. Any overwrit-
			   ing of existing files that can be allowed by	the -o
			   invalid= actions are	subject	to permission (-p) and
			   modification	time (-u) restrictions,	and  are  sup-
			   pressed if the -k option is also specified.

		       linkdata

			   This	 keyword is applicable only to the -x pax for-
			   mat.	In write mode, pax writes the  contents	 of  a
			   file	to the archive even when that file is merely a
			   hard	link to	a file	whose  contents	 have  already
			   been	written	to the archive.

		       listopt=format

			   This	keyword	specifies the output format of the ta-
			   ble of contents produced  when  the	-v  option  is
			   specified in	list mode. (See	List Mode Format Spec-
			   ifications  below.)	 To   avoid   ambiguity,   the
			   listopt=format  is  the only	or final keyword=value
			   pair	in an -o option-argument.  All	characters  in
			   the remainder of the	option-argument	are considered
			   to be part of the format string. When  multiple  -o
			   listopt=format  options  are	 specified, the	format
			   strings are considered to be	a single, concatenated
			   string, evaluated in	command	line order.

		       times

			   This	 keyword  is applicable	only to	the -x pax and
			   -x xustar formats. When used	in write or copy mode,
			   pax	 includes  atime  and  mtime  extended	header
			   records for each file.

		       In addition to these keywords, if the -x	pax format  is
		       specified,  any	of  the	keywords and values, including
		       implementation extensions, can be used  in  -o  option-
		       arguments, in either of two modes:

		       keyword=value   When  used in write or copy mode, these
				       keyword/value pairs are included	at the
				       beginning  of the archive as typeflag g
				       global extended header  records.	  When
				       used  in	 read or list mode, these key-
				       word/value pairs	act  as	 if  they  had
				       been at the beginning of	the archive as
				       typeflag	 g  global   extended	header
				       records.

		       keyword:=value  When  used in write or copy mode, these
				       keyword/value  pairs  are  included  as
				       records	at the beginning of a typeflag
				       x extended header for each file.	  This
				       is  equivalent  to  the equal-sign form
				       except that it creates  no  typeflag  g
				       global  extended	 header	 records. When
				       used in read or list mode,  these  key-
				       word/value  pairs  act  as if they were
				       included	as records at the end of  each
				       extended	 header.   Thus, they override
				       any global  or  file-specific  extended
				       header  record  keywords	 of  the  same
				       names. For example, in the command:

				       pax -r -o "
				       gname:=mygroup,
				       " <archive

				       the group name is forced	to a new value
				       for all files read from the archive.

       -p string       Specifies  one  or  more	 file  characteristic  options
		       (privileges). The  string  option-argument  must	 be  a
		       string  specifying  file	characteristics	to be retained
		       or discarded on extraction.  The	string consists	of the
		       specification  characters  a,  e, m, o, and p. Multiple
		       characteristics can be  concatenated  within  the  same
		       string  and  multiple  -p options can be	specified. The
		       meaning of the specification characters is as follows:

		       a	Does not preserve file access times.

		       e	Preserves the user ID,	group  ID,  file  mode
				bits, access time, and modification time.

		       m	Does not preserve file modification times.

		       o	Preserves the user ID and group	ID.

		       p	Preserves the file mode	bits.

		       In  the	preceding list,	``preserve'' indicates that an
		       attribute  stored  in  the  archive  is	given  to  the
		       extracted  file,	 subject  to  the  permissions	of the
		       invoking	process. Otherwise, the	 attribute  is	deter-
		       mined  as  part of the normal file creation action. The
		       access and modification times of	the file is  preserved
		       unless  otherwise  specified  with the -p option	or not
		       stored in the archive. All attributes that are not pre-
		       served  are  determined as part of the normal file cre-
		       ation action.

		       If neither the e	nor the	o specification	 character  is
		       specified,  or  the  user  ID and group ID are not pre-
		       served for any reason, pax does not set the setuid  and
		       setgid bits of the file mode.

		       If the preservation of any of these items fails for any
		       reason, pax writes a  diagnostic	 message  to  standard
		       error.  Failure	to  preserve  these  items affects the
		       final exit status, but does  not	 cause	the  extracted
		       file to be deleted.

		       If  file-characteristic	letters	 in  any of the	string
		       option-arguments	are duplicated or conflict  with  each
		       other,  the  ones given last take precedence. For exam-
		       ple, if -p eme is specified,  file  modification	 times
		       are preserved.

       -r	       Reads an	archive	file from standard input.

       -s replstr      Modifies	 file or archive member	names named by pattern
		       or file operands	according to the substitution  expres-
		       sion  replstr, which is based on	the ed(1) s (substitu-
		       tion) utility, using the	regular	expression  syntax  on
		       the  regex(5)  manual page. The concepts	of ``address''
		       and ``line'' are	meaningless in the context of the  pax
		       command,	and must not be	supplied. The format is:

		       -s /old/new/ [gp]

		       where,  as in ed, old is	a basic	regular	expression and
		       new can contain an ampersand (&), a  \n	backreference,
		       where  n	is a digit, or subexpression matching. The old
		       string is also permitted	to contain newlines.

		       Any non-null character can be used as  a	 delimiter  (/
		       shown  here). Multiple -s expressions can be specified.
		       The expressions are applied  in	the  order  specified,
		       terminating with	the first successful substitution. The
		       optional	trailing g is as defined in  the  ed  command.
		       The optional trailing p causes successful substitutions
		       to be written to	standard error.	File or	archive	member
		       names  that  substitute to the empty string are ignored
		       when reading and	writing	archives.

       -t	       When reading files from the file	 system,  and  if  the
		       user  has the permissions required by utime() to	do so,
		       sets the	access time of each file read  to  the	access
		       time that it had	before being read by pax.

       -u	       Ignores files that are older (having a less recent file
		       modification time) than a pre-existing file or  archive
		       member with the same name.

		       read mode       An archive member with the same name as
				       a file in the file system is  extracted
				       if the archive member is	newer than the
				       file.

		       write mode      An archive file member  with  the  same
				       name  as	 a  file in the	file system is
				       superseded if the file  is  newer  than
				       the  archive  member.  If  option -a is
				       also specified, this is accomplished by
				       appending to the	archive. Otherwise, it
				       is unspecified whether this  is	accom-
				       plished	by  actual  replacement	in the
				       archive or by appending to the archive.

		       copy mode       The  file  in the destination hierarchy
				       is replaced by the file in  the	source
				       hierarchy  or  by a link	to the file in
				       the source hierarchy if the file	in the
				       source hierarchy	is newer.

       -v	       In list mode, produces a	verbose	table of contents (see
		       Standard	Output). Otherwise, writes archive member path
		       names  and  extended  attributes	to standard error (see
		       Standard	Error).

       -w	       Writes files to the standard output  in	the  specified
		       archive format.

       -x format       Specifies  the  output  archive format. The pax utility
		       recognizes the following	formats:

		       cpio	The extended cpio(1) interchange  format.  See
				IEEE  Std  1003.1-2001.	 The default blocksize
				for this format	for character special  archive
				files  is  5120.  Implementations  support all
				blocksize values less than or equal  to	 32256
				that are multiples of 512.

				This archive format allows files with UIDs and
				GIDs up	to 262143 to be	stored in the archive.
				Files  with  UIDs  and	GIDs greater than this
				value are archived with	the  UID  and  GID  of
				60001.

		       pax	The  pax  interchange  format.	See  IEEE  Std
				1003.1-2001. The default  blocksize  for  this
				format	for character special archive files is
				5120. Implementations  support	all  blocksize
				values	less  than  or equal to	32256 that are
				multiples of 512.

				Similar	to ustar. Also	allows	archiving  and
				extracting  files  whose  size is greater than
				8GB; whose UID,	 GID,  devmajor,  or  devminor
				values	are  greater  than 2097151; whose path
				(including filename) is	greater	than 255 char-
				acters;	 or whose linkname is greater than 100
				characters.

		       ustar	The extended tar(1)  interchange  format.  See
				the   IEEE  1003.1(1990)  specifications.  The
				default	blocksize for this format for  charac-
				ter  special archive files is 10240. Implemen-
				tations	support	all blocksize values less than
				or equal to 32256 that are multiples of	512.

				This archive format allows files with UIDs and
				GIDs up	to 2097151 to be  stored  in  the  ar-
				chive.	Files  with UIDs and GIDs greater than
				this value are archived	with the UID  and  GID
				of 60001.

		       xustar	Similar	 to  ustar.  Also allows archiving and
				extracting files whose size  is	 greater  than
				8GB;  whose  UID,  GID,	 devmajor, or devminor
				values are greater than	 2097151;  whose  path
				(including filename) is	greater	than 255 char-
				acters;	or whose linkname is greater than  100
				characters.  This option should	not be used if
				the archive is to be extracted by an  archiver
				that cannot handle the larger values.

		       Any  attempt  to	 append	to an archive file in a	format
		       different from the existing archive format  causes  pax
		       to exit immediately with	a non-zero exit	status.

		       In copy mode, if	no -x format is	specified, pax behaves
		       as if -x	pax were specified.

       -X	       When traversing the file	hierarchy specified by a  path
		       name, pax does not descend into directories that	have a
		       different device	ID (st_dev, see	stat(2)).

       -@	       When traversing the file	hierarchy specified by a  path
		       name, pax descends into the attribute directory for any
		       file with extended attributes. Extended	attributes  go
		       into  the  archive  as special files. When this flag is
		       used during file	extraction,  any  extended  attributes
		       associated   with  a  file  being  extracted  are  also
		       extracted.  Extended  attribute	files  can   only   be
		       extracted  from	an  archive  as	 part of a normal file
		       extract.	 Attempts  to  explicitly  extract   attribute
		       records are ignored.

       Specifying more than one	of the mutually-exclusive options -H and -L is
       not considered an error.	 The  last  option  specified  determines  the
       behavior	of the utility.

       The  options that operate on the	names of files or archive members (-c,
       -i, -n, -s, -u and -v) interact as follows.

       In read mode, the archive members are selected based on the user-speci-
       fied  pattern  operands as modified by the -c, -n and -u	options. Then,
       any -s and -i options modify, in	that order, the	names of the  selected
       files. The -v option writes names resulting from	these modifications.

       In  write mode, the files are selected based on the user-specified path
       names as	modified by the	-n and -u options. Then, any -s	and -i options
       modify, in that order, the names	of these selected files. The -v	option
       writes names resulting from these modifications.

       If both the -u and -n options are specified, pax	does  not  consider  a
       file selected unless it is newer	than the file to which it is compared.

   List	Mode Format Specifications
       In list mode with the -o	listopt=format option, the format argument  is
       applied	for  each  selected file. The pax utility appends a newline to
       the listopt output for each selected file. The format argument is  used
       as  the format string with the following	exceptions. (See printf(1) for
       the first five exceptions.)

       1.  A SPACE character in	the format string, in any context other	than a
	   flag	of a conversion	specification, is treated as an	ordinary char-
	   acter that is copied	to the output.

       2.  A ' ' character in the format string	is treated as a	' ' character,
	   not as a SPACE.

       3.  In  addition	 to  the  escape sequences described in	the formats(5)
	   manual page (\\, \a,	\b, \f,	\n, \r,	\t, \v), \ddd, where ddd is  a
	   one-,  two-,	or three-digit octal number, is	written	as a byte with
	   the numeric value specified by the octal number.

       4.  Output from the d or	u conversion specifiers	 is  not  preceded  or
	   followed with BLANKs	not specified by the format operand.

       5.  Output  from	 the o conversion specifier is not preceded with zeros
	   that	are not	specified by the format	operand.

       6.  The sequence	(keyword) can occur before a format conversion	speci-
	   fier.  The  conversion argument is defined by the value of keyword.
	   The following keywords are supported	(see IEEE Std 1003.1-2001):

	     o	Any of the Field Name entries in ustar Header Block and	Octet-
		Oriented  cpio	Archive	Entry. The implementation supports the
		cpio keywords without the leading c_ in	addition to  the  form
		required by Values for cpio c_ mode Field.

	     o	Any  keyword  defined  for the extended	header in pax Extended
		Header.

	     o	Any keyword provided as	 an  implementation-defined  extension
		within the extended header defined in pax Extended Header.

	   For	example, the sequence "%(charset)s" is the string value	of the
	   name	of the character set in	the extended header.

	   The result of the keyword conversion	argument is the	value from the
	   applicable  header  field  or extended header, without any trailing
	   NULs.

	   All keyword values used as conversion arguments are translated from
	   the	UTF -8 encoding	to the character set appropriate for the local
	   file	system,	user database, and so on, as applicable.

       7.  An additional conversion specifier character, T, is used to specify
	   time	 formats. The T	conversion specifier character can be preceded
	   by the sequence (keyword=subformat),	where subformat	is a date for-
	   mat	as  defined by date operands. The default keyword is mtime and
	   the default subformat is:

	   %b %e %H:%M %Y

       8.  An additional conversion specifier character, M, is used to specify
	   the file mode string	as defined in ls Standard Output. If (keyword)
	   is omitted, the mode	keyword	is used. For example, %.1M writes  the
	   single character corresponding to the entry type field of the ls -l
	   command.

       9.  An additional conversion specifier character, D, is used to specify
	   the	device for block or special files, if applicable, in an	imple-
	   mentation-defined format. If	not applicable,	and (keyword) is spec-
	   ified,  then	 this  conversion is equivalent	to %(keyword)u.	If not
	   applicable, and (keyword)  is  omitted,  then  this	conversion  is
	   equivalent to SPACE.

       10. An additional conversion specifier character, F, is used to specify
	   a path name.	The F  conversion  character  can  be  preceded	 by  a
	   sequence of comma-separated keywords:

	   (keyword[,keyword] ... )

	   The values for all the keywords that	are non-null are concatenated,
	   each	separated by a '/'. The	default	is (path) if the keyword  path
	   is defined. Otherwise, the default is (prefix,name).

       11. An additional conversion specifier character, L, is used to specify
	   a symbolic link expansion. If the current file is a symbolic	 link,
	   then	%L expands to:

	   "%s -> %s", value of	keyword, contents of link

	   Otherwise, the %L conversion	specification is the equivalent	of %F.

OPERANDS
       The following operands are supported:

       directory       The destination directory path name for copy mode.

       file	       A path name of a	file to	be copied or archived.

       pattern	       A pattern matching one or more path  names  of  archive
		       members.	A pattern must conform to the pattern matching
		       notation	found  on  the	fnmatch(5)  manual  page.  The
		       default,	 if  no	pattern	is specified, is to select all
		       members in the archive.

OUTPUT
       Output formats are discussed below:

   Standard Output
       In write	mode, if -f is not specified, the standard output is  the  ar-
       chive formatted according to cpio or ustar. (See	-x format.)

       In list mode, when the -o listopt=format	option has been	specified, the
       selected	archive	members	are written to standard	output using the  for-
       mat  described  above  under  List Mode Format Specifications.  In list
       mode without the	-o listopt=format option, the table of contents	of the
       selected	 archive members are written to	standard output	using the fol-
       lowing format:

       "%s\n", pathname

       If the -v option	is specified in	list mode, the table  of  contents  of
       the  selected  archive members are written to standard output using the
       following formats:

	 o  For	path names representing	hard links to previous members of  the
	    archive:

	    "%s	== %s\n", <ls -l listing_, linkname

	 o  For	all other path names:

	    "%s\n", <ls	-l listing>

	    where  <ls	-l  listing> is	the format specified by	the ls command
	    with the -l	option.	When writing path names	in this	format,	it  is
	    unspecified	 what  is  written for fields for which	the underlying
	    archive format does	not have the correct information, although the
	    correct number of blank-character-separated	fields is written.

       In  list	 mode,	standard  output is not	buffered more than a line at a
       time.

   Standard Error
       If -v is	specified in read, write or copy modes,	pax  writes  the  path
       names  it  processes  to	 the standard error output using the following
       format:

       "%s\n", pathname

       These path names	are written as soon as processing is begun on the file
       or archive member, and are flushed to standard error. The trailing new-
       line character, which is	not buffered, is written  when	the  file  has
       been read or written.

       If  the -s option is specified, and the replacement string has a	trail-
       ing p, substitutions are	written	to standard  error  in	the  following
       format:

       "%s >> %s\n", <original pathname>, <new pathname>

       In  all operating modes of pax, optional	messages of unspecified	format
       concerning the input archive format and volume number,  the  number  of
       files,  blocks,	volumes,  and  media parts as well as other diagnostic
       messages	can be written to standard error.

       In all formats, for both	standard output	 and  standard	error,	it  is
       unspecified  how	 non-printable	characters in path names or link names
       are written.

       When pax	is in read mode	or list	mode, using the	-x pax archive format,
       and  a  file  name,  link  name,	 owner	name, or any other field in an
       extended	header record cannot be	translated from	the pax	UTF-8  codeset
       format  to  the	codeset	 and current locale of the implementation, pax
       writes a	diagnostic message to standard error, processes	 the  file  as
       described  for  the -o invalid=option, and then processes the next file
       in the archive.

   Output Files
       In read mode, the extracted output files	are of the archived file type.
       In  copy	 mode,	the copied output files	are the	type of	the file being
       copied .	In either mode,	existing files in  the	destination  hierarchy
       are  overwritten	only when all permission (-p), modification time (-u),
       and invalid-value (-o invalid=) tests allow it. In write	mode, the out-
       put  file named by the -f option-argument is a file formatted according
       to one of the specifications in IEEE Std	1003.1-2001.

ERRORS
       If pax cannot create a file or a	link when reading an archive, or  can-
       not  find  a  file when writing an archive, or cannot preserve the user
       ID, group ID, or	file mode when the -p option is	specified, a  diagnos-
       tic  message is written to standard error and a non-zero	exit status is
       returned, but processing	continues. In the case where pax cannot	create
       a link to a file, pax does not, by default, create a second copy	of the
       file.

       If the extraction of a file from	an archive is  prematurely  terminated
       by  a  signal  or error,	pax can	have only partially extracted the file
       or, if the -n option was	not specified, can have	extracted  a  file  of
       the  same name as that specified	by the user, but which is not the file
       the user	wanted.	Additionally, the file modes of	extracted  directories
       can have	additional bits	from the read, write, execute mask set as well
       as incorrect modification and access times.

USAGE
       The -p  (privileges)  option  was  invented  to	reconcile  differences
       between	historical  tar(1) and cpio(1) implementations.	In particular,
       the two utilities use -m	in diametrically opposed ways. The  -p	option
       also  provides a	consistent means of extending the ways in which	future
       file attributes can be addressed, such as for enhanced security systems
       or  high-performance  files.  Although  it  can seem complex, there are
       really two modes	that are most commonly used:

       -p e	``Preserve everything''. This would be used by the  historical
		superuser,  someone  with  all	the appropriate	privileges, to
		preserve all aspects of	the files as they are recorded in  the
		archive. The e flag is the sum of o and	p, and other implemen-
		tation-dependent attributes.

       -p p	``Preserve'' the file mode bits. This would  be	 used  by  the
		user with regular privileges who wished	to preserve aspects of
		the file other than the	ownership. The	file  times  are  pre-
		served	by default, but	two other flags	are offered to disable
		these and use the time of extraction.

       The one path name per line format  of  standard	input  precludes  path
       names  containing newlines. Although such path names violate the	porta-
       ble filename guidelines,	they can exist and their presence can  inhibit
       usage  of pax within shell scripts. This	problem	is inherited from his-
       torical archive programs. The problem can be avoided  by	 listing  file
       name arguments on the command line instead of on	standard input.

       It  is  almost certain that appropriate privileges are required for pax
       to accomplish parts of this volume of IEEE  Std	1003.1-2001.  Specifi-
       cally,  creating	 files	of  type  block	 special or character special,
       restoring file access times unless the files are	owned by the user (the
       -t  option),  or	preserving file	owner, group, and mode (the -p option)
       all probably require appropriate	privileges.

       In read mode, implementations are permitted to overwrite	files when the
       archive	has multiple members with the same name. This can fail if per-
       missions	on the first version of	the file do not	permit it to be	 over-
       written.

       See  largefile(5)  for  the  description	 of  the  behavior of pax when
       encountering files greater than or equal	to 2 Gbyte ( 2**31 bytes).

   Standard Input
       In write	mode, the standard input is used only if no file operands  are
       specified.  It  is a text file containing a list	of path	names, one per
       line, without leading or	trailing blanks. In list and read modes, if -f
       is not specified, the standard input is an archive file.	Otherwise, the
       standard	input is not used.

   Input Files
       The input file named by the archive option-argument, or standard	 input
       when  the  archive is read from there, is a file	formatted according to
       IEEE Std	1003.1-2001, pax Shell and Utilities.  The  file  /dev/tty  is
       used to write prompts and read responses.

EXAMPLES
       Example 1: Copying the Contents of the Current Directory

       The following command:

       example%	pax -w -f /dev/rmt/1m .

       copies  the  contents  of the current directory to tape drive 1,	medium
       density.	This assumes historical	System V device	naming procedures. The
       historical BSD device name would	be /dev/rmt9.

       Example 2: Copying the Directory	Hierarchy

       The following commands:

       example%	mkdir newdir
       example%	pax -rw	olddir newdir

       copy the	olddir directory hierarchy to newdir.

       Example	3: Reading an Archive Extracted	Relative to the	Current	Direc-
       tory

       The following command:

       example%	pax -r -s ',^//*usr//*,,' -f a.pax

       reads the archive a.pax,	with all files rooted in /usr in  the  archive
       extracted relative to the current directory.

       Example 4: Overriding the Default Output	Description

       Using the option:

       -o listopt="%M %(atime)T	%(size)D %(name)s"

       overrides the default output description	in Standard Output and instead
       writes:

       -rw-rw- - - Jan 12 15:53	2003 1492 /usr/foo/bar

       Using the options:

       -o listopt='%L\t%(size)D\n%.7' \
       -o listopt='(name)s\n%(atime)T\n%T'

       overrides the default output description	in standard output and instead
       writes:

       usr/foo/bar -> /tmp	       1492
       /usr/foo
       Jan 12 15:53 1991
       Jan 31 15:53 2003

ENVIRONMENT VARIABLES
       See  environ(5) for descriptions	of the following environment variables
       that affect the execution of pax: LANG, LC_ALL, LC_CTYPE,  LC_MESSAGES,
       LC_TIME,	and NLSPATH.

       LC_COLLATE      Determine  the  locale  for  the	 behaviour  of ranges,
		       equivalence classes, and	multi-character	collating ele-
		       ments  used in the pattern matching expressions for the
		       pattern operand,	the basic regular expression  for  the
		       -s  option, and the extended regular expression defined
		       for the yesexpr locale keyword in the LC_MESSAGES cate-
		       gory.

       TMPDIR	       Determine  the  path  name  that	 provides  part	of the
		       default	global	extended  header   record   file,   as
		       described  for  the -o globexthdr= keyword as described
		       in the OPTIONS section.

       TZ	       Determine the timezone used to calculate	date and  time
		       strings when the	-v option is specified.	If TZ is unset
		       or null,	an unspecified default timezone	is used.

EXIT STATUS
       The following exit values are returned:

       0	All files were processed successfully.

       >0	An error occurred.

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWcsu			   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+

SEE ALSO
       chmod(1),  cpio(1),  ed(1),  printf(1),	tar(1),	  mkdir(2),   stat(2),
       attributes(5),	environ(5),  fnmatch(5),  formats(5)fsattr(5),	large-
       file(5),	regex(5), standards(5)

SunOS 5.10			  25 Oct 2004				pax(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERANDS | OUTPUT | ERRORS | USAGE | EXAMPLES | ENVIRONMENT VARIABLES | EXIT STATUS | ATTRIBUTES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pax&sektion=1&manpath=SunOS+5.10>

home | help