


                                                           PAX(1)



NAME
     pax - portable archive exchange

SYNOPSIS
     pax [-cimopuvy] [-f archive] [-s replstr] [-t device] [pat-
         tern...]

     pax -r [-cimnopuvy] [-f archive] [-s replstr] [-t device]
            [pattern...]

     pax -w [-adimuvy] [-b blocking] [-f archive] [-s replstr]
            [-t device] [-x format] [pathname...]

     pax -rw [-ilmopuvy] [-s replstr] [pathname...] directory

DESCRIPTION
     Pax reads and writes archive files which conform to the
     Archive/Interchange File Format specified in IEEE Std.
     1003.1-1988.  Pax can also read, but not write, a number of
     other file formats in addition to those specified in the
     Archive/Interchange File Format description.  Support for
     these traditional file formats, such as V7 tar and System V
     binary cpio format archives, is provided for backward compa-
     tibility and to maximize portability.

     Pax will also support traditional cpio and System V tar
     interfaces if invoked with the name "cpio" or "tar" respec-
     tively.  See the cpio(1) or tar(1) manual pages for more
     details.

     Combinations of the -r and -w command line arguments specify
     whether pax will read, write or list the contents of the
     specified archive, or move the specified files to another
     directory.

     The command line arguments are:

     -w   writes the files and directories specified by pathname
          operands to the standard output together with the path-
          name and status information prescribed by the archive
          format used.  A directory pathname operand refers to
          the files and (recursively) subdirectories of that
          directory.  If no pathname operands are given, then the
          standard input is read to get a list of pathnames to
          copy, one pathname per line.  In this case, only those
          pathnames appearing on the standard input are copied.

     -r   Pax reads an archive file from the standard input.
          Only files with names that match any of the pattern
          operands are selected for extraction.  The selected
          files are conditionally created and copied relative to
          the current directory tree, subject to the options



                                                                1






PAX(1)



          described below.  By default, the owner and group of
          selected files will be that of the invoking process,
          and the permissions and modification times will be the
          sames as those in the archive.

          The supported archive formats are automatically
          detected on input.  The default output format is ustar,
          but may be overridden by the -x format option described
          below.

     -rw  Pax reads the files and directories named in the path-
          name operands and copies them to the destination direc-
          tory.  A directory pathname operand refers to the files
          and (recursively) subdirectories of that directory.  If
          no pathname operands are given, the standard input is
          read to get a list of pathnames to copy, one pathname
          per line.  In this case, only those pathnames appearing
          on the standard input are copied.  The directory named
          by the directory operand must exist and have the proper
          permissions before the copy can occur.

     If neither the -r or -w options are given, then pax will
     list the contents of the specified archive.  In this mode,
     pax lists normal files one per line, hard link pathnames as

               pathname == linkname

     and symbolic link pathnames (if supported by the implementa-
     tion) as

               pathname -> linkname

     where pathname is the name of the file being extracted, and
     linkname is the name of a file which appeared earlier in the
     archive.

     If the -v option is specified, then pax list normal path-
     names in the same format used by the ls utility with the -l
     option.  Hard links are shown as

               <ls -l listing> == linkname

     and symbolic links (if supported) are shown as

               <ls -l listing> -> linkname


     Pax is capable of reading and writing archives which span
     multiple physical volumes.  Upon detecting an end of medium
     on an archive which is not yet completed, pax will prompt
     the user for the next volume of the archive and will allow
     the user to specify the location of the next volume.



2






                                                           PAX(1)



     Options
     The following options are available:

     -a        The files specified by pathname are appended to
               the specified archive.

     -b blocking
               Block the output at blocking bytes per write to
               the archive file.  A k suffix multiplies blocking
               by 1024, a b suffix multiplies blocking by 512 and
               a m suffix multiplies blocking by 1048576 (1 mega-
               byte).  For machines with 16-bit int's (VAXen,
               XENIX-286, etc.), the maximum buffer size is 32k-
               1.  If not specified, blocking is automatically
               determined on input and is ignored for -rw.

     -c        Complement the match sense of the pattern
               operands.

     -d        Intermediate directories not explicitly listed in
               the archive are not created.  This option is
               ignored unless the -r option is specified.

     -f archive
               The archive option specifies the pathname of the
               input or output archive, overriding the default of
               standard input for -r or standard output for -w.

     -i        Interactively rename files.  Substitutions speci-
               fied by -s options (described below) are performed
               before requesting the new file name from the user.
               A file is skipped if an empty line is entered and
               pax exits with an exit status of 0 if EOF is
               encountered.

     -l        Files are linked rather than copied when possible.

     -m        File modification times are not retained.

     -n        When -r is specified, but -w is not, the pattern
               arguments are treated as ordinary file names.
               Only the first occurrence of each of these files
               in the input archive is read.  The pax utility
               exits with a zero exit status after all files in
               the list have been read.  If one or more files in
               the list is not found, pax writes a diagnostic to
               standard error for each of the files and exits
               with a non-zero exit status.  the file names are
               compared before any of the -i, -s, or -y options
               are applied.

     -o        Restore file ownership as specified in the



                                                                3






