home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 9 Archive / 09-Archive.zip / PAX20.ZIP / PAX.MAN < prev    next >
Text File  |  1990-11-12  |  15KB  |  349 lines
  1. NAME
  2.      pax - portable archive exchange
  3.  
  4. SYNOPSIS
  5.      pax [-cimopuvy] [-f archive] [-s replstr] [-t device] [pat-
  6.          tern...]
  7.  
  8.      pax -r [-cimnopuvy] [-f archive] [-s replstr] [-t device]
  9.             [pattern...]
  10.  
  11.      pax -w [-adimuvy] [-b blocking] [-f archive] [-s replstr]
  12.             [-t device] [-x format] [pathname...]
  13.  
  14.      pax -rw [-ilmopuvy] [-s replstr] [pathname...] directory
  15.  
  16. DESCRIPTION
  17.      Pax reads and writes archive files which conform to the
  18.      Archive/Interchange File Format specified in IEEE Std.
  19.      1003.1-1988.  Pax can also read, but not write, a number of
  20.      other file formats in addition to those specified in the
  21.      Archive/Interchange File Format description.  Support for
  22.      these traditional file formats, such as V7 tar and System V
  23.      binary cpio format archives, is provided for backward compa-
  24.      tibility and to maximize portability.
  25.  
  26.      Pax will also support traditional cpio and System V tar
  27.      interfaces if invoked with the name "cpio" or "tar" respec-
  28.      tively.  See the cpio(1) or tar(1) manual pages for more
  29.      details.
  30.  
  31.      Combinations of the -r and -w command line arguments specify
  32.      whether pax will read, write or list the contents of the
  33.      specified archive, or move the specified files to another
  34.      directory.
  35.  
  36.      The command line arguments are:
  37.  
  38.      -w   writes the files and directories specified by pathname
  39.           operands to the standard output together with the path-
  40.           name and status information prescribed by the archive
  41.           format used.  A directory pathname operand refers to
  42.           the files and (recursively) subdirectories of that
  43.           directory.  If no pathname operands are given, then the
  44.           standard input is read to get a list of pathnames to
  45.           copy, one pathname per line.  In this case, only those
  46.           pathnames appearing on the standard input are copied.
  47.  
  48.      -r   Pax reads an archive file from the standard input.
  49.           Only files with names that match any of the pattern
  50.           operands are selected for extraction.  The selected
  51.           files are conditionally created and copied relative to
  52.           the current directory tree, subject to the options
  53.           described below.  By default, the owner and group of
  54.           selected files will be that of the invoking process,
  55.           and the permissions and modification times will be the
  56.           sames as those in the archive.
  57.  
  58.           The supported archive formats are automatically
  59.           detected on input.  The default output format is ustar,
  60.           but may be overridden by the -x format option described
  61.           below.
  62.  
  63.      -rw  Pax reads the files and directories named in the path-
  64.           name operands and copies them to the destination direc-
  65.           tory.  A directory pathname operand refers to the files
  66.           and (recursively) subdirectories of that directory.  If
  67.           no pathname operands are given, the standard input is
  68.           read to get a list of pathnames to copy, one pathname
  69.           per line.  In this case, only those pathnames appearing
  70.           on the standard input are copied.  The directory named
  71.           by the directory operand must exist and have the proper
  72.           permissions before the copy can occur.
  73.  
  74.      If neither the -r or -w options are given, then pax will
  75.      list the contents of the specified archive.  In this mode,
  76.      pax lists normal files one per line, hard link pathnames as
  77.  
  78.                pathname == linkname
  79.  
  80.      and symbolic link pathnames (if supported by the implementa-
  81.      tion) as
  82.  
  83.                pathname -> linkname
  84.  
  85.      where pathname is the name of the file being extracted, and
  86.      linkname is the name of a file which appeared earlier in the
  87.      archive.
  88.  
  89.      If the -v option is specified, then pax list normal path-
  90.      names in the same format used by the ls utility with the -l
  91.      option.  Hard links are shown as
  92.  
  93.                <ls -l listing> == linkname
  94.  
  95.      and symbolic links (if supported) are shown as
  96.  
  97.                <ls -l listing> -> linkname
  98.  
  99.  
  100.      Pax is capable of reading and writing archives which span
  101.      multiple physical volumes.  Upon detecting an end of medium
  102.      on an archive which is not yet completed, pax will prompt
  103.      the user for the next volume of the archive and will allow
  104.      the user to specify the location of the next volume.
  105.  
  106.      Options
  107.      The following options are available:
  108.  
  109.      -a        The files specified by pathname are appended to
  110.                the specified archive.
  111.  
  112.      -b blocking
  113.                Block the output at blocking bytes per write to
  114.                the archive file.  A k suffix multiplies blocking
  115.                by 1024, a b suffix multiplies blocking by 512 and
  116.                a m suffix multiplies blocking by 1048576 (1 mega-
  117.                byte).  For machines with 16-bit int's (VAXen,
  118.                XENIX-286, etc.), the maximum buffer size is 32k-
  119.                1.  If not specified, blocking is automatically
  120.                determined on input and is ignored for -rw.
  121.  
  122.      -c        Complement the match sense of the pattern
  123.                operands.
  124.  
  125.      -d        Intermediate directories not explicitly listed in
  126.                the archive are not created.  This option is
  127.                ignored unless the -r option is specified.
  128.  
  129.      -f archive
  130.                The archive option specifies the pathname of the
  131.                input or output archive, overriding the default of
  132.                standard input for -r or standard output for -w.
  133.  
  134.      -i        Interactively rename files.  Substitutions speci-
  135.                fied by -s options (described below) are performed
  136.                before requesting the new file name from the user.
  137.                A file is skipped if an empty line is entered and
  138.                pax exits with an exit status of 0 if EOF is
  139.                encountered.
  140.  
  141.      -l        Files are linked rather than copied when possible.
  142.  
  143.      -m        File modification times are not retained.
  144.  
  145.      -n        When -r is specified, but -w is not, the pattern
  146.                arguments are treated as ordinary file names.
  147.                Only the first occurrence of each of these files
  148.                in the input archive is read.  The pax utility
  149.                exits with a zero exit status after all files in
  150.                the list have been read.  If one or more files in
  151.                the list is not found, pax writes a diagnostic to
  152.                standard error for each of the files and exits
  153.                with a non-zero exit status.  the file names are
  154.                compared before any of the -i, -s, or -y options
  155.                are applied.
  156.  
  157.      -o        Restore file ownership as specified in the
  158.                archive.  The invoking process must have appropri-
  159.                ate privileges to accomplish this.
  160.  
  161.      -p        Preserve the access time of the input files after
  162.                they have been copied.
  163.  
  164.      -s replstr
  165.                File names are modified according to the substitu-
  166.                tion expression using the syntax of ed(1) as
  167.                shown:
  168.  
  169.                          -s /old/new/[gp]
  170.  
  171.                Any non null character may be used as a delimiter
  172.                (a / is used here as an example).  Multiple -s
  173.                expressions may be specified; the expressions are
  174.                applied in the order specified terminating with
  175.                the first successful substitution.  The optional
  176.                trailing p causes successful mappings to be listed
  177.                on standard error.  The optional trailing g causes
  178.                the old expression to be replaced each time it
  179.                occurs in the source string.  Files that substi-
  180.                tute to an empty string are ignored both on input
  181.                and output.
  182.  
  183.      -t device The device option argument is an implementation-
  184.                defined identifier that names the input or output
  185.                archive device, overriding the default of standard
  186.                input for -r and standard output for -w.
  187.  
  188.      -u        Copy each file only if it is newer than a pre-
  189.                existing file with the same name.  This implies
  190.                -a.
  191.  
  192.      -v        List file names as they are encountered.  Produces
  193.                a verbose table of contents listing on the stan-
  194.                dard output when both -r and -w are omitted, oth-
  195.                erwise the file names are printed to standard
  196.                error as they are encountered in the archive.
  197.  
  198.      -x format Specifies the output archive format.  The input
  199.                format, which must be one of the following, is
  200.                automatically determined when the -r option is
  201.                used.  The supported formats are:
  202.  
  203.                cpio   The extended CPIO interchange format speci-
  204.                       fied in Extended CPIO Format in IEEE Std.
  205.                       1003.1-1988.
  206.  
  207.                ustar  The extended TAR interchange format speci-
  208.                       fied in Extended TAR Format in IEEE Std.
  209.                       1003.1-1988. This is the default archive
  210.                       format.
  211.  
  212.      -y        Interactively prompt for the disposition of each
  213.                file.  Substitutions specified by -s options
  214.                (described above) are performed before prompting
  215.                the user for disposition.  EOF or an input line
  216.                starting with the character q caused pax to exit.
  217.                Otherwise, an input line starting with anything
  218.                other than y causes the file to be ignored.  This
  219.                option cannot be used in conjunction with the -i
  220.                option.
  221.  
  222.      Only the last of multiple -f or -t options take effect.
  223.  
  224.      When writing to an archive, the standard input is used as a
  225.      list of pathnames if no pathname operands are specified.
  226.      The format is one pathname per line.  Otherwise, the stan-
  227.      dard input is the archive file, which is formatted according
  228.      to one of the specifications in Archive/Interchange File
  229.      format in IEEE Std. 1003.1-1988, or some other
  230.      implementation-defined format.
  231.  
  232.      The user ID and group ID of the process, together with the
  233.      appropriate privileges, affect the ability of pax to restore
  234.      ownership and permissions attributes of the archived files.
  235.      (See format-reading utility in Archive/Interchange File For-
  236.      mat in IEEE Std. 1003.1-1988.)
  237.  
  238.      The options -a, -c, -d, -i, -l, -p, -t, -u, and -y are pro-
  239.      vided for functional compatibility with the historical cpio
  240.      and tar utilities.  The option defaults were chosen based on
  241.      the most common usage of these options, therefore, some of
  242.      the options have meanings different than those of the his-
  243.      torical commands.
  244.  
  245.      Operands
  246.      The following operands are available:
  247.  
  248.      directory The destination directory pathname for copies when
  249.                both the -r and -w options are specified.  The
  250.                directory must exist and be writable before the
  251.                copy or and error results.
  252.  
  253.      pathname  A file whose contents are used instead of the
  254.                files named on the standard input.  When a direc-
  255.                tory is named, all of its files and (recursively)
  256.                subdirectories are copied as well.
  257.  
  258.      pattern   A pattern is given in the standard shell pattern
  259.                matching notation.  The default if no pattern is
  260.                specified is *, which selects all files.
  261.  
  262. EXAMPLES
  263.      The following command
  264.  
  265.                pax -w -f /dev/rmt0 .
  266.  
  267.      copies the contents of the current directory to tape drive
  268.      0.
  269.  
  270.      The commands
  271.  
  272.                mkdir newdir
  273.                cd olddir
  274.                pax -rw . newdir
  275.  
  276.      copies the contents of olddir to newdir .
  277.  
  278.      The command
  279.  
  280.                pax -r -s ',//*usr//*,,' -f pax.out
  281.  
  282.      reads the archive pax.out with all files rooted in "/usr" in
  283.      the archive extracted relative to the current directory.
  284.  
  285. FILES
  286.      /dev/tty  used to prompt the user for information when the
  287.                -i or -y options are specified.
  288.  
  289. SEE ALSO
  290.      cpio(1), find(1), tar(1), cpio(5), tar(5)
  291.  
  292. DIAGNOSTICS
  293.      Pax will terminate immediately, without processing any addi-
  294.      tional files on the command line or in the archive.
  295.  
  296. EXIT CODES
  297.      Pax will exit with one of the following values:
  298.  
  299.      0    All files in the archive were processed successfully.
  300.  
  301.      >0   Pax aborted due to errors encountered during operation.
  302.  
  303. BUGS
  304.      Special permissions may be required to copy or extract spe-
  305.      cial files.
  306.  
  307.      Device, user ID, and group ID numbers larger than 65535
  308.      cause additional header records to be output.  These records
  309.      are ignored by some historical version of cpio(1) and
  310.      tar(1).
  311.  
  312.      The archive formats described in Archive/Interchange File
  313.      Format have certain restrictions that have been carried over
  314.      from historical usage.  For example, there are restrictions
  315.      on the length of pathnames stored in the archive.
  316.  
  317.      When getting an "ls -l" style listing on tar format
  318.      archives, link counts are listed as zero since the ustar
  319.      archive format does not keep link count information.
  320.  
  321.      On 16 bit architectures, the largest buffer size is 32k-1.
  322.      This is due, in part, to using integers in the buffer allo-
  323.      cation schemes, however, on many of these machines, it is
  324.      not possible to allocate blocks of memory larger than 32k.
  325.  
  326. COPYRIGHT
  327.      Copyright (c) 1989 Mark H. Colburn.
  328.      All rights reserved.
  329.  
  330.      Redistribution and use in source and binary forms are per-
  331.      mitted provided that the above copyright notice is dupli-
  332.      cated in all such forms and that any documentation,
  333.      advertising materials, and other materials related to such
  334.      distribution and use acknowledge that the software was
  335.      developed by Mark H. Colburn.
  336.  
  337.      THE SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS
  338.      OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE
  339.      IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PAR-
  340.      TICULAR PURPOSE.
  341.  
  342. AUTHOR
  343.      Mark H. Colburn
  344.      Minnetech Consulting, Inc.
  345.      3232 Aquila Lane
  346.      St. Louis Park, MN 55426
  347.  
  348.      mark@Minnetech.MN.ORG
  349.