Return to pax.1 CVS log

Up to [MW Coherent from dump] / coherent / g / usr / bin / pax / doc

Annotation of coherent/g/usr/bin/pax/doc/pax.1, revision 1.1

1.1     ! root        1: .\" $Id: pax.1,v 1.1 88/12/23 18:02:22 mark Rel $
        !             2: .TH PAX 1 "USENIX Association" ""
        !             3: .SH NAME
        !             4: pax \- portable archive exchange 
        !             5: .SH SYNOPSIS
        !             6: .TP \w'\fBpax\fR\ 'u
        !             7: .B pax
        !             8: .RB [ \-cimopuvy ]
        !             9: .RI "[\fB\-f\fR" " archive" ]
        !            10: .RI "[\fB\-s\fR" " replstr" ]
        !            11: .RI "[\fB\-t\fR" " device" ] 
        !            12: .RI [ pattern... ]
        !            13: .TP \w'\fBpax\ \-r\fR\ 'u
        !            14: .B "pax\ \-r"
        !            15: .RB [ \-cimnopuvy ]
        !            16: .RI "[\fB\-f\fR" " archive" ]
        !            17: .RI "[\fB\-s\fR" " replstr" ] 
        !            18: .RI "[\fB\-t\fR" " device" ] 
        !            19: .RI [ pattern... ]
        !            20: .TP \w'\fBpax\ \-w\fR\ 'u
        !            21: .B "pax\ \-w"
        !            22: .RB [ \-adimuvy ] 
        !            23: .RI "[\fB\-b\fR" " blocking" ]
        !            24: .RI "[\fB\-f\fR" " archive" ] 
        !            25: .RI "[\fB\-s\fR" " replstr" ] 
        !            26: .RI "[\fB\-t\fR" " device" ] 
        !            27: .RI "[\fB\-x\fR" " format" ]
        !            28: .RI [ pathname... ]
        !            29: .TP \w'\fBpax\ \-rw\fR\ 'u
        !            30: .B "pax\ \-rw"
        !            31: .RB [ \-ilmopuvy ] 
        !            32: .RI "[\fB\-s\fR" " replstr" ] 
        !            33: .RI [ pathname... ]
        !            34: directory
        !            35: .SH DESCRIPTION
        !            36: .I Pax 
        !            37: reads and writes archive files which conform to the 
        !            38: .B "Archive/Interchange File Format" 
        !            39: specified in 
        !            40: .IR "IEEE Std. 1003.1-1988" .
        !            41: .I Pax
        !            42: can also read, but not write, a number of other file formats
        !            43: in addition to those specified in the 
        !            44: .B "Archive/Interchange File Format"
        !            45: description.
        !            46: Support for these traditional file formats, such as V7 
        !            47: .I "tar" 
        !            48: and System V binary 
        !            49: .I "cpio" 
        !            50: format archives,
        !            51: is provided for backward compatibility and to maximize portability.
        !            52: .PP
        !            53: .I Pax 
        !            54: will also support traditional 
        !            55: .I cpio 
        !            56: and 
        !            57: System V
        !            58: .I tar
        !            59: interfaces if invoked with the name
        !            60: "cpio" or "tar" respectively.
        !            61: See the 
        !            62: .I cpio(1) 
        !            63: or 
        !            64: .I tar(1)
        !            65: manual pages for more details.
        !            66: .PP
        !            67: Combinations of the
        !            68: .B \-r 
        !            69: and 
        !            70: .B \-w
        !            71: command line arguments specify whether 
        !            72: .I pax 
        !            73: will read, write or list the contents of the specified archive,
        !            74: or move the specified files to another directory.
        !            75: .PP
        !            76: The command line arguments are:
        !            77: .TP .5i
        !            78: .B \-w
        !            79: writes the files and directories specified by 
        !            80: .I pathname
        !            81: operands to the standard output together with the pathname and status 
        !            82: information prescribed by the archive format used.
        !            83: A directory
        !            84: .I pathname
        !            85: operand refers to the files and (recursively) subdirectories of that 
        !            86: directory.
        !            87: If no 
        !            88: .I pathname 
        !            89: operands are given, then the standard input is read to get a
        !            90: list of pathnames to copy, one pathname per line.
        !            91: In this case, only those pathnames appearing on the standard input are
        !            92: copied.
        !            93: .TP .5i
        !            94: .B \-r
        !            95: .I Pax
        !            96: reads an archive file from the standard input.
        !            97: Only files with names that match any of the 
        !            98: .I pattern
        !            99: operands are selected for extraction.
        !           100: The selected files are conditionally created and copied relative to the
        !           101: current directory tree, subject to the options described below.
        !           102: By default, the owner and group of selected files will be that of the
        !           103: invoking process, and the permissions and modification times will be the
        !           104: sames as those in the archive.
        !           105: .RS .5i
        !           106: .PP
        !           107: The supported archive formats are automatically detected on input.
        !           108: The default output format is 
        !           109: .IR ustar ,
        !           110: but may be overridden by the 
        !           111: .B \-x
        !           112: .I format
        !           113: option described below.
        !           114: .RE
        !           115: .TP .5i
        !           116: .B \-rw
        !           117: .I Pax 
        !           118: reads the files and directories named in the
        !           119: .I pathname
        !           120: operands and copies them to the destination 
        !           121: .IR directory .
        !           122: A directory
        !           123: .I pathname 
        !           124: operand refers to the files and (recursively) subdirectories of that
        !           125: directory.
        !           126: If no 
        !           127: .I pathname
        !           128: operands are given, the standard input is read to get a list of pathnames
        !           129: to copy, one pathname per line.
        !           130: In this case, only those pathnames appearing on the standard input are
        !           131: copied.
        !           132: The directory named by the 
        !           133: .I directory
        !           134: operand must exist and have the proper permissions before the copy can
        !           135: occur.
        !           136: .PP
        !           137: If neither the
        !           138: .BR \-r " or " \-w 
        !           139: options are given, then 
        !           140: .I pax
        !           141: will list the contents of the specified archive.
        !           142: In this mode, 
        !           143: .I pax 
        !           144: lists normal files one per line, hard link pathnames as
        !           145: .sp
        !           146: .RS 1i
        !           147: .IR pathname " == " linkname
        !           148: .RE
        !           149: .sp
        !           150: and symbolic link pathnames (if supported by the implementation) as
        !           151: .sp
        !           152: .RS 1i
        !           153: .IR pathname " -> " linkname
        !           154: .RE
        !           155: .sp
        !           156: where 
        !           157: .I pathname
        !           158: is the name of the file being extracted, and
        !           159: .I linkname
        !           160: is the name of a file which appeared earlier in the archive.
        !           161: .PP
        !           162: If the 
        !           163: .B \-v
        !           164: option is specified, then 
        !           165: .I pax 
        !           166: list normal pathnames in the same format used by the 
        !           167: .I ls
        !           168: utility with the
        !           169: .B \-l
        !           170: option.
        !           171: Hard links are shown as
        !           172: .sp
        !           173: .RS 1i
        !           174: .IR "<ls -l listing>" " == " linkname
        !           175: .RE
        !           176: .sp
        !           177: and symbolic links (if supported) are shown as
        !           178: .sp
        !           179: .RS 1i
        !           180: .IR "<ls -l listing>" " -> " linkname
        !           181: .RE
        !           182: .sp 
        !           183: .PP
        !           184: .I Pax 
        !           185: is capable of reading and writing archives which span multiple physical 
        !           186: volumes.
        !           187: Upon detecting an end of medium on an archive which is not yet completed,
        !           188: .I pax 
        !           189: will prompt the user for the next volume of the archive and will allow the 
        !           190: user to specify the location of the next volume.
        !           191: .SS Options
        !           192: The following options are available:
        !           193: .TP 1i
        !           194: .B \-a
        !           195: The files specified by
        !           196: .I pathname
        !           197: are appended to the specified archive.
        !           198: .TP 1i
        !           199: .BI \-b " blocking"
        !           200: Block the output at
        !           201: .I blocking
        !           202: bytes per write to the archive file.
        !           203: A 
        !           204: .B k
        !           205: suffix multiplies 
        !           206: .I blocking 
        !           207: by 1024, a
        !           208: .B b 
        !           209: suffix multiplies 
        !           210: .I blocking 
        !           211: by 512 and a 
        !           212: .B m
        !           213: suffix multiplies 
        !           214: .I blocking 
        !           215: by 1048576 (1 megabyte).
        !           216: If not specified,
        !           217: .I blocking 
        !           218: is automatically determined on input and is ignored for 
        !           219: .B \-rw.
        !           220: .TP 1i
        !           221: .B \-c
        !           222: Complement the match sense of the the 
        !           223: .I pattern
        !           224: operands.
        !           225: .TP 1i
        !           226: .B \-d
        !           227: Intermediate directories not explicitly listed in the archive are not 
        !           228: created.
        !           229: This option is ignored unless
        !           230: the 
        !           231: .B \-r
        !           232: option is specified.
        !           233: .TP 1i
        !           234: .BI \-f " archive"
        !           235: The
        !           236: .I archive
        !           237: option specifies the pathname of the input or output archive,
        !           238: overriding the default of standard input for 
        !           239: .B \-r
        !           240: or standard output for
        !           241: .BR \-w .
        !           242: .TP 1i
        !           243: .B \-i
        !           244: Interactively rename files.
        !           245: Substitutions specified by 
        !           246: .B \-s
        !           247: options (described below)
        !           248: are performed before requesting the new file name from the user.
        !           249: A file is skipped if an empty line is entered and
        !           250: .I pax
        !           251: exits with an exit status of 0 if 
        !           252: .B EOF 
        !           253: is encountered.
        !           254: .TP 1i
        !           255: .B \-l
        !           256: Files are linked rather than copied when possible.
        !           257: .TP 1i
        !           258: .B \-m
        !           259: File modification times are not retained.
        !           260: .TP 1i
        !           261: .B \-n
        !           262: When 
        !           263: .B \-r
        !           264: is specified, but
        !           265: .B \-w
        !           266: is not, the 
        !           267: .I pattern
        !           268: arguments are treated as ordinary file names.
        !           269: Only the first occurrence of each of these files in the input archive
        !           270: is read.
        !           271: The
        !           272: .B pax
        !           273: utility exits with a zero exit status after all files in the list have been
        !           274: read.
        !           275: If one or more files in the list is not found,
        !           276: .B pax
        !           277: writes a diagnostic to standard error for each of the files and exits with
        !           278: a non-zero exit status.
        !           279: the file names are compared before any of the 
        !           280: .BR \-i ,
        !           281: .BR \-s ,
        !           282: or
        !           283: .B \-y
        !           284: options are applied.
        !           285: .TP 1i
        !           286: .B \-o
        !           287: Restore file ownership as specified in the archive.
        !           288: The invoking process must have appropriate privileges to accomplish this.
        !           289: .TP 1i
        !           290: .B \-p
        !           291: Preserve the access time of the input files after they have been copied.
        !           292: .TP 1i
        !           293: .BI \-s " replstr"
        !           294: File names are modified according to the substitution expression using the 
        !           295: syntax of 
        !           296: .I "ed(1)"
        !           297: as shown:
        !           298: .sp
        !           299: .RS 2i
        !           300: -s /\fIold\fR/\fInew\fR/\fB[\fRgp\fB]\fR
        !           301: .RE
        !           302: .RS 1i
        !           303: .PP
        !           304: Any non null character may be used as a delimiter (a / is used here as an
        !           305: example).
        !           306: Multiple 
        !           307: .B \-s
        !           308: expressions may be specified; the expressions are applied in the order
        !           309: specified terminating with the first successful substitution.
        !           310: The optional trailing 
        !           311: .B p
        !           312: causes successful mappings to be listed on standard error.
        !           313: The optional trailing
        !           314: .B g
        !           315: causes the 
        !           316: .I old 
        !           317: expression to be replaced each time it occurs in the source string.
        !           318: Files that substitute to an empty string are ignored both on input and
        !           319: output.
        !           320: .RE
        !           321: .TP 1i
        !           322: .BI \-t " device"
        !           323: The
        !           324: .I device
        !           325: option argument is an implementation-defined identifier that names the input
        !           326: or output archive device, overriding the default of standard input for
        !           327: .B \-r
        !           328: and standard output for
        !           329: .BR \-w .
        !           330: .TP 1i
        !           331: .B \-u
        !           332: Copy each file only if it is newer than a pre-existing file with the same
        !           333: name.
        !           334: This implies 
        !           335: .BR \-a .
        !           336: .TP 1i
        !           337: .B \-v
        !           338: List file names as they are encountered.
        !           339: Produces a verbose table of contents listing on the standard output when both 
        !           340: .B \-r 
        !           341: and
        !           342: .B \-w
        !           343: are omitted,
        !           344: otherwise the file names are printed to standard error as they are
        !           345: encountered in the archive.
        !           346: .TP 1i
        !           347: .BI \-x " format"
        !           348: Specifies the output archive
        !           349: .IR format .
        !           350: The input format, which must be one of the following, is automatically
        !           351: determined when the
        !           352: .B \-r 
        !           353: option is used.
        !           354: The supported formats are:
        !           355: .TP 1i
        !           356: .I cpio
        !           357: The extended 
        !           358: .I CPIO
        !           359: interchange format specified in
        !           360: .B "Extended CPIO Format" in 
        !           361: .I "IEEE Std. 1003.1-1988."
        !           362: .TP 1i
        !           363: .I ustar
        !           364: The extended 
        !           365: .I TAR
        !           366: interchange format specified in
        !           367: .B "Extended TAR Format" in 
        !           368: .I "IEEE Std. 1003.1-1988."
        !           369: This is the default archive format.
        !           370: .RE
        !           371: .TP 1i
        !           372: .B \-y
        !           373: Interactively prompt for the disposition of each file.
        !           374: Substitutions specified by 
        !           375: .B \-s
        !           376: options (described above)
        !           377: are performed before prompting the user for disposition.
        !           378: .B EOF
        !           379: or an input line starting with the character
        !           380: .B q
        !           381: caused
        !           382: .I pax
        !           383: to exit.
        !           384: Otherwise, an input line starting with anything other than 
        !           385: .B y
        !           386: causes the file to be ignored.
        !           387: This option cannot be used in conjunction with the 
        !           388: .B \-i 
        !           389: option.
        !           390: .PP
        !           391: Only the last of multiple 
        !           392: .B \-f 
        !           393: or
        !           394: .B \-t
        !           395: options take effect.
        !           396: .PP
        !           397: When writing to an archive, the
        !           398: standard input is used as a list of pathnames if no
        !           399: .I pathname
        !           400: operands are specified.
        !           401: The format is one pathname per line.
        !           402: Otherwise, the standard input is the archive file,
        !           403: which is formatted according to one of the specifications in
        !           404: .B "Archive/Interchange File format"
        !           405: in 
        !           406: .IR "IEEE Std. 1003.1-1988" ,
        !           407: or some other implementation-defined format.
        !           408: .PP
        !           409: The user ID and group ID of the process, together with the appropriate
        !           410: privileges, affect the ability of 
        !           411: .I pax
        !           412: to restore ownership and permissions attributes of the archived files.
        !           413: (See 
        !           414: .I "format-reading utility"
        !           415: in
        !           416: .B "Archive/Interchange File Format"
        !           417: in 
        !           418: .IR "IEEE Std. 1003.1-1988" ".)"
        !           419: .PP
        !           420: The options
        !           421: .BR \-a ,
        !           422: .BR \-c ,
        !           423: .BR \-d ,
        !           424: .BR \-i ,
        !           425: .BR \-l ,
        !           426: .BR \-p ,
        !           427: .BR \-t ,
        !           428: .BR \-u ,
        !           429: and
        !           430: .BR \-y 
        !           431: are provided for functional compatibility with the historical
        !           432: .I cpio
        !           433: and
        !           434: .I tar
        !           435: utilities.
        !           436: The option defaults were chosen based on the most common usage of these
        !           437: options, therefore, some of the options have meanings different than
        !           438: those of the historical commands.
        !           439: .SS Operands
        !           440: The following operands are available:
        !           441: .TP 1i
        !           442: .I directory
        !           443: The destination directory pathname for copies when both the
        !           444: .B \-r
        !           445: and 
        !           446: .B \-w
        !           447: options are specified.
        !           448: The directory must exist and be writable before the copy or and error
        !           449: results.
        !           450: .TP 1i
        !           451: .I pathname
        !           452: A file whose contents are used instead of the files named on the standard
        !           453: input.
        !           454: When a directory is named, all of its files and (recursively) 
        !           455: subdirectories
        !           456: are copied as well.
        !           457: .TP 1i
        !           458: .IR pattern 
        !           459: A
        !           460: .I pattern
        !           461: is given in the standard shell pattern matching notation.
        !           462: The default if no 
        !           463: .I pattern 
        !           464: is  specified is
        !           465: .BR * \,
        !           466: which selects all files.
        !           467: .SH EXAMPLES
        !           468: The following command
        !           469: .sp
        !           470: .RS 1i
        !           471: pax \-w \-f /dev/rmt0 \.
        !           472: .RE
        !           473: .sp
        !           474: copies the contents of the current directory to tape drive 0.
        !           475: .PP
        !           476: The commands
        !           477: .sp
        !           478: .RS 1i
        !           479: .RI mkdir " newdir"
        !           480: .br
        !           481: .RI cd " olddir"
        !           482: .br
        !           483: .RI "pax -rw . " newdir
        !           484: .RE
        !           485: .sp
        !           486: copies the contents of 
        !           487: .I olddir 
        !           488: to 
        !           489: .I newdir .
        !           490: .PP
        !           491: The command
        !           492: .sp
        !           493: .RS 1i
        !           494: pax \-r \-s ',//*usr//*,,' -f pax.out
        !           495: .RE
        !           496: .sp
        !           497: reads the archive 
        !           498: .B pax.out
        !           499: with all files rooted in "/usr" in the archive extracted
        !           500: relative to the current directory.
        !           501: .SH FILES
        !           502: .TP 1i
        !           503: /dev/tty
        !           504: used to prompt the user for information when the
        !           505: .BR \-i " or " \-y
        !           506: options are specified. 
        !           507: .SH "SEE ALSO"
        !           508: cpio(1), find(1), tar(1), cpio(5), tar(5)
        !           509: .SH DIAGNOSTICS
        !           510: .I Pax
        !           511: will terminate immediately, without processing any 
        !           512: additional files on the command line or in the archive.
        !           513: .SH "EXIT CODES"
        !           514: .I Pax 
        !           515: will exit with one of the following values:
        !           516: .IP 0 .5i
        !           517: All files in the archive were processed successfully.
        !           518: .IP ">0" .5i
        !           519: .I Pax 
        !           520: aborted due to errors encountered during operation.
        !           521: .SH BUGS
        !           522: Special permissions may be required to copy or extract special files.
        !           523: .PP
        !           524: Device, user ID, and group ID numbers larger than 65535 cause additional
        !           525: header records to be output.
        !           526: These records are ignored by some historical version of
        !           527: .I "cpio(1)"
        !           528: and
        !           529: .IR "tar(1)" .
        !           530: .PP
        !           531: The archive formats described in
        !           532: .B "Archive/Interchange File Format" 
        !           533: have certain restrictions that have
        !           534: been carried over from historical usage.
        !           535: For example, there are restrictions on the length of pathnames stored in
        !           536: the archive.
        !           537: .PP
        !           538: When getting an "ls -l" style listing on
        !           539: .I tar
        !           540: format archives, link counts are listed as zero since the 
        !           541: .I ustar
        !           542: archive format does not keep link count information.
        !           543: .SH COPYRIGHT
        !           544: Copyright (c) 1989 Mark H. Colburn.  
        !           545: .br
        !           546: All rights reserved.
        !           547: .PP
        !           548: Redistribution and use in source and binary forms are permitted
        !           549: provided that the above copyright notice is duplicated in all such 
        !           550: forms and that any documentation, advertising materials, and other 
        !           551: materials related to such distribution and use acknowledge that the 
        !           552: software was developed by Mark H. Colburn and sponsored by The 
        !           553: USENIX Association. 
        !           554: .PP
        !           555: THE SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
        !           556: IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
        !           557: WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
        !           558: .SH AUTHOR
        !           559: Mark H. Colburn
        !           560: .br
        !           561: NAPS International
        !           562: .br
        !           563: 117 Mackubin Street, Suite 1
        !           564: .br
        !           565: St. Paul, MN 55102
        !           566: .br
        !           567: [email protected]
        !           568: .sp 2
        !           569: Sponsored by
        !           570: .B "The USENIX Association"
        !           571: for public distribution.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.