PAX(1)



               archive.  The invoking process must have appropri-
               ate privileges to accomplish this.

     -p        Preserve the access time of the input files after
               they have been copied.

     -s replstr
               File names are modified according to the substitu-
               tion expression using the syntax of ed(1) as
               shown:

                         -s /old/new/[gp]

               Any non null character may be used as a delimiter
               (a / is used here as an example).  Multiple -s
               expressions may be specified; the expressions are
               applied in the order specified terminating with
               the first successful substitution.  The optional
               trailing p causes successful mappings to be listed
               on standard error.  The optional trailing g causes
               the old expression to be replaced each time it
               occurs in the source string.  Files that substi-
               tute to an empty string are ignored both on input
               and output.

     -t device The device option argument is an implementation-
               defined identifier that names the input or output
               archive device, overriding the default of standard
               input for -r and standard output for -w.

     -u        Copy each file only if it is newer than a pre-
               existing file with the same name.  This implies
               -a.

     -v        List file names as they are encountered.  Produces
               a verbose table of contents listing on the stan-
               dard output when both -r and -w are omitted, oth-
               erwise the file names are printed to standard
               error as they are encountered in the archive.

     -x format Specifies the output archive format.  The input
               format, which must be one of the following, is
               automatically determined when the -r option is
               used.  The supported formats are:

               cpio   The extended CPIO interchange format speci-
                      fied in Extended CPIO Format in IEEE Std.
                      1003.1-1988.

               ustar  The extended TAR interchange format speci-
                      fied in Extended TAR Format in IEEE Std.
                      1003.1-1988. This is the default archive



4






                                                           PAX(1)



                      format.

     -y        Interactively prompt for the disposition of each
               file.  Substitutions specified by -s options
               (described above) are performed before prompting
               the user for disposition.  EOF or an input line
               starting with the character q caused pax to exit.
               Otherwise, an input line starting with anything
               other than y causes the file to be ignored.  This
               option cannot be used in conjunction with the -i
               option.

     Only the last of multiple -f or -t options take effect.

     When writing to an archive, the standard input is used as a
     list of pathnames if no pathname operands are specified.
     The format is one pathname per line.  Otherwise, the stan-
     dard input is the archive file, which is formatted according
     to one of the specifications in Archive/Interchange File
     format in IEEE Std. 1003.1-1988, or some other
     implementation-defined format.

     The user ID and group ID of the process, together with the
     appropriate privileges, affect the ability of pax to restore
     ownership and permissions attributes of the archived files.
     (See format-reading utility in Archive/Interchange File For-
     mat in IEEE Std. 1003.1-1988.)

     The options -a, -c, -d, -i, -l, -p, -t, -u, and -y are pro-
     vided for functional compatibility with the historical cpio
     and tar utilities.  The option defaults were chosen based on
     the most common usage of these options, therefore, some of
     the options have meanings different than those of the his-
     torical commands.

     Operands
     The following operands are available:

     directory The destination directory pathname for copies when
               both the -r and -w options are specified.  The
               directory must exist and be writable before the
               copy or and error results.

     pathname  A file whose contents are used instead of the
               files named on the standard input.  When a direc-
               tory is named, all of its files and (recursively)
               subdirectories are copied as well.

     pattern   A pattern is given in the standard shell pattern
               matching notation.  The default if no pattern is
               specified is *, which selects all files.




                                                                5






PAX(1)



EXAMPLES
     The following command

               pax -w -f /dev/rmt0 .

     copies the contents of the current directory to tape drive
     0.

     The commands

               mkdir newdir
               cd olddir
               pax -rw . newdir

     copies the contents of olddir to newdir .

     The command

               pax -r -s ',//*usr//*,,' -f pax.out

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

FILES
     /dev/tty  used to prompt the user for information when the
               -i or -y options are specified.

SEE ALSO
     cpio(1), find(1), tar(1), cpio(5), tar(5)

DIAGNOSTICS
     Pax will terminate immediately, without processing any addi-
     tional files on the command line or in the archive.

EXIT CODES
     Pax will exit with one of the following values:

     0    All files in the archive were processed successfully.

     >0   Pax aborted due to errors encountered during operation.

BUGS
     Special permissions may be required to copy or extract spe-
     cial files.

     Device, user ID, and group ID numbers larger than 65535
     cause additional header records to be output.  These records
     are ignored by some historical version of cpio(1) and
     tar(1).

     The archive formats described in Archive/Interchange File
     Format have certain restrictions that have been carried over



6






                                                           PAX(1)



     from historical usage.  For example, there are restrictions
     on the length of pathnames stored in the archive.

     When getting an "ls -l" style listing on tar format
     archives, link counts are listed as zero since the ustar
     archive format does not keep link count information.

     On 16 bit architectures, the largest buffer size is 32k-1.
     This is due, in part, to using integers in the buffer allo-
     cation schemes, however, on many of these machines, it is
     not possible to allocate blocks of memory larger than 32k.

COPYRIGHT
     Copyright (c) 1989 Mark H. Colburn.
     All rights reserved.

     Redistribution and use in source and binary forms are per-
     mitted provided that the above copyright notice is dupli-
     cated in all such forms and that any documentation,
     advertising materials, and other materials related to such
     distribution and use acknowledge that the software was
     developed by Mark H. Colburn and sponsored by The USENIX
     Association.

     THE SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS
     OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE
     IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PAR-
     TICULAR PURPOSE.

AUTHOR
     Mark H. Colburn
     Minnetech Consulting, Inc.
     117 Mackubin Street, Suite 1
     St. Paul, MN 55102
     mark@jhereg.MN.ORG


     Sponsored by The USENIX Association for public distribution.

















                                                                7



