unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

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,
                                       " <&lt;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 (&&amp;), 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&gt;, 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.



       >&gt;0       An error occurred.



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


       tab()     allbox;     cw(2.750000i)|    cw(2.750000i)    lw(2.750000i)|
       lw(2.750000i).   ATTRIBUTE  TYPEATTRIBUTE   VALUE   AvailabilitySUNWcsu
       Interface StabilityStandard


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)