diff options
Diffstat (limited to 'man-pages-posix-2013/man1p/pax.1p')
| -rw-r--r-- | man-pages-posix-2013/man1p/pax.1p | 4153 |
1 files changed, 4153 insertions, 0 deletions
diff --git a/man-pages-posix-2013/man1p/pax.1p b/man-pages-posix-2013/man1p/pax.1p new file mode 100644 index 0000000..788756b --- /dev/null +++ b/man-pages-posix-2013/man1p/pax.1p @@ -0,0 +1,4153 @@ +'\" et +.TH PAX "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pax +\(em portable archive interchange +.SH SYNOPSIS +.LP +.nf +pax \fB[\fR\(midv\fB] [\fR\(mic|\(min\fB] [\fR\(miH|\(miL\fB] [\fR\(mio \fIoptions\fB] [\fR\(mif \fIarchive\fB] [\fR\(mis \fIreplstr\fB]\fR... + \fB[\fIpattern\fR...\fB]\fR +.P +pax \(mir\fB[\fR\(mic|\(min\fB] [\fR\(midikuv\fB] [\fR\(miH|\(miL\fB] [\fR\(mif \fIarchive\fB] [\fR\(mio \fIoptions\fB]\fR... \fB[\fR\(mip \fIstring\fB]\fR... + \fB[\fR\(mis \fIreplstr\fB]\fR... \fB[\fIpattern\fR...\fB]\fR +.P +pax \(miw \fB[\fR\(midituvX\fB] [\fR\(miH|\(miL\fB] [\fR\(mib \fIblocksize\fB] [[\fR\(mia\fB] [\fR\(mif \fIarchive\fB]] [\fR\(mio \fIoptions\fB]\fR... + \fB[\fR\(mis \fIreplstr\fB]\fR... \fB[\fR\(mix \fIformat\fB] [\fIfile\fR...\fB]\fR +.P +pax \(mir \(miw \fB[\fR\(midiklntuvX\fB] [\fR\(miH|\(miL\fB] [\fR\(mio \fIoptions\fB]\fR... \fB[\fR\(mip \fIstring\fB]\fR... + \fB[\fR\(mis \fIreplstr\fB]\fR... \fB[\fIfile\fR...\fB] \fIdirectory\fR +.fi +.SH DESCRIPTION +The +.IR pax +utility shall read, write, and write lists of the members of archive +files and copy directory hierarchies. A variety of archive formats +shall be supported; see the +.BR \(mix +.IR format +option. +.P +The action to be taken depends on the presence of the +.BR \(mir +and +.BR \(miw +options. The four combinations of +.BR \(mir +and +.BR \(miw +are referred to as the four modes of operation: +.BR list , +.BR read , +.BR write , +and +.BR copy +modes, corresponding respectively to the four forms shown in the +SYNOPSIS section. +.IP "\fBlist\fP" 10 +In +.BR list +mode (when neither +.BR \(mir +nor +.BR \(miw +are specified), +.IR pax +shall write the names of the members of the archive file read from the +standard input, with pathnames matching the specified patterns, to +standard output. If a named file is of type directory, the file +hierarchy rooted at that file shall be listed as well. +.IP "\fBread\fP" 10 +In +.BR read +mode (when +.BR \(mir +is specified, but +.BR \(miw +is not), +.IR pax +shall extract the members of the archive file read from the standard +input, with pathnames matching the specified patterns. If an extracted +file is of type directory, the file hierarchy rooted at that file shall +be extracted as well. The extracted files shall be created performing +pathname resolution with the directory in which +.IR pax +was invoked as the current working directory. +.RS 10 +.P +If an attempt is made to extract a directory when the directory +already exists, this shall not be considered an error. If +an attempt is made to extract a FIFO when the FIFO already exists, +this shall not be considered an error. +.P +The ownership, access, and modification times, and file mode of the +restored files are discussed under the +.BR \(mip +option. +.RE +.IP "\fBwrite\fP" 10 +In +.BR write +mode (when +.BR \(miw +is specified, but +.BR \(mir +is not), +.IR pax +shall write the contents of the +.IR file +operands to the standard output in an archive format. If no +.IR file +operands are specified, a list of files to copy, one per line, shall be +read from the standard input and each entry in this list shall be +processed as if it had been a +.IR file +operand on the command line. A file of type directory shall include +all of the files in the file hierarchy rooted at the file. +.IP "\fBcopy\fP" 10 +In +.BR copy +mode (when both +.BR \(mir +and +.BR \(miw +are specified), +.IR pax +shall copy the +.IR file +operands to the destination directory. +.RS 10 +.P +If no +.IR file +operands are specified, a list of files to copy, one per line, shall be +read from the standard input. A file of type directory shall include +all of the files in the file hierarchy rooted at the file. +.P +The effect of the +.BR copy +shall be as if the copied files were written to a +.IR pax +format archive file and then subsequently extracted, except that there +may 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. If the destination directory is a +file of a type not defined by the System Interfaces volume of POSIX.1\(hy2008, the results are +implementation-defined; otherwise, it shall be an error for the file +named by the +.IR directory +operand not to exist, not be writable by the user, or not be a file of +type directory. +.RE +.P +In +.BR read +or +.BR copy +modes, if intermediate directories are necessary to extract an archive +member, +.IR pax +shall perform actions equivalent to the +\fImkdir\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008, called with the following arguments: +.IP " *" 4 +The intermediate directory used as the +.IR path +argument +.IP " *" 4 +The value of the bitwise-inclusive OR of S_IRWXU, S_IRWXG, and S_IRWXO +as the +.IR mode +argument +.P +If any specified +.IR pattern +or +.IR file +operands are not matched by at least one file or archive member, +.IR pax +shall write a diagnostic message to standard error for each one that +did not match and exit with a non-zero exit status. +.P +The archive formats described in the EXTENDED DESCRIPTION section shall +be automatically detected on input. The default output archive format +shall be implementation-defined. +.P +A single archive can span multiple files. The +.IR pax +utility shall determine, in an implementation-defined manner, what +file to read or write as the next file. +.P +If the selected archive format supports the specification of linked files, +it shall be an error if these files cannot be linked when the archive +is extracted. 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 +.IR pax +session, either the data shall be restored from the original file, or a +diagnostic message shall be displayed with the name of a file that can +be used to extract the data. In traversing directories, +.IR pax +shall detect infinite loops; that is, entering a previously visited +directory that is an ancestor of the last file visited. When it detects +an infinite loop, +.IR pax +shall write a diagnostic message to standard error and shall +terminate. +.SH OPTIONS +The +.IR pax +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that the order of presentation of the +.BR \(mio , +.BR \(mip , +and +.BR \(mis +options is significant. +.P +The following options shall be supported: +.IP "\fB\(mir\fP" 10 +Read an archive file from standard input. +.IP "\fB\(miw\fP" 10 +Write files to the standard output in the specified archive format. +.IP "\fB\(mia\fP" 10 +Append files to the end of the archive. It is implementation-defined +which devices on the system support appending. Additional file formats +unspecified by this volume of POSIX.1\(hy2008 may impose restrictions on appending. +.IP "\fB\(mib\ \fIblocksize\fR" 10 +Block the output at a positive decimal integer number of bytes per +write to the archive file. Devices and archive formats may impose +restrictions on blocking. Blocking shall be automatically determined on +input. Conforming applications shall not specify a +.IR blocksize +value larger than 32\|256. Default blocking when creating archives +depends on the archive format. (See the +.BR \(mix +option below.) +.IP "\fB\(mic\fP" 10 +Match all file or archive members except those specified by the +.IR pattern +or +.IR file +operands. +.IP "\fB\(mid\fP" 10 +Cause 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. +.IP "\fB\(mif\ \fIarchive\fR" 10 +Specify the pathname of the input or output archive, overriding the +default standard input (in +.BR list +or +.BR read +modes) or standard output (\c +.BR write +mode). +.IP "\fB\(miH\fP" 10 +If a symbolic link referencing a file of type directory is specified on +the command line, +.IR pax +shall archive 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 +.IR pax +can normally archive is specified on the command line, then +.IR pax +shall archive the file referenced by the link, using the name of the +link. The default behavior, when neither +.BR \(miH +or +.BR \(miL +are specified, shall be to archive the symbolic link itself. +.IP "\fB\(mii\fP" 10 +Interactively rename files or archive members. For each archive member +matching a +.IR pattern +operand or file matching a +.IR file +operand, a prompt shall be written to the file +.BR /dev/tty . +The prompt shall contain the name of the file or archive member, but +the format is otherwise unspecified. A line shall then be read from +.BR /dev/tty . +If this line is blank, the file or archive member shall be skipped. If +this line consists of a single period, the file or archive member shall +be processed with no modification to its name. Otherwise, its name +shall be replaced with the contents of the line. The +.IR pax +utility shall immediately exit with a non-zero exit status if +end-of-file is encountered when reading a response or if +.BR /dev/tty +cannot be opened for reading and writing. +.RS 10 +.P +The results of extracting a hard link to a file that has been renamed +during extraction are unspecified. +.RE +.IP "\fB\(mik\fP" 10 +Prevent the overwriting of existing files. +.IP "\fB\(mil\fP" 10 +(The letter ell.) In +.BR copy +mode, hard links shall be made between the source and destination file +hierarchies whenever possible. If specified in conjunction with +.BR \(miH +or +.BR \(miL , +when a symbolic link is encountered, the hard link created in the +destination file hierarchy shall be to the file referenced by the +symbolic link. If specified when neither +.BR \(miH +nor +.BR \(miL +is specified, when a symbolic link is encountered, the implementation +shall create a hard link to the symbolic link in the source file +hierarchy or copy the symbolic link to the destination. +.IP "\fB\(miL\fP" 10 +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, +.IR pax +shall archive 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 +.IR pax +can normally archive is specified on the command line or encountered +during the traversal of a file hierarchy, +.IR pax +shall archive the file referenced by the link, using the name of the +link. The default behavior, when neither +.BR \(miH +or +.BR \(miL +are specified, shall be to archive the symbolic link itself. +.IP "\fB\(min\fP" 10 +Select the first archive member that matches each +.IR pattern +operand. No more than one archive member shall be matched for each +pattern (although members of type directory shall still match the file +hierarchy rooted at that file). +.IP "\fB\(mio\ \fIoptions\fR" 10 +Provide information to the implementation to modify the algorithm for +extracting or writing files. The value of +.IR options +shall consist of one or more +<comma>-separated +keywords of the form: +.RS 10 +.sp +.RS 4 +.nf +\fB +\fIkeyword\fB[[\fR:\fB]\fR=\fIvalue\fB][\fR,\fIkeyword\fB[[\fR:\fB]\fR=\fIvalue\fB]\fR, ...\fB]\fR +.fi \fR +.P +.RE +.P +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. +.P +Keywords in the +.IR options +argument shall be a string that would be a valid portable filename as +described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.278" ", " "Portable Filename Character Set". +.TP 10 +.BR Note: +Keywords are not expected to be filenames, merely to follow the same +character composition rules as portable filenames. +.P +.P +Keywords can be preceded with white space. The +.IR value +field shall consist of zero or more characters; within +.IR value , +the application shall precede any literal +<comma> +with a +<backslash>, +which shall be ignored, but preserves the +<comma> +as part of +.IR value . +A +<comma> +as the final character, or a +<comma> +followed solely by white space as the final characters, in +.IR options +shall be ignored. Multiple +.BR \(mio +options can be specified; if keywords given to these multiple +.BR \(mio +options conflict, the keywords and values appearing later in command +line sequence shall take precedence and the earlier shall be silently +ignored. The following keyword values of +.IR options +shall be supported for the file formats as indicated: +.IP "\fBdelete\fR=\fIpattern\fR" 6 +.br +(Applicable only to the +.BR \(mix +.BR pax +format.) When used in +.BR write +or +.BR copy +mode, +.IR pax +shall omit from extended header records that it produces any keywords +matching the string pattern. When used in +.BR read +or +.BR list +mode, +.IR pax +shall ignore any keywords matching the string pattern in the extended +header records. In both cases, matching shall be performed using the +pattern matching notation described in +.IR "Section 2.13.1" ", " "Patterns Matching a Single Character" +and +.IR "Section 2.13.2" ", " "Patterns Matching Multiple Characters". +For example: +.RS 6 +.sp +.RS 4 +.nf +\fB +\(mio \fBdelete\fR=\fIsecurity\fR.* +.fi \fR +.P +.RE +.P +would suppress security-related information. See +.IR "pax Extended Header" +for extended header record keyword usage. +.P +When multiple +.BR \(mio \c +.BR delete=pattern +options are specified, the patterns shall be additive; all keywords +matching the specified string patterns shall be omitted from extended +header records that +.IR pax +produces. +.RE +.IP "\fBexthdr.name\fR=\fIstring\fR" 6 +.br +(Applicable only to the +.BR \(mix +.BR pax +format.) This keyword allows user control over the name that is written +into the +.BR ustar +header blocks for the extended header produced under the circumstances +described in +.IR "pax Header Block". +The name shall be the contents of +.IR string , +after the following character substitutions have been made: +.TS +center box tab(!); +cB | cB +cB | cB +lf5 | lw(3.8i). +\fIstring\fP +Includes:!Replaced by: +_ +%d!T{ +The directory name of the file, equivalent to the result of the +.IR dirname +utility on the translated pathname. +T} +%f!T{ +The filename of the file, equivalent to the result of the +.IR basename +utility on the translated pathname. +T} +%p!T{ +The process ID of the +.IR pax +process. +T} +%%!T{ +A +.BR '%' +character. +T} +.TE +.RS 6 +.P +Any other +.BR '%' +characters in +.IR string +produce undefined results. +.P +If no +.BR \(mio +.BR exthdr.name=string +is specified, +.IR pax +shall use the following default value: +.sp +.RS 4 +.nf +\fB +%d/PaxHeaders.%p/%f +.fi \fR +.P +.RE +.RE +.IP "\fBglobexthdr.name\fR=\fIstring\fR" 6 +.br +(Applicable only to the +.BR \(mix +.BR pax +format.) When used in +.BR write +or +.BR copy +mode with the appropriate options, +.IR pax +shall create global extended header records with +.BR ustar +header blocks that will be treated as regular files by previous +versions of +.IR pax . +This keyword allows user control over the name that is written into the +.BR ustar +header blocks for global extended header records. The name shall be the +contents of string, after the following character substitutions have +been made: +.TS +center box tab(!); +cB | cB +cB | cB +lf5 | lw(3.8i). +\fIstring\fP +Includes:!Replaced by: +_ +%n!T{ +An integer that represents the sequence number of the global extended +header record in the archive, starting at 1. +T} +%p!T{ +The process ID of the +.IR pax +process. +T} +%%!T{ +A +.BR '%' +character. +T} +.TE +.RS 6 +.P +Any other +.BR '%' +characters in +.IR string +produce undefined results. +.P +If no +.BR \(mio +.BR globexthdr.name=string +is specified, +.IR pax +shall use the following default value: +.sp +.RS 4 +.nf +\fB +$TMPDIR/GlobalHead.%p.%n +.fi \fR +.P +.RE +.P +where $\c +.IR TMPDIR +represents the value of the +.IR TMPDIR +environment variable. If +.IR TMPDIR +is not set, +.IR pax +shall use +.BR /tmp . +.RE +.IP "\fBinvalid\fR=\fIaction\fR" 6 +.br +(Applicable only to the +.BR \(mix +.BR pax +format.) This keyword allows user control over the action +.IR pax +takes upon encountering values in an extended header record that, in +.BR read +or +.BR copy +mode, are invalid in the destination hierarchy or, in +.BR list +mode, cannot be written in the codeset and current locale of the +implementation. The following are invalid values that shall be +recognized by +.IR pax : +.RS 6 +.IP -- 4 +In +.BR read +or +.BR copy +mode, a filename or link name that contains character encodings +invalid in the destination hierarchy. (For example, the name may +contain embedded NULs.) +.IP -- 4 +In +.BR read +or +.BR copy +mode, a filename or link name that is longer than the maximum allowed +in the destination hierarchy (for either a pathname component or the +entire pathname). +.IP -- 4 +In +.BR list +mode, any character string value (filename, link name, user name, and +so on) that cannot be written in the codeset and current locale of the +implementation. +.P +The following mutually-exclusive values of the +.IR action +argument are supported: +.IP "\fBbinary\fR" 10 +In +.BR write +mode, +.IR pax +shall generate a +.BR hdrcharset = BINARY +extended header record for each file with a filename, link name, group +name, owner name, or any other field in an extended header record that +cannot be translated to the UTF\(hy8 codeset, allowing the archive to +contain the files with unencoded extended header record values. In +.BR read +or +.BR copy +mode, +.IR pax +shall use the values specified in the header without translation, +regardless of whether this may overwrite an existing file with a valid +name. In +.BR list +mode, +.IR pax +shall behave identically to the +.BR bypass +action. +.IP "\fBbypass\fR" 10 +In +.BR read +or +.BR copy +mode, +.IR pax +shall bypass the file, causing no change to the destination hierarchy. +In +.BR list +mode, +.IR pax +shall write all requested valid values for the file, but its method for +writing invalid values is unspecified. +.IP "\fBrename\fR" 10 +In +.BR read +or +.BR copy +mode, +.IR pax +shall act as if the +.BR \(mii +option were in effect for each file with invalid filename or link name +values, allowing the user to provide a replacement name interactively. +In +.BR list +mode, +.IR pax +shall behave identically to the +.BR bypass +action. +.IP "\fBUTF\(hy8\fR" 10 +When used in +.BR read , +.BR copy , +or +.BR list +mode and a filename, link name, owner name, or any other field in an +extended header record cannot be translated from the +.BR pax +UTF\(hy8 codeset format to the codeset and current locale of the +implementation, +.IR pax +shall use the actual UTF\(hy8 encoding for the name. If a +.BR hdrcharset +extended header record is in effect for this file, the character set +specified by that record shall be used instead of UTF\(hy8. If a +.BR hdrcharset = BINARY +extended header record is in effect for this file, no translation shall +be performed. +.IP "\fBwrite\fR" 10 +In +.BR read +or +.BR copy +mode, +.IR pax +shall write the file, translating the name, regardless of whether this +may overwrite an existing file with a valid name. In +.BR list +mode, +.IR pax +shall behave identically to the +.BR bypass +action. +.P +If no +.BR \(mio +.BR invalid=option +is specified, +.IR pax +shall act as if +.BR \(mio \c +.BR invalid=bypass +were specified. Any overwriting of existing files that may be allowed +by the +.BR \(mio \c +.BR invalid= +actions shall be subject to permission (\c +.BR \(mip ) +and modification time (\c +.BR \(miu ) +restrictions, and shall be suppressed if the +.BR \(mik +option is also specified. +.RE +.IP "\fBlinkdata\fP" 6 +.br +(Applicable only to the +.BR \(mix +.BR pax +format.) In +.BR write +mode, +.IR pax +shall write 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. +.IP "\fBlistopt\fR=\fIformat\fP" 6 +.br +This keyword specifies the output format of the table of contents +produced when the +.BR \(miv +option is specified in +.BR list +mode. See +.IR "List Mode Format Specifications". +To avoid ambiguity, the +.BR listopt=format +shall be the only or final +.BR keyword=value +pair in a +.BR \(mio +option-argument; all characters in the remainder of the option-argument +shall be considered part of the format string. When multiple +.BR \(mio \c +.BR listopt=format +options are specified, the format strings shall be considered a single, +concatenated string, evaluated in command line order. +.IP "\fBtimes\fR" 6 +.br +(Applicable only to the +.BR \(mix +.IR pax +format.) When used in +.BR write +or +.BR copy +mode, +.IR pax +shall include +.BR atime +and +.BR mtime +extended header records for each file. See +.IR "pax Extended Header File Times". +.P +In addition to these keywords, if the +.BR \(mix +.IR pax +format is specified, any of the keywords and values defined in +.IR "pax Extended Header", +including implementation extensions, can be used in +.BR \(mio +option-arguments, in either of two modes: +.IP "\fBkeyword\fR=\fIvalue\fR" 6 +.br +When used in +.BR write +or +.BR copy +mode, these keyword/value pairs shall be included at the beginning of +the archive as +.BR typeflag +.BR g +global extended header records. When used in +.BR read +or +.BR list +mode, these keyword/value pairs shall act as if they had been at the +beginning of the archive as +.BR typeflag +.BR g +global extended header records. +.IP "\fBkeyword\fR:=\fIvalue\fR" 6 +.br +When used in +.BR write +or +.BR copy +mode, these keyword/value pairs shall be included as records at the +beginning of a +.BR typeflag +.BR x +extended header for each file. (This shall be equivalent to the +<equals-sign> +form except that it creates no +.BR typeflag +.BR g +global extended header records.) When used in +.BR read +or +.BR list +mode, these keyword/value pairs shall act as if they were included as +records at the end of each extended header; thus, they shall override +any global or file-specific extended header record keywords of the same +names. For example, in the command: +.RS 6 +.sp +.RS 4 +.nf +\fB +pax \(mir \(mio " +gname:=mygroup, +" <archive +.fi \fR +.P +.RE +.P +the group name will be forced to a new value for all files read from +the archive. +.RE +.P +The precedence of +.BR \(mio +keywords over various fields in the archive is described in +.IR "pax Extended Header Keyword Precedence". +.RE +.IP "\fB\(mip\ \fIstring\fR" 10 +Specify one or more file characteristic options (privileges). The +.IR string +option-argument shall be a string specifying file characteristics to be +retained or discarded on extraction. The string shall consist of the +specification characters +.BR a , +.BR e , +.BR m , +.BR o , +and +.BR p . +Other implementation-defined characters can be included. Multiple +characteristics can be concatenated within the same string and multiple +.BR \(mip +options can be specified. The meaning of the specification characters +are as follows: +.RS 10 +.IP "\fRa\fP" 6 +Do not preserve file access times. +.IP "\fRe\fP" 6 +Preserve the user ID, group ID, file mode bits (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.169" ", " "File Mode Bits"), +access time, modification time, and any other implementation-defined +file characteristics. +.IP "\fRm\fP" 6 +Do not preserve file modification times. +.IP "\fRo\fP" 6 +Preserve the user ID and group ID. +.IP "\fRp\fP" 6 +Preserve the file mode bits. Other implementation-defined file mode +attributes may be preserved. +.P +In the preceding list, ``preserve'' indicates that an attribute stored +in the archive shall be given to the extracted file, subject to the +permissions of the invoking process. The access and modification times +of the file shall be preserved unless otherwise specified with the +.BR \(mip +option or not stored in the archive. All attributes that are not +preserved shall be determined as part of the normal file creation +action (see +.IR "Section 1.1.1.4" ", " "File Read" ", " "Write" ", " "and Creation"). +.P +If neither the +.BR e +nor the +.BR o +specification character is specified, or the user ID and group ID are +not preserved for any reason, +.IR pax +shall not set the S_ISUID and S_ISGID bits of the file mode. +.P +If the preservation of any of these items fails for any reason, +.IR pax +shall write a diagnostic message to standard error. Failure to preserve +these items shall affect the final exit status, but shall not cause the +extracted file to be deleted. +.P +If file characteristic letters in any of the +.IR string +option-arguments are duplicated or conflict with each other, the ones +given last shall take precedence. For example, if +.BR \(mip +.BR eme +is specified, file modification times are preserved. +.RE +.IP "\fB\(mis\ \fIreplstr\fR" 10 +Modify file or archive member names named by +.IR pattern +or +.IR file +operands according to the substitution expression +.IR replstr , +using the syntax of the +.IR ed +utility. The concepts of ``address'' and ``line'' are meaningless in +the context of the +.IR pax +utility, and shall not be supplied. The format shall be: +.RS 10 +.sp +.RS 4 +.nf +\fB +\(mis /\fIold\fR/\fInew\fR/\fB[\fRgp\fB]\fR +.fi \fR +.P +.RE +.P +where as in +.IR ed , +.IR old +is a basic regular expression and +.IR new +can contain an +<ampersand>, +.BR '\en' +(where +.IR n +is a digit) back-references, or subexpression matching. The +.IR old +string shall also be permitted to contain +<newline> +characters. +.P +Any non-null character can be used as a delimiter (\c +.BR '/' +shown here). Multiple +.BR \(mis +expressions can be specified; the expressions shall be applied in the +order specified, terminating with the first successful substitution. +The optional trailing +.BR 'g' +is as defined in the +.IR ed +utility. The optional trailing +.BR 'p' +shall cause successful substitutions to be written to standard error. +File or archive member names that substitute to the empty string shall +be ignored when reading and writing archives. +.RE +.IP "\fB\(mit\fP" 10 +When reading files from the file system, and if the user has the +permissions required by +\fIutime\fR() +to do so, set the access time of each file read to the access time that +it had before being read by +.IR pax . +.IP "\fB\(miu\fP" 10 +Ignore files that are older (having a less recent file modification +time) than a pre-existing file or archive member with the same name. +In +.BR read +mode, an archive member with the same name as a file in the file system +shall be extracted if the archive member is newer than the file. In +.BR write +mode, an archive file member with the same name as a file in the file +system shall be superseded if the file is newer than the archive +member. If +.BR \(mia +is also specified, this is accomplished by appending to the archive; +otherwise, it is unspecified whether this is accomplished by actual +replacement in the archive or by appending to the archive. In +.BR copy +mode, the file in the destination hierarchy shall be 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. +.IP "\fB\(miv\fP" 10 +In +.BR list +mode, produce a verbose table of contents (see the STDOUT section). +Otherwise, write archive member pathnames to standard error (see the +STDERR section). +.IP "\fB\(mix\ \fIformat\fR" 10 +Specify the output archive format. The +.IR pax +utility shall support the following formats: +.RS 10 +.IP "\fBcpio\fR" 10 +The +.BR cpio +interchange format; see the EXTENDED DESCRIPTION section. The default +.IR blocksize +for this format for character special archive files shall be 5\|120. +Implementations shall support all +.IR blocksize +values less than or equal to 32\|256 that are multiples of 512. +.IP "\fBpax\fR" 10 +The +.BR pax +interchange format; see the EXTENDED DESCRIPTION section. The default +.IR blocksize +for this format for character special archive files shall be 5\|120. +Implementations shall support all +.IR blocksize +values less than or equal to 32\|256 that are multiples of 512. +.IP "\fBustar\fR" 10 +The +.BR tar +interchange format; see the EXTENDED DESCRIPTION section. The default +.IR blocksize +for this format for character special archive files shall be 10\|240. +Implementations shall support all +.IR blocksize +values less than or equal to 32\|256 that are multiples of 512. +.P +Implementation-defined formats shall specify a default block size as +well as any other block sizes supported for character special archive +files. +.P +Any attempt to append to an archive file in a format different from the +existing archive format shall cause +.IR pax +to exit immediately with a non-zero exit status. +.RE +.IP "\fB\(miX\fP" 10 +When traversing the file hierarchy specified by a pathname, +.IR pax +shall not descend into directories that have a different device ID (\c +.IR st_dev ; +see the System Interfaces volume of POSIX.1\(hy2008, +\fIstat\fR()). +.P +Specifying more than one of the mutually-exclusive options +.BR \(miH +and +.BR \(miL +shall not be considered an error and the last option specified shall +determine the behavior of the utility. +.P +The options that operate on the names of files or archive members (\c +.BR \(mic , +.BR \(mii , +.BR \(min , +.BR \(mis , +.BR \(miu , +and +.BR \(miv ) +shall interact as follows. In +.BR read +mode, the archive members shall be selected based on the user-specified +.IR pattern +operands as modified by the +.BR \(mic , +.BR \(min , +and +.BR \(miu +options. Then, any +.BR \(mis +and +.BR \(mii +options shall modify, in that order, the names of the selected files. +The +.BR \(miv +option shall write names resulting from these modifications. +.P +In +.BR write +mode, the files shall be selected based on the user-specified +pathnames as modified by the +.BR \(min +and +.BR \(miu +options. Then, any +.BR \(mis +and +.BR \(mii +options shall modify, in that order, the names of these selected files. +The +.BR \(miv +option shall write names resulting from these modifications. +.P +If both the +.BR \(miu +and +.BR \(min +options are specified, +.IR pax +shall not consider a file selected unless it is newer than the file to +which it is compared. +.SS "List Mode Format Specifications" +.P +In +.BR list +mode with the +.BR \(mio +.BR listopt=format +option, the +.IR format +argument shall be applied for each selected file. The +.IR pax +utility shall append a +<newline> +to the +.BR listopt +output for each selected file. The +.IR format +argument shall be used as the +.IR format +string described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation", +with the exceptions 1. through 6. defined in the EXTENDED DESCRIPTION +section of +.IR printf , +plus the following exceptions: +.IP 7. 6 +The sequence (\c +.IR keyword ) +can occur before a format conversion specifier. The conversion +argument is defined by the value of +.IR keyword . +The implementation shall support the following keywords: +.RS 6 +.IP -- 4 +Any of the Field Name entries in +.IR "Table 4-14, ustar Header Block" +and +.IR "Table 4-16, Octet-Oriented cpio Archive Entry". +The implementation may support the +.IR cpio +keywords without the leading +.BR c_ +in addition to the form required by +.IR "Table 4-16, Octet-Oriented cpio Archive Entry". +.IP -- 4 +Any keyword defined for the extended header in +.IR "pax Extended Header". +.IP -- 4 +Any keyword provided as an implementation-defined extension within +the extended header defined in +.IR "pax Extended Header". +.P +For example, the sequence +.BR \(dq%(charset)s\(dq +is the string value of the name of the character set in the extended +header. +.P +The result of the keyword conversion argument shall be the value from +the applicable header field or extended header, without any trailing +NULs. +.P +All keyword values used as conversion arguments shall be translated +from the UTF\(hy8 encoding (or alternative encoding specified by any +.BR hdrcharset +extended header record) to the character set appropriate for the local +file system, user database, and so on, as applicable. +.RE +.IP 8. 6 +An additional conversion specifier character, +.BR T , +shall be used to specify time formats. The +.BR T +conversion specifier character can be preceded by the sequence (\c +.IR keyword= \c +.IR subformat ), +where +.IR subformat +is a date format as defined by +.IR date +operands. The default +.IR keyword +shall be +.BR mtime +and the default subformat shall be: +.RS 6 +.sp +.RS 4 +.nf +\fB +%b %e %H:%M %Y +.fi \fR +.P +.RE +.RE +.IP 9. 6 +An additional conversion specifier character, +.BR M , +shall be used to specify the file mode string as defined in +.IR ls +Standard Output. If (\c +.IR keyword ) +is omitted, the +.BR mode +keyword shall be used. For example, +.BR %.1M +writes the single character corresponding to the <\fIentry\ type\fP> +field of the +.IR ls +.BR \(mil +command. +.IP 10. 6 +An additional conversion specifier character, +.BR D , +shall be used to specify the device for block or special files, if +applicable, in an implementation-defined format. If not applicable, +and (\c +.IR keyword ) +is specified, then this conversion shall be equivalent to +\fR%(\fIkeyword\fR)u\fR. If not applicable, and (\c +.IR keyword ) +is omitted, then this conversion shall be equivalent to +<space>. +.IP 11. 6 +An additional conversion specifier character, +.BR F , +shall be used to specify a pathname. The +.BR F +conversion character can be preceded by a sequence of +<comma>-separated +keywords: +.RS 6 +.sp +.RS 4 +.nf +\fB +(\fIkeyword\fB[\fR,\fIkeyword\fB]\fR ... ) +.fi \fR +.P +.RE +.P +The values for all the keywords that are non-null shall be concatenated +together, each separated by a +.BR '/' . +The default shall be (\c +.BR path ) +if the keyword +.BR path +is defined; otherwise, the default shall be (\c +.BR prefix ,\c +.BR name ). +.RE +.IP 12. 6 +An additional conversion specifier character, +.BR L , +shall be used to specify a symbolic link expansion. If the current +file is a symbolic link, then +.BR %L +shall expand to: +.RS 6 +.sp +.RS 4 +.nf +\fB +"%s \(mi> %s", <\fIvalue of keyword\fR>, <\fIcontents of link\fR> +.fi \fR +.P +.RE +.P +Otherwise, the +.BR %L +conversion specification shall be the equivalent of +.BR %F . +.RE +.SH OPERANDS +The following operands shall be supported: +.IP "\fIdirectory\fR" 10 +The destination directory pathname for +.BR copy +mode. +.IP "\fIfile\fR" 10 +A pathname of a file to be copied or archived. +.IP "\fIpattern\fR" 10 +A pattern matching one or more pathnames of archive members. A pattern +must be given in the name-generating notation of the pattern matching +notation in +.IR "Section 2.13" ", " "Pattern Matching Notation", +including the filename expansion rules in +.IR "Section 2.13.3" ", " "Patterns Used for Filename Expansion". +The default, if no +.IR pattern +is specified, is to select all members in the archive. +.SH STDIN +In +.BR write +mode, the standard input shall be used only if no +.IR file +operands are specified. It shall be a file containing a list of +pathnames, each terminated by a +<newline> +character. +.P +In +.BR list +and +.BR read +modes, if +.BR \(mif +is not specified, the standard input shall be an archive file. +.P +Otherwise, the standard input shall not be used. +.SH "INPUT FILES" +The input file named by the +.IR archive +option-argument, or standard input when the archive is read from there, +shall be a file formatted according to one of the specifications in the +EXTENDED DESCRIPTION section or some other implementation-defined +format. +.P +The file +.BR /dev/tty +shall be used to write prompts and read responses. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR pax : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements used in the pattern matching +expressions for the +.IR pattern +operand, the basic regular expression for the +.BR \(mis +option, and the extended regular expression defined for the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files), the behavior of +character classes used in the extended regular expression defined for +the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category, and pattern matching. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale used to process affirmative responses, and the +locale used to affect the format and contents of diagnostic messages +and prompts written to standard error. +.IP "\fILC_TIME\fP" 10 +Determine the format and contents of date and time strings when the +.BR \(miv +option is specified. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITMPDIR\fP" 10 +Determine the pathname that provides part of the default global +extended header record file, as described for the +.BR \(mio +.BR globexthdr= +keyword in the OPTIONS section. +.IP "\fITZ\fP" 10 +Determine the timezone used to calculate date and time strings when the +.BR \(miv +option is specified. If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +In +.BR write +mode, if +.BR \(mif +is not specified, the standard output shall be the archive formatted +according to one of the specifications in the EXTENDED DESCRIPTION +section, or some other implementation-defined format (see +.BR \(mix +.IR format ). +.P +In +.BR list +mode, when the +.BR \(mio \c +.BR listopt =\c +.IR format +has been specified, the selected archive members shall be written to +standard output using the format described under +.IR "List Mode Format Specifications". +In +.BR list +mode without the +.BR \(mio \c +.BR listopt =\c +.IR format +option, the table of contents of the selected archive members shall +be written to standard output using the following format: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIpathname\fR> +.fi \fR +.P +.RE +.P +If the +.BR \(miv +option is specified in +.BR list +mode, the table of contents of the selected archive members shall be +written to standard output using the following formats. +.P +For pathnames representing hard links to previous members of the +archive: +.sp +.RS 4 +.nf +\fB +"%s == %s\en", <\fIls\fR \(mil \fIlisting\fR>, <\fIlinkname\fR> +.fi \fR +.P +.RE +.P +For all other pathnames: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIls\fR \(mil \fIlisting\fR> +.fi \fR +.P +.RE +.P +where <\fIls\ \fR\(mil\ \fIlisting\fR> shall be the format specified by +the +.IR ls +utility with the +.BR \(mil +option. When writing pathnames 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>-separated +fields shall be written. +.P +In +.BR list +mode, standard output shall not be buffered more than a pathname +(plus any associated information and a +<newline> +terminator) at a time. +.SH STDERR +If +.BR \(miv +is specified in +.BR read , +.BR write , +or +.BR copy +modes, +.IR pax +shall write the pathnames it processes to the standard error output +using the following format: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIpathname\fR> +.fi \fR +.P +.RE +.P +These pathnames shall be written as soon as processing is begun on the +file or archive member, and shall be flushed to standard error. The +trailing +<newline>, +which shall not be buffered, is written when the file has been read or +written. +.P +If the +.BR \(mis +option is specified, and the replacement string has a trailing +.BR 'p' , +substitutions shall be written to standard error in the following +format: +.sp +.RS 4 +.nf +\fB +"%s >> %s\en", <\fIoriginal pathname\fR>, <\fInew pathname\fR> +.fi \fR +.P +.RE +.P +In all operating modes of +.IR 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 may be written to +standard error. +.P +In all formats, for both standard output and standard error, it is +unspecified how non-printable characters in pathnames or link names +are written. +.P +When using the +.BR \(mix \c +.BR pax +archive format, if a filename, link name, group name, owner name, or +any other field in an extended header record cannot be translated +between the codeset in use for that extended header record and the +character set of the current locale, +.IR pax +shall write a diagnostic message to standard error, shall process the +file as described for the +.BR \(mio +.BR invalid= +option, and then shall continue processing with the next file. +.SH "OUTPUT FILES" +In +.BR read +mode, the extracted output files shall be of the archived file type. +In +.BR copy +mode, the copied output files shall be the type of the file being +copied. In either mode, existing files in the destination hierarchy +shall be overwritten only when all permission (\c +.BR \(mip ), +modification time (\c +.BR \(miu ), +and invalid-value (\c +.BR \(mio \c +.BR invalid= ) +tests allow it. +.P +In +.BR write +mode, the output file named by the +.BR \(mif +option-argument shall be a file formatted according to one of the +specifications in the EXTENDED DESCRIPTION section, or some other +implementation-defined format. +.SH "EXTENDED DESCRIPTION" +.SS "pax Interchange Format" +.P +A +.IR pax +archive tape or file produced in the +.BR \(mix \c +.BR pax +format shall contain a series of blocks. The physical layout of the +archive shall be identical to the +.BR ustar +format described in +.IR "ustar Interchange Format". +Each file archived shall be represented by the following sequence: +.IP " *" 4 +An optional header block with extended header records. This header +block is of the form described in +.IR "pax Header Block", +with a +.IR typeflag +value of +.BR x +or +.BR g . +The extended header records, described in +.IR "pax Extended Header", +shall be included as the data for this header block. +.IP " *" 4 +A header block that describes the file. Any fields in the preceding +optional extended header shall override the associated fields in +this header block for this file. +.IP " *" 4 +Zero or more blocks that contain the contents of the file. +.P +At the end of the archive file there shall be two 512-byte blocks +filled with binary zeros, interpreted as an end-of-archive indicator. +.P +A schematic of an example archive with global extended header records +and two actual files is shown in +.IR "Figure 4-1, pax Format Archive Example". +In the example, the second file in the archive has no extended header +preceding it, presumably because it has no need for extended +attributes. +.sp +.ce 1 +\fBFigure 4-1: pax Format Archive Example\fR +.SS "pax Header Block" +.P +The +.BR pax +header block shall be identical to the +.BR ustar +header block described in +.IR "ustar Interchange Format", +except that two additional +.IR typeflag +values are defined: +.IP "\fRx\fP" 6 +Represents extended header records for the following file in the +archive (which shall have its own +.BR ustar +header block). The format of these extended header records shall be as +described in +.IR "pax Extended Header". +.IP "\fRg\fR" 6 +Represents global extended header records for the following files in +the archive. The format of these extended header records shall be as +described in +.IR "pax Extended Header". +Each value shall affect all subsequent files that do not override that +value in their own extended header record and until another global +extended header record is reached that provides another value for the +same field. The +.IR typeflag +.BR g +global headers should not be used with interchange media that could +suffer partial data loss in transporting the archive. +.P +For both of these types, the +.IR size +field shall be the size of the extended header records in octets. The +other fields in the header block are not meaningful to this version of +the +.IR pax +utility. However, if this archive is read by a +.IR pax +utility conforming to the ISO\ POSIX\(hy2:\|1993 standard, the header block fields are used to +create a regular file that contains the extended header records as +data. Therefore, header block field values should be selected to +provide reasonable file access to this regular file. +.P +A further difference from the +.BR ustar +header block is that data blocks for files of +.IR typeflag +1 (the digit one) (hard link) may be included, which means that the +size field may be greater than zero. Archives created by +.IR pax +.BR \(mio +.BR linkdata +shall include these data blocks with the hard links. +.SS "pax Extended Header" +.P +A +.BR pax +extended header contains values that are inappropriate for the +.BR ustar +header block because of limitations in that format: fields requiring a +character encoding other than that described in the ISO/IEC\ 646:\|1991 standard, fields +representing file attributes not described in the +.BR ustar +header, and fields whose format or length do not fit the requirements +of the +.BR ustar +header. The values in an extended header add attributes to the +following file (or files; see the description of the +.IR typeflag +.BR g +header block) or override values in the following header block(s), as +indicated in the following list of keywords. +.P +An extended header shall consist of one or more records, each +constructed as follows: +.sp +.RS 4 +.nf +\fB +"%d %s=%s\en", <\fIlength\fR>, <\fIkeyword\fR>, <\fIvalue\fR> +.fi \fR +.P +.RE +.P +The extended header records shall be encoded according to the ISO/IEC\ 10646\(hy1:\|2000 standard +UTF\(hy8 encoding. The <\fIlength\fP> field, +<blank>, +<equals-sign>, +and +<newline> +shown shall be limited to the portable character set, as encoded in +UTF\(hy8. The <\fIkeyword\fP> fields can be any UTF\(hy8 characters. +The <\fIlength\fP> field shall be the decimal length of the extended +header record in octets, including the trailing +<newline>. +If there is a +.BR hdrcharset +extended header in effect for a file, the +.IR value +field for any +.BR gname , +.BR linkpath , +.BR path , +and +.BR uname +extended header records shall be encoded using the character set +specified by the +.BR hdrcharset +extended header record; otherwise, the +.IR value +field shall be encoded using UTF\(hy8. The +.IR value +field for all other keywords specified by POSIX.1\(hy2008 shall be +encoded using UTF\(hy8. +.P +The <\fIkeyword\fP> field shall be one of the entries from the +following list or a keyword provided as an implementation extension. +Keywords consisting entirely of lowercase letters, digits, and periods +are reserved for future standardization. A keyword shall not include an +<equals-sign>. +(In the following list, the notations ``file(s)'' or ``block(s)'' is used +to acknowledge that a keyword affects the following single file after a +.IR typeflag +.BR x +extended header, but possibly multiple files after +.IR typeflag +.BR g . +Any requirements in the list for +.IR pax +to include a record when in +.BR write +or +.BR copy +mode shall apply only when such a record has not already been provided +through the use of the +.BR \(mio +option. When used in +.BR copy +mode, +.IR pax +shall behave as if an archive had been created with applicable extended +header records and then extracted.) +.IP "\fBatime\fP" 10 +The file access time for the following file(s), equivalent to the value +of the +.IR st_atime +member of the +.BR stat +structure for a file, as described by the +\fIstat\fR() +function. The access time shall be restored if the process has +appropriate privileges required to do so. The format of the +<\fIvalue\fP> shall be as described in +.IR "pax Extended Header File Times". +.IP "\fBcharset\fP" 10 +The name of the character set used to encode the data in the following +file(s). The entries in the following table are defined to refer to +known standards; additional names may be agreed on between the +originator and recipient. +.TS +center box tab(!); +cB | cB +lf5 | l. +<value>!Formal Standard +_ +ISO-IR 646 1990!ISO/IEC 646:\|1990 +ISO-IR 8859 1 1998!ISO/IEC 8859\(hy1:\|1998 +ISO-IR 8859 2 1999!ISO/IEC 8859\(hy2:\|1999 +ISO-IR 8859 3 1999!ISO/IEC 8859\(hy3:\|1999 +ISO-IR 8859 4 1998!ISO/IEC 8859\(hy4:\|1998 +ISO-IR 8859 5 1999!ISO/IEC 8859\(hy5:\|1999 +ISO-IR 8859 6 1999!ISO/IEC 8859\(hy6:\|1999 +ISO-IR 8859 7 1987!ISO/IEC 8859\(hy7:\|1987 +ISO-IR 8859 8 1999!ISO/IEC 8859\(hy8:\|1999 +ISO-IR 8859 9 1999!ISO/IEC 8859\(hy9:\|1999 +ISO-IR 8859 10 1998!ISO/IEC 8859\(hy10:\|1998 +ISO-IR 8859 13 1998!ISO/IEC 8859\(hy13:\|1998 +ISO-IR 8859 14 1998!ISO/IEC 8859\(hy14:\|1998 +ISO-IR 8859 15 1999!ISO/IEC 8859\(hy15:\|1999 +ISO-IR 10646 2000!ISO/IEC 10646:\|2000 +ISO-IR 10646 2000 UTF-8!ISO/IEC 10646, UTF-8 encoding +BINARY!None. +.TE +.RS 10 +.P +The encoding is included in an extended header for information only; +when +.IR pax +is used as described in POSIX.1\(hy2008, it shall not translate the file data +into any other encoding. The +.BR BINARY +entry indicates unencoded binary data. +.P +When used in +.BR write +or +.BR copy +mode, it is implementation-defined whether +.IR pax +includes a +.BR charset +extended header record for a file. +.RE +.IP "\fBcomment\fP" 10 +A series of characters used as a comment. All characters in the +<\fIvalue\fP> field shall be ignored by +.IR pax . +.IP "\fBgid\fP" 10 +The group ID of the group that owns the file, expressed as a decimal +number using digits from the ISO/IEC\ 646:\|1991 standard. This record shall override the +.IR gid +field in the following header block(s). When used in +.BR write +or +.BR copy +mode, +.IR pax +shall include a +.IR gid +extended header record for each file whose group ID is greater than +2\|097\|151 (octal 7\|777\|777). +.IP "\fBgname\fP" 10 +The group of the file(s), formatted as a group name in the group +database. This record shall override the +.IR gid +and +.IR gname +fields in the following header block(s), and any +.IR gid +extended header record. When used in +.BR read , +.BR copy , +or +.BR list +mode, +.IR pax +shall translate the name from the encoding in the header record to +the character set appropriate for the group database on the +receiving system. If any of the characters cannot be +translated, and if neither the +.BR \(mio \c +.BR invalid=UTF\(hy8 +option nor the +.BR \(mio \c +.BR invalid=binary +option is specified, the results are implementation-defined. +When used in +.BR write +or +.BR copy +mode, +.IR pax +shall include a +.BR gname +extended header record for each file whose group name cannot be +represented entirely with the letters and digits of the portable +character set. +.IP "\fBhdrcharset\fR" 10 +The name of the character set used to encode the value field of the +.BR gname , +.BR linkpath , +.BR path , +and +.BR uname +.IR pax +extended header records. The entries in the following table are defined +to refer to known standards; additional names may be agreed between the +originator and the recipient. +.TS +center box tab(!); +cB | cB +lf5 | l. +<value>!Formal Standard +_ +ISO-IR 10646 2000 UTF-8!ISO/IEC 10646, UTF-8 encoding +BINARY!None. +.TE +.RS 10 +.P +If no +.BR hdrcharset +extended header record is specified, the default character set used to +encode all values in extended header records shall be the ISO/IEC\ 10646\(hy1:\|2000 standard +UTF\(hy8 encoding. +.P +The +.BR BINARY +entry indicates that all values recorded in extended headers for +affected files are unencoded binary data from the underlying system. +.RE +.IP "\fBlinkpath\fP" 10 +The pathname of a link being created to another file, of any type, +previously archived. This record shall override the +.IR linkname +field in the following +.BR ustar +header block(s). The following +.BR ustar +header block shall determine the type of link created. If +.IR typeflag +of the following header block is 1, it shall be a hard link. If +.IR typeflag +is 2, it shall be a symbolic link and the +.BR linkpath +value shall be the contents of the symbolic link. The +.IR pax +utility shall translate the name of the link (contents of the symbolic +link) from the encoding in the header to the character set appropriate +for the local file system. When used in +.BR write +or +.BR copy +mode, +.IR pax +shall include a +.BR linkpath +extended header record for each link whose pathname cannot be +represented entirely with the members of the portable character set +other than NUL. +.IP "\fBmtime\fP" 10 +The file modification time of the following file(s), equivalent to the +value of the +.IR st_mtime +member of the +.BR stat +structure for a file, as described in the +\fIstat\fR() +function. This record shall override the +.IR mtime +field in the following header block(s). The modification time shall be +restored if the process has appropriate privileges required to do +so. The format of the <\fIvalue\fP> shall be as described in +.IR "pax Extended Header File Times". +.IP "\fBpath\fP" 10 +The pathname of the following file(s). This record shall override the +.IR name +and +.IR prefix +fields in the following header block(s). The +.IR pax +utility shall translate the pathname of the file from the encoding in +the header to the character set appropriate for the local file system. +.RS 10 +.P +When used in +.BR write +or +.BR copy +mode, +.IR pax +shall include a +.IR path +extended header record for each file whose pathname cannot be +represented entirely with the members of the portable character set +other than NUL. +.RE +.IP "\fBrealtime.\fIany\fR" 10 +The keywords prefixed by ``realtime.'' are reserved for future +standardization. +.IP "\fBsecurity.\fIany\fR" 10 +The keywords prefixed by ``security.'' are reserved for future +standardization. +.IP "\fBsize\fP" 10 +The size of the file in octets, expressed as a decimal number using +digits from the ISO/IEC\ 646:\|1991 standard. This record shall override the +.IR size +field in the following header block(s). When used in +.BR write +or +.BR copy +mode, +.IR pax +shall include a +.IR size +extended header record for each file with a size value greater than +8\|589\|934\|591 (octal 77\|777\|777\|777). +.IP "\fBuid\fP" 10 +The user ID of the file owner, expressed as a decimal number using +digits from the ISO/IEC\ 646:\|1991 standard. This record shall override the +.IR uid +field in the following header block(s). When used in +.BR write +or +.BR copy +mode, +.IR pax +shall include a +.IR uid +extended header record for each file whose owner ID is greater than +2\|097\|151 (octal 7\|777\|777). +.IP "\fBuname\fP" 10 +The owner of the following file(s), formatted as a user name in the +user database. This record shall override the +.IR uid +and +.IR uname +fields in the following header block(s), and any +.IR uid +extended header record. When used in +.BR read , +.BR copy , +or +.BR list +mode, +.IR pax +shall translate the name from the encoding in the header record to the +character set appropriate for the user database on the receiving +system. If any of the characters cannot be translated, and if neither +the +.BR \(mio \c +.BR invalid=UTF\(hy8 +option nor the +.BR \(mio \c +.BR invalid=binary +option is specified, the results are implementation-defined. +When used in +.BR write +or +.BR copy +mode, +.IR pax +shall include a +.BR uname +extended header record for each file whose user name cannot be +represented entirely with the letters and digits of the portable +character set. +.P +If the <\fIvalue\fP> field is zero length, it shall delete any header +block field, previously entered extended header value, or global +extended header value of the same name. +.P +If a keyword in an extended header record (or in a +.BR \(mio +option-argument) overrides or deletes a corresponding field in the +.BR ustar +header block, +.IR pax +shall ignore the contents of that header block field. +.P +Unlike the +.BR ustar +header block fields, NULs shall not delimit <\fIvalue\fP>s; all +characters within the <\fIvalue\fP> field shall be considered data for +the field. None of the length limitations of the +.BR ustar +header block fields in +.IR "Table 4-14, ustar Header Block" +shall apply to the extended header records. +.SS "pax Extended Header Keyword Precedence" +.P +This section describes the precedence in which the various header +records and fields and command line options are selected to apply to a +file in the archive. When +.IR pax +is used in +.BR read +or +.BR list +modes, it shall determine a file attribute in the following sequence: +.IP " 1." 4 +If +.BR \(mio \c +.BR delete=keyword-prefix +is used, the affected attributes shall be determined from step 7., if +applicable, or ignored otherwise. +.IP " 2." 4 +If +.BR \(mio \c +.IR keyword := +is used, the affected attributes shall be ignored. +.IP " 3." 4 +If +.BR \(mio \c +.BR keyword:=value +is used, the affected attribute shall be assigned the value. +.IP " 4." 4 +If there is a +.IR typeflag +.BR x +extended header record, the affected attribute shall be assigned the +<\fIvalue\fP>. When extended header records conflict, the last one +given in the header shall take precedence. +.IP " 5." 4 +If +.BR \(mio \c +.BR keyword=value +is used, the affected attribute shall be assigned the value. +.IP " 6." 4 +If there is a +.IR typeflag +.BR g +global extended header record, the affected attribute shall be assigned +the <\fIvalue\fP>. When global extended header records conflict, the +last one given in the global header shall take precedence. +.IP " 7." 4 +Otherwise, the attribute shall be determined from the +.BR ustar +header block. +.SS "pax Extended Header File Times" +.P +The +.IR pax +utility shall write an +.BR mtime +record for each file in +.BR write +or +.BR copy +modes if the file's modification time cannot be represented exactly in +the +.BR ustar +header logical record described in +.IR "ustar Interchange Format". +This can occur if the time is out of +.BR ustar +range, or if the file system of the underlying implementation supports +non-integer time granularities and the time is not an integer. All of +these time records shall be formatted as a decimal representation of +the time in seconds since the Epoch. If a +<period> +(\c +.BR '.' ) +decimal point character is present, the digits to the right of the +point shall represent the units of a subsecond timing granularity, +where the first digit is tenths of a second and each subsequent digit +is a tenth of the previous digit. In +.BR read +or +.BR copy +mode, the +.IR pax +utility shall truncate the time of a file to the greatest value that is +not greater than the input header file time. In +.BR write +or +.BR copy +mode, the +.IR pax +utility shall output a time exactly if it can be represented exactly as +a decimal number, and otherwise shall generate only enough digits so +that the same time shall be recovered if the file is extracted on a +system whose underlying implementation supports the same time +granularity. +.SS "ustar Interchange Format" +.P +A +.BR ustar +archive tape or file shall contain a series of logical records. Each +logical record shall be a fixed-size logical record of 512 octets (see +below). Although this format may be thought of as being stored on +9-track industry-standard 12.7 mm (0.5 in) magnetic tape, other types of +transportable media are not excluded. Each file archived shall be +represented by a header logical record that describes the file, +followed by zero or more logical records that give the contents of the +file. At the end of the archive file there shall be two 512-octet +logical records filled with binary zeros, interpreted as an +end-of-archive indicator. +.P +The logical records may be grouped for physical I/O operations, as +described under the +.BR \(mib \c +.IR blocksize +and +.BR \(mix +.BR ustar +options. Each group of logical records may be written with a single +operation equivalent to the +\fIwrite\fR() +function. On magnetic tape, the result of this write shall be a single +tape physical block. The last physical block shall always be the full +size, so logical records after the two zero logical records may contain +undefined data. +.P +The header logical record shall be structured as shown in the following +table. All lengths and offsets are in decimal. +.br +.sp +.ce 1 +\fBTable 4-14: ustar Header Block\fR +.TS +center box tab(@); +cB | cB | cB +lI | n | n. +Field Name@Octet Offset@Length (in Octets) +_ +name@0@100 +mode@100@8 +uid@108@8 +gid@116@8 +size@124@12 +mtime@136@12 +chksum@148@8 +typeflag@156@1 +linkname@157@100 +magic@257@6 +version@263@2 +uname@265@32 +gname@297@32 +devmajor@329@8 +devminor@337@8 +prefix@345@155 +.TE +.P +All characters in the header logical record shall be represented in the +coded character set of the ISO/IEC\ 646:\|1991 standard. For maximum portability between +implementations, names should be selected from characters represented +by the portable filename character set as octets with the most +significant bit zero. If an implementation supports the use of +characters outside of +<slash> +and the portable filename character set in names for files, users, and +groups, one or more implementation-defined encodings of these characters +shall be provided for interchange purposes. +.P +However, the +.IR pax +utility shall never create filenames on the local system that cannot +be accessed via the procedures described in POSIX.1\(hy2008. If a filename is +found on the medium that would create an invalid filename, it is +implementation-defined whether the data from the file is stored on the +file hierarchy and under what name it is stored. The +.IR pax +utility may choose to ignore these files as long as it produces an +error indicating that the file is being ignored. +.P +Each field within the header logical record is contiguous; that is, +there is no padding used. Each character on the archive medium shall be +stored contiguously. +.P +The fields +.IR magic , +.IR uname , +and +.IR gname +are character strings each terminated by a NUL character. The fields +.IR name , +.IR linkname , +and +.IR prefix +are NUL-terminated character strings except when all characters in the +array contain non-NUL characters including the last character. The +.IR version +field is two octets containing the characters +.BR \(dq00\(dq +(zero-zero). The +.IR typeflag +contains a single character. All other fields are leading zero-filled +octal numbers using digits from the ISO/IEC\ 646:\|1991 standard IRV. Each numeric field is +terminated by one or more +<space> +or NUL characters. +.P +The +.IR name +and the +.IR prefix +fields shall produce the pathname of the file. A new pathname shall +be formed, if +.IR prefix +is not an empty string (its first character is not NUL), by +concatenating +.IR prefix +(up to the first NUL character), a +<slash> +character, and +.IR name ; +otherwise, +.IR name +is used alone. In either case, +.IR name +is terminated at the first NUL character. If +.IR prefix +begins with a NUL character, it shall be ignored. In this manner, +pathnames of at most 256 characters can be supported. If a pathname +does not fit in the space provided, +.IR pax +shall notify the user of the error, and shall not store any part of the +file\(emheader or data\(emon the medium. +.P +The +.IR linkname +field, described below, shall not use the +.IR prefix +to produce a pathname. As such, a +.IR linkname +is limited to 100 characters. If the name does not fit in the space +provided, +.IR pax +shall notify the user of the error, and shall not attempt to store the +link on the medium. +.P +The +.IR mode +field provides 12 bits encoded in the ISO/IEC\ 646:\|1991 standard octal digit representation. +The encoded bits shall represent the following values: +.br +.sp +.ce 1 +\fBTable: ustar \fImode\fP Field\fR +.TS +tab(!) center box; +cB | cB | cB +n | l | l. +Bit Value!POSIX.1\(hy2008 Bit!Description +_ +04\|000!S_ISUID!Set UID on execution. +02\|000!S_ISGID!Set GID on execution. +01\|000!<reserved>!Reserved for future standardization. +00\|400!S_IRUSR!Read permission for file owner class. +00\|200!S_IWUSR!Write permission for file owner class. +00\|100!S_IXUSR!Execute/search permission for file owner class. +00\|040!S_IRGRP!Read permission for file group class. +00\|020!S_IWGRP!Write permission for file group class. +00\|010!S_IXGRP!Execute/search permission for file group class. +00\|004!S_IROTH!Read permission for file other class. +00\|002!S_IWOTH!Write permission for file other class. +00\|001!S_IXOTH!Execute/search permission for file other class. +.TE +.P +When appropriate privileges are required to set one of these mode bits, +and the user restoring the files from the archive does not have +appropriate privileges, the mode bits for which the user does not have +appropriate privileges shall be ignored. Some of the mode bits in the +archive format are not mentioned elsewhere in this volume of POSIX.1\(hy2008. If the +implementation does not support those bits, they may be ignored. +.P +The +.IR uid +and +.IR gid +fields are the user and group ID of the owner and group of the file, +respectively. +.P +The +.IR size +field is the size of the file in octets. If the +.IR typeflag +field is set to specify a file to be of type 1 (a link) or 2 (a +symbolic link), the +.IR size +field shall be specified as zero. If the +.IR typeflag +field is set to specify a file of type 5 (directory), the +.IR size +field shall be interpreted as described under the definition of that +record type. No data logical records are stored for types 1, 2, or 5. +If the +.IR typeflag +field is set to 3 (character special file), 4 (block special file), or +6 (FIFO), the meaning of the +.IR size +field is unspecified by this volume of POSIX.1\(hy2008, and no data logical records shall be +stored on the medium. Additionally, for type 6, the +.IR size +field shall be ignored when reading. If the +.IR typeflag +field is set to any other value, the number of logical records written +following the header shall be (\c +.IR size +511)/512, +ignoring any fraction in the result of the division. +.P +The +.IR mtime +field shall be the modification time of the file at the time it was +archived. It is the ISO/IEC\ 646:\|1991 standard representation of the octal value of the +modification time obtained from the +\fIstat\fR() +function. +.P +The +.IR chksum +field shall be the ISO/IEC\ 646:\|1991 standard IRV representation of the octal value of the +simple sum of all octets in the header logical record. Each octet in +the header shall be treated as an unsigned value. These values shall be +added to an unsigned integer, initialized to zero, the precision of +which is not less than 17 bits. When calculating the checksum, the +.IR chksum +field is treated as if it were all +<space> +characters. +.P +The +.IR typeflag +field specifies the type of file archived. If a particular +implementation does not recognize the type, or the user does not have +appropriate privileges to create that type, the file shall be extracted +as if it were a regular file if the file type is defined to have a +meaning for the +.IR size +field that could cause data logical records to be written on the medium +(see the previous description for +.IR size ). +If conversion to a regular file occurs, the +.IR pax +utility shall produce an error indicating that the conversion took +place. All of the +.IR typeflag +fields shall be coded in the ISO/IEC\ 646:\|1991 standard IRV: +.IP "\fR0\fR" 8 +Represents a regular file. For backwards-compatibility, a +.IR typeflag +value of binary zero (\c +.BR '\e0' ) +should be recognized as meaning a regular file when extracting files +from the archive. Archives written with this version of the archive +file format create regular files with a +.IR typeflag +value of the ISO/IEC\ 646:\|1991 standard IRV +.BR '0' . +.IP "\fR1\fR" 8 +Represents a file linked to another file, of any type, previously +archived. Such files are identified by having the same device +and file serial numbers, and pathnames that refer to different +directory entries. All such files shall be archived as linked files. +The linked-to name is specified in the +.IR linkname +field with a NUL-character terminator if it is less than 100 octets in +length. +.IP "\fR2\fR" 8 +Represents a symbolic link. The contents of the symbolic link shall be +stored in the +.IR linkname +field. +.IP "\fR3,4\fR" 8 +Represent character special files and block special files respectively. +In this case the +.IR devmajor +and +.IR devminor +fields shall contain information defining the device, the format of +which is unspecified by this volume of POSIX.1\(hy2008. Implementations may map the device +specifications to their own local specification or may ignore the +entry. +.IP "\fR5\fR" 8 +Specifies a directory or subdirectory. On systems where disk allocation +is performed on a directory basis, the +.IR size +field shall contain the maximum number of octets (which may be rounded +to the nearest disk block allocation unit) that the directory may hold. +A +.IR size +field of zero indicates no such limiting. Systems that do not support +limiting in this manner should ignore the +.IR size +field. +.IP "\fR6\fR" 8 +Specifies a FIFO special file. Note that the archiving of a FIFO file +archives the existence of this file and not its contents. +.IP "\fR7\fR" 8 +Reserved to represent a file to which an implementation has associated +some high-performance attribute. Implementations without such +extensions should treat this file as a regular file (type 0). +.IP "\fRA\(hyZ\fR" 8 +The letters +.BR 'A' +to +.BR 'Z' , +inclusive, are reserved for custom implementations. All other values +are reserved for future versions of this standard. +.P +It is unspecified whether files with pathnames that refer to the same +directory entry are archived as linked files or as separate files. If +they are archived as linked files, this means that attempting to +extract both pathnames from the resulting archive will always cause an +error (unless the +.BR \(miu +option is used) because the link cannot be created. +.P +It is unspecified whether files with the same device and file serial +numbers being appended to an archive are treated as linked files to +members that were in the archive before the append. +.P +Attempts to archive a socket using +.BR ustar +interchange format shall produce a diagnostic message. Handling of +other file types is implementation-defined. +.P +The +.IR magic +field is the specification that this archive was output in this archive +format. If this field contains +.BR ustar +(the five characters from the ISO/IEC\ 646:\|1991 standard IRV shown followed by NUL), the +.IR uname +and +.IR gname +fields shall contain the ISO/IEC\ 646:\|1991 standard IRV representation of the owner and +group of the file, respectively (truncated to fit, if necessary). When +the file is restored by a privileged, protection-preserving version of +the utility, the user and group databases shall be scanned for these +names. If found, the user and group IDs contained within these files +shall be used rather than the values contained within the +.IR uid +and +.IR gid +fields. +.SS "cpio Interchange Format" +.P +The octet-oriented +.BR cpio +archive format shall be a series of entries, each comprising a header +that describes the file, the name of the file, and then the contents of +the file. +.P +An archive may be recorded as a series of fixed-size blocks of octets. +This blocking shall be used only to make physical I/O more efficient. +The last group of blocks shall always be at the full size. +.P +For the octet-oriented +.BR cpio +archive format, the individual entry information shall be in the order +indicated and described by the following table; see also the +.IR <cpio.h> +header. +.br +.sp +.ce 1 +\fBTable 4-16: Octet-Oriented cpio Archive Entry\fR +.TS +center box tab(!); +cB | cB | cB +lI | n | l. +Header Field Name!Length (in Octets)!Interpreted as +_ +c_magic!6!Octal number +c_dev!6!Octal number +c_ino!6!Octal number +c_mode!6!Octal number +c_uid!6!Octal number +c_gid!6!Octal number +c_nlink!6!Octal number +c_rdev!6!Octal number +c_mtime!11!Octal number +c_namesize!6!Octal number +c_filesize!11!Octal number +_ +.T& +cB | cB | cB +lI lI l. +Filename Field Name!Length!Interpreted as +_ +c_name!c_namesize!Pathname string +_ +.T& +cB | cB | cB +lI lI l. +File Data Field Name!Length!Interpreted as +_ +c_filedata!c_filesize!Data +.TE +.SS "cpio Header" +.P +For each file in the archive, a header as defined previously shall be +written. The information in the header fields is written as streams of +the ISO/IEC\ 646:\|1991 standard characters interpreted as octal numbers. The octal numbers +shall be extended to the necessary length by appending the ISO/IEC\ 646:\|1991 standard IRV +zeros at the most-significant-digit end of the number; the result is +written to the most-significant digit of the stream of octets first. +The fields shall be interpreted as follows: +.IP "\fIc_magic\fR" 10 +Identify the archive as being a transportable archive by containing the +identifying value +.BR \(dq070707\(dq . +.IP "\fIc_dev\fR,\ \fIc_ino\fR" 10 +Contains values that uniquely identify the file within the archive +(that is, no files contain the same pair of +.IR c_dev +and +.IR c_ino +values unless they are links to the same file). The values shall be +determined in an unspecified manner. +.IP "\fIc_mode\fR" 10 +Contains the file type and access permissions as defined in the +following table. +.br +.sp +.ce 1 +\fBTable 4-17: Values for cpio c_mode Field\fR +.TS +center box tab(@); +cB | cB | cB +l | n | l. +File Permissions Name@Value@Indicates +_ +C_IRUSR@000\|400@Read by owner +C_IWUSR@000\|200@Write by owner +C_IXUSR@000\|100@Execute by owner +C_IRGRP@000\|040@Read by group +C_IWGRP@000\|020@Write by group +C_IXGRP@000\|010@Execute by group +C_IROTH@000\|004@Read by others +C_IWOTH@000\|002@Write by others +C_IXOTH@000\|001@Execute by others +C_ISUID@004\|000@Set \fIuid\fP +C_ISGID@002\|000@Set \fIgid\fP +C_ISVTX@001\|000@Reserved +_ +.T& +cB | cB | cB +l | n | l. +File Type Name@Value@Indicates +_ +C_ISDIR@040\|000@Directory +C_ISFIFO@010\|000@FIFO +C_ISREG@0100\|000@Regular file +C_ISLNK@0120\|000@Symbolic link +.RS 10 +.P +C_ISBLK@060\|000@Block special file +C_ISCHR@020\|000@Character special file +C_ISSOCK@0140\|000@Socket +.P +C_ISCTG@0110\|000@Reserved +.TE +.P +Directories, FIFOs, symbolic links, and regular files shall be +supported on a system conforming to this volume of POSIX.1\(hy2008; additional values defined +previously are reserved for compatibility with existing systems. +Additional file types may be supported; however, such files should not +be written to archives intended to be transported to other systems. +.RE +.IP "\fIc_uid\fR" 10 +Contains the user ID of the owner. +.IP "\fIc_gid\fR" 10 +Contains the group ID of the group. +.IP "\fIc_nlink\fR" 10 +Contains a number greater than or equal to the number of links in the +archive referencing the file. If the +.BR \(mia +option is used to append to a +.IR cpio +archive, then the +.IR pax +utility need not account for the files in the existing part of the +archive when calculating the +.IR c_nlink +values for the appended part of the archive, and need not alter the +.IR c_nlink +values in the existing part of the archive if additional files with the +same +.IR c_dev +and +.IR c_ino +values are appended to the archive. +.IP "\fIc_rdev\fR" 10 +Contains implementation-defined information for character or block +special files. +.IP "\fIc_mtime\fR" 10 +Contains the latest time of modification of the file at the time the +archive was created. +.IP "\fIc_namesize\fR" 10 +Contains the length of the pathname, including the terminating NUL +character. +.IP "\fIc_filesize\fR" 10 +Contains the length in octets of the data section following the +header structure. +.SS "cpio Filename" +.P +The +.IR c_name +field shall contain the pathname of the file. The length of this field +in octets is the value of +.IR c_namesize . +.P +If a filename is found on the medium that would create an invalid +pathname, it is implementation-defined whether the data from the file +is stored on the file hierarchy and under what name it is stored. +.P +All characters shall be represented in the ISO/IEC\ 646:\|1991 standard IRV. For maximum +portability between implementations, names should be selected from +characters represented by the portable filename character set as +octets with the most significant bit zero. If an implementation +supports the use of characters outside the portable filename character +set in names for files, users, and groups, one or more +implementation-defined encodings of these characters shall be provided +for interchange purposes. However, the +.IR pax +utility shall never create filenames on the local system that cannot +be accessed via the procedures described previously in this volume of POSIX.1\(hy2008. If a +filename is found on the medium that would create an invalid filename, +it is implementation-defined whether the data from the file is stored on +the local file system and under what name it is stored. The +.IR pax +utility may choose to ignore these files as long as it produces an +error indicating that the file is being ignored. +.SS "cpio File Data" +.P +Following +.IR c_name , +there shall be +.IR c_filesize +octets of data. Interpretation of such data occurs in a manner +dependent on the file. For regular files, the data shall consist +of the contents of the file. For symbolic links, the data shall +consist of the contents of the symbolic link. If +.IR c_filesize +is zero, no data shall be contained in +.IR c_filedata . +.P +When restoring from an archive: +.IP " *" 4 +If the user does not have appropriate privileges to create a file of +the specified type, +.IR pax +shall ignore the entry and write an error message to standard error. +.IP " *" 4 +Only regular files and symbolic links have data to be restored. Presuming +a regular file meets any selection criteria that might be imposed on +the format-reading utility by the user, such data shall be restored. +.IP " *" 4 +If a user does not have appropriate privileges to set a particular mode +flag, the flag shall be ignored. Some of the mode flags in the archive +format are not mentioned elsewhere in this volume of POSIX.1\(hy2008. If the implementation does +not support those flags, they may be ignored. +.SS "cpio Special Entries" +.P +FIFO special files, directories, and the trailer shall be recorded with +.IR c_filesize +equal to zero. Symbolic links shall be recorded with +.IR c_filesize +equal to the length of the contents of the symbolic link. +For other special files, +.IR c_filesize +is unspecified by this volume of POSIX.1\(hy2008. The header for the next file entry in the +archive shall be written directly after the last octet of the file +entry preceding it. A header denoting the filename +.BR TRAILER!!! +shall indicate the end of the archive; the contents of octets in the +last block of the archive following such a header are undefined. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All files were processed successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If +.IR pax +cannot create a file or a link when reading an archive or cannot find a +file when writing an archive, or cannot preserve the user ID, group ID, +or file mode when the +.BR \(mip +option is specified, a diagnostic message shall be written to standard +error and a non-zero exit status shall be returned, but processing +shall continue. In the case where +.IR pax +cannot create a link to a file, +.IR pax +shall not, by default, create a second copy of the file. +.P +If the extraction of a file from an archive is prematurely terminated +by a signal or error, +.IR pax +may have only partially extracted the file or (if the +.BR \(min +option was not specified) may 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 may have +additional bits from the S_IRWXU mask set as well as incorrect +modification and access times. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Caution is advised when using the +.BR \(mia +option to append to a +.IR cpio +format archive. If any of the files being appended happen to be given +the same +.IR c_dev +and +.IR c_ino +values as a file in the existing part of the archive, then they may be +treated as links to that file on extraction. Thus, it is risky to use +.BR \(mia +with +.IR cpio +format except when it is done on the same system that the original +archive was created on, and with the same +.IR pax +utility, and in the knowledge that there has been little or no file +system activity since the original archive was created that could lead +to any of the files appended being given the same +.IR c_dev +and +.IR c_ino +values as an unrelated file in the existing part of the archive. Also, +when (intentionally) appending additional links to a file in the +existing part of the archive, the +.IR c_nlink +values in the modified archive can be smaller than the number of links +to the file in the archive, which may mean that the links are not +preserved on extraction. +.P +The +.BR \(mip +(privileges) option was invented to reconcile differences between +historical +.IR tar +and +.IR cpio +implementations. In particular, the two utilities use +.BR \(mim +in diametrically opposed ways. The +.BR \(mip +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 may seem complex, there +are really two modes that are most commonly used: +.IP "\fB\(mip\ e\fR" 8 +``Preserve everything''. This would be used by the historical +superuser, someone with all appropriate privileges, to preserve all +aspects of the files as they are recorded in the archive. The +.BR e +flag is the sum of +.BR o +and +.BR p , +and other implementation-defined attributes. +.IP "\fB\(mip\ p\fR" 8 +``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 preserved by default, but two +other flags are offered to disable these and use the time of +extraction. +.P +The one pathname per line format of standard input precludes +pathnames containing +<newline> +characters. Although such pathnames violate the portable filename +guidelines, they may exist and their presence may inhibit usage of +.IR pax +within shell scripts. This problem is inherited from historical archive +programs. The problem can be avoided by listing filename arguments on +the command line instead of on standard input. +.P +It is almost certain that appropriate privileges are required for +.IR pax +to accomplish parts of this volume of POSIX.1\(hy2008. Specifically, creating files of type +block special or character special, restoring file access times unless +the files are owned by the user (the +.BR \(mit +option), or preserving file owner, group, and mode (the +.BR \(mip +option) all probably require appropriate privileges. +.P +In +.BR read +mode, implementations are permitted to overwrite files when the archive +has multiple members with the same name. This may fail if permissions +on the first version of the file do not permit it to be overwritten. +.P +The +.BR cpio +and +.BR ustar +formats can only support files up to 8\|589\|934\|592 bytes +(8 \(** 2^30) in size. +.P +When archives containing binary header information are listed , the +filenames printed may cause strange behavior on some terminals. +.P +When all of the following are true: +.IP " 1." 4 +A file of type directory is being placed into an archive. +.IP " 2." 4 +The +.BR ustar +archive format is being used. +.IP " 3." 4 +The pathname of the directory is less than or equal to 155 bytes long +(it will fit in the +.IR prefix +field in the +.BR ustar +header block). +.IP " 4." 4 +The last component of the pathname of the directory is longer than 100 +bytes long (it will not fit in the +.IR name +field in the +.BR ustar +header block). +.P +some implementations of the +.IR pax +utility will place the entire directory pathname in the +.IR prefix +field, set the +.IR name +field to an empty string, and place the directory in the archive. +Other implementations of the +.IR pax +utility will give an error under these conditions because the +.IR name +field is not large enough to hold the last component of the directory name. +This standard allows either behavior. However, when extracting a directory +from a +.BR ustar +format archive, this standard requires that all implementations be able +to extract a directory even if the +.IR name +field contains an empty string as long as the +.IR prefix +field does not also contain an empty string. +.SH EXAMPLES +The following command: +.sp +.RS 4 +.nf +\fB +pax \(miw \(mif /dev/rmt/1m . +.fi \fR +.P +.RE +.P +copies the contents of the current directory to tape drive 1, medium +density (assuming historical System V device naming procedures\(emthe +historical BSD device name would be +.BR /dev/rmt9 ). +.P +The following commands: +.sp +.RS 4 +.nf +\fB +mkdir \fInewdir\fR +pax \(mirw \fIolddir newdir\fR +.fi \fR +.P +.RE +.P +copy the +.IR olddir +directory hierarchy to +.IR newdir . +.sp +.RS 4 +.nf +\fB +pax \(mir \(mis ',^//*usr//*,,' \(mif a.pax +.fi \fR +.P +.RE +.P +reads the archive +.BR a.pax , +with all files rooted in +.BR /usr +in the archive extracted relative to the current directory. +.P +Using the option: +.sp +.RS 4 +.nf +\fB +\(mio listopt="%M %(atime)T %(size)D %(name)s" +.fi \fR +.P +.RE +.P +overrides the default output description in Standard Output and instead +writes: +.sp +.RS 4 +.nf +\fB +\(mirw\(mirw\(mi\|\(mi\|\(mi Jan 12 15:53 2003 1492 /usr/foo/bar +.fi \fR +.P +.RE +.P +Using the options: +.sp +.RS 4 +.nf +\fB +\(mio listopt='%L\et%(size)D\en%.7' \e +\(mio listopt='(name)s\en%(atime)T\en%T' +.fi \fR +.P +.RE +.P +overrides the default output description in Standard Output and instead +writes: +.sp +.RS 4 +.nf +\fB +/usr/foo/bar \(mi> /tmp 1492 +/usr/fo +Jan 12 15:53 1991 +Jan 31 15:53 2003 +.fi \fR +.P +.RE +.SH RATIONALE +The +.IR pax +utility was new for the ISO\ POSIX\(hy2:\|1993 standard. It represents a peaceful +compromise between advocates of the historical +.IR tar +and +.IR cpio +utilities. +.P +A fundamental difference between +.IR cpio +and +.IR tar +was in the way directories were treated. The +.IR cpio +utility did not treat directories differently from other files, and to +select a directory and its contents required that each file in the +hierarchy be explicitly specified. For +.IR tar , +a directory matched every file in the file hierarchy it rooted. +.P +The +.IR pax +utility offers both interfaces; by default, directories map into the +file hierarchy they root. The +.BR \(mid +option causes +.IR pax +to skip any file not explicitly referenced, as +.IR cpio +historically did. The +.IR tar +.BR \(mi \c +.IR style +behavior was chosen as the default because it was believed that this +was the more common usage and because +.IR tar +is the more commonly available interface, as it was historically +provided on both System V and BSD implementations. +.P +The data interchange format specification in this volume of POSIX.1\(hy2008 requires that +processes with ``appropriate privileges'' shall always restore the +ownership and permissions of extracted files exactly as archived. If +viewed from the historic equivalence between superuser and +``appropriate privileges'', there are two problems +with this requirement. First, users running as superusers may +unknowingly set dangerous permissions on extracted files. Second, it is +needlessly limiting, in that superusers cannot extract files and own +them as superuser unless the archive was created by the superuser. (It +should be noted that restoration of ownerships and permissions for the +superuser, by default, is historical practice in +.IR cpio , +but not in +.Im tar .) +In order to avoid these two problems, the +.IR pax +specification has an additional ``privilege'' mechanism, the +.BR \(mip +option. Only a +.IR pax +invocation with the privileges needed, and which has the +.BR \(mip +option set using the +.BR e +specification character, has appropriate privileges to restore +full ownership and permission information. +.P +Note also that this volume of POSIX.1\(hy2008 requires that the file ownership and access +permissions shall be set, on extraction, in the same fashion as the +\fIcreat\fR() +function when provided with the mode stored in the archive. This means +that the file creation mask of the user is applied to the file +permissions. +.P +Users should note that directories may be created by +.IR pax +while extracting files with permissions that are different from those +that existed at the time the archive was created. When extracting +sensitive information into a directory hierarchy that no longer exists, +users are encouraged to set their file creation mask appropriately to +protect these files during extraction. +.P +The table of contents output is written to standard output to +facilitate pipeline processing. +.P +An early proposal had hard links displaying for all pathnames. This +was removed because it complicates the output of the case where +.BR \(miv +is not specified and does not match historical +.IR cpio +usage. The hard-link information is available in the +.BR \(miv +display. +.P +The description of the +.BR \(mil +option allows implementations to make hard links to symbolic links. +Earlier versions of this standard did not specify any way to create a +hard link to a symbolic link, but many implementations provided this +capability as an extension. If there are hard links to symbolic links +when an archive is created, the implementation is required to archive +the hard link in the archive (unless +.BR \(miH +or +.BR \(miL +is specified). When in +.BR read +mode and in +.BR copy +mode, implementations supporting hard links to symbolic links should +use them when appropriate. +.P +The archive formats inherited from the POSIX.1\(hy1990 standard have certain restrictions +that have been brought along from historical usage. For example, there +are restrictions on the length of pathnames stored in the archive. +When +.IR pax +is used in +.BR copy (\c +.BR \(mirw ) +mode (copying directory hierarchies), the ability to use extensions +from the +.BR \(mix \c +.BR pax +format overcomes these restrictions. +.P +The default +.IR blocksize +value of 5\|120 bytes for +.IR cpio +was selected because it is one of the standard block-size values for +.IR cpio , +set when the +.BR \(miB +option is specified. (The other default block-size value for +.IR cpio +is 512 bytes, and this was considered to be too small.) The default +block value of 10\|240 bytes for +.IR tar +was selected because that is the standard block-size value for BSD +.IR tar . +The maximum block size of 32\|256 bytes (2\s-3\u15\d\s+3\(mi512 bytes) +is the largest multiple of 512 bytes that fits into a signed 16-bit +tape controller transfer register. There are known limitations in some +historical systems that would prevent larger blocks from being +accepted. Historical values were chosen to improve compatibility with +historical scripts using +.IR dd +or similar utilities to manipulate archives. Also, default block sizes +for any file type other than character special file has been deleted +from this volume of POSIX.1\(hy2008 as unimportant and not likely to affect the structure of the +resulting archive. +.P +Implementations are permitted to modify the block-size value based on +the archive format or the device to which the archive is being +written. This is to provide implementations with the opportunity to +take advantage of special types of devices, and it should not be used +without a great deal of consideration as it almost certainly decreases +archive portability. +.P +The intended use of the +.BR \(min +option was to permit extraction of one or more files from the archive +without processing the entire archive. This was viewed by the standard +developers as offering significant performance advantages over +historical implementations. The +.BR \(min +option in early proposals had three effects; the first was to cause +special characters in patterns to not be treated specially. The second +was to cause only the first file that matched a pattern to be +extracted. The third was to cause +.IR pax +to write a diagnostic message to standard error when no file was found +matching a specified pattern. Only the second behavior is retained by +this volume of POSIX.1\(hy2008, for many reasons. First, it is in general not acceptable for a +single option to have multiple effects. Second, the ability to make +pattern matching characters act as normal characters +is useful for parts of +.IR pax +other than file extraction. Third, a finer degree of control over the +special characters is useful because users may wish to normalize only a +single special character in a single filename. Fourth, given a more +general escape mechanism, the previous behavior of the +.BR \(min +option can be easily obtained using the +.BR \(mis +option or a +.IR sed +script. Finally, writing a diagnostic message when a pattern specified +by the user is unmatched by any file is useful behavior in all cases. +.P +In this version, the +.BR \(min +was removed from the +.BR copy +mode synopsis of +.IR pax ; +it is inapplicable because there are no pattern operands specified in +this mode. +.P +There is another method than +.IR pax +for copying subtrees in POSIX.1\(hy2008 described as part of the +.IR cp +utility. Both methods are historical practice: +.IR cp +provides a simpler, more intuitive interface, while +.IR pax +offers a finer granularity of control. Each provides additional +functionality to the other; in particular, +.IR pax +maintains the hard-link structure of the hierarchy while +.IR cp +does not. It is the intention of the standard developers that the +results be similar (using appropriate option combinations in both +utilities). The results are not required to be identical; there seemed +insufficient gain to applications to balance the difficulty of +implementations having to guarantee that the results would be exactly +identical. +.P +A single archive may span more than one file. It is suggested that +implementations provide informative messages to the user on standard +error whenever the archive file is changed. +.P +The +.BR \(mid +option (do not create intermediate directories not listed in the +archive) found in early proposals was originally provided as a +complement to the historic +.BR \(mid +option of +.IR cpio . +It has been deleted. +.P +The +.BR \(mis +option in early proposals specified a subset of the substitution +command from the +.IR ed +utility. As there was no reason for only a subset to be supported, the +.BR \(mis +option is now compatible with the current +.IR ed +specification. Since the delimiter can be any non-null character, the +following usage with single +<space> +characters is valid: +.sp +.RS 4 +.nf +\fB +pax \(mis " foo bar " ... +.fi \fR +.P +.RE +.P +The +.BR \(mit +description is worded so as to note that this may cause the access time +update caused by some other activity (which occurs while the file is +being read) to be overwritten. +.P +The default behavior of +.IR pax +with regard to file modification times is the same as historical +implementations of +.IR tar . +It is not the historical behavior of +.IR cpio . +.P +Because the +.BR \(mii +option uses +.BR /dev/tty , +utilities without a controlling terminal are not able to use this +option. +.P +The +.BR \(miy +option, found in early proposals, has been deleted because a line +containing a single +<period> +for the +.BR \(mii +option has equivalent functionality. The special lines for the +.BR \(mii +option (a single +<period> +and the empty line) are historical practice in +.IR cpio . +.P +In early drafts, a +.BR \(mie \c +.IR charmap +option was included to increase portability of files between systems +using different coded character sets. This option was omitted because +it was apparent that consensus could not be formed for it. In this +version, the use of UTF\(hy8 should be an adequate substitute. +.P +The ISO\ POSIX\(hy2:\|1993 standard and ISO\ POSIX\(hy1 standard requirements for +.IR pax , +however, made it very difficult to create a single archive containing +files created using extended characters provided by different locales. +This version adds the +.BR hdrcharset +keyword to make it possible to archive files in these cases without +dropping files due to translation errors. +.P +Translating filenames and other attributes from a locale's encoding to +UTF\(hy8 and then back again can lose information, as the resulting +filename might not be byte-for-byte equivalent to the original. To +avoid this problem, users can specify the +.BR \(mio +.BR hdrcharset=binary +option, which will cause the resulting archive to use binary +format for all names and attributes. Such archives are not portable +among hosts that use different native encodings (e.g., EBCDIC +\fIversus\fR ASCII-based encodings), but they will allow interchange +among the vast majority of POSIX file systems in practical use. Also, +the +.BR \(mio +.BR hdrcharset=binary +option will cause +.IR pax +in +.BR copy +mode to behave more like other standard utilities such as +.IR cp . +.P +If the values specified by the +.BR \(mio +.BR exthdr.name=value , +.BR \(mio +.BR globexthdr.name=value , +or by +.BR $TMPDIR +(if +.BR \(mio +.BR globexthdr.name +is not specified) require a character encoding other than that +described in the ISO/IEC\ 646:\|1991 standard, a +.BR path +extended header record will have to be created for the file. If a +.BR hdrcharset +extended header record is active for such headers, it will determine +the codeset used for the value field in these extended +.BR path +header records. These +.BR path +extended header records always need to be created when writing an +archive even if +.BR hdrcharset=binary +has been specified and would contain the same (binary) data that +appears in the +.BR ustar +header record prefix and +.IR name +fields. (In other words, an extended header +.BR path +record is always required to be generated if the +.IR prefix +or +.IR name +fields contain non-ASCII characters even when +.BR hdrcharset=binary +is also in effect for that file.) +.P +The +.BR \(mik +option was added to address international concerns about the dangers +involved in the character set transformations of +.BR \(mie +(if the target character set were different from the source, the +filenames might be transformed into names matching existing files) and +also was made more general to protect files transferred between file +systems with different +{NAME_MAX} +values (truncating a filename on a smaller system might also +inadvertently overwrite existing files). As stated, it prevents any +overwriting, even if the target file is older than the source. This +version adds more granularity of options to solve this problem by +introducing the +.BR \(mio \c +.BR invalid=option \c +\(emspecifically the +.BR UTF\(hy8 +and +.BR binary +actions. (Note that an existing file is still subject to overwriting in +this case. The +.BR \(mik +option closes that loophole.) +.P +Some of the file characteristics referenced in this volume of POSIX.1\(hy2008 might not be +supported by some archive formats. For example, neither the +.BR tar +nor +.BR cpio +formats contain the file access time. For this reason, the +.BR e +specification character has been provided, intended to cause all file +characteristics specified in the archive to be retained. +.P +It is required that extracted directories, by default, have their +access and modification times and permissions set to the values +specified in the archive. This has obvious problems in that the +directories are almost certainly modified after being extracted and +that directory permissions may not permit file creation. One possible +solution is to create directories with the mode specified in the +archive, as modified by the +.IR umask +of the user, with sufficient permissions to allow file creation. After +all files have been extracted, +.IR pax +would then reset the access and modification times and permissions as +necessary. +.P +The list-mode formatting description borrows heavily from the one +defined by the +.IR printf +utility. However, since there is no separate operand list to get +conversion arguments, the format was extended to allow specifying the +name of the conversion argument as part of the conversion +specification. +.P +The +.BR T +conversion specifier allows time fields to be displayed in any of +the date formats. Unlike the +.IR ls +utility, +.IR pax +does not adjust the format when the date is less than six months in the +past. This makes parsing the output more predictable. +.P +The +.BR D +conversion specifier handles the ability to display the major/minor +or file size, as with +.IR ls , +by using \fR%\(mi8(\fIsize\fR)D\fR. +.P +The +.BR L +conversion specifier handles the +.IR ls +display for symbolic links. +.P +Conversion specifiers were added to generate existing known types used +for +.IR ls . +.SS "pax Interchange Format" +.P +The new POSIX data interchange format was developed primarily to +satisfy international concerns that the +.BR ustar +and +.BR cpio +formats did not provide for file, user, and group names encoded in +characters outside a subset of the ISO/IEC\ 646:\|1991 standard. The standard developers +realized that this new POSIX data interchange format should be very +extensible because there were other requirements they foresaw in the +near future: +.IP " *" 4 +Support international character encodings and locale information +.IP " *" 4 +Support security information (ACLs, and so on) +.IP " *" 4 +Support future file types, such as realtime or contiguous files +.IP " *" 4 +Include data areas for implementation use +.IP " *" 4 +Support systems with words larger than 32 bits and timers with +subsecond granularity +.P +The following were not goals for this format because these are better +handled by separate utilities or are inappropriate for a portable +format: +.IP " *" 4 +Encryption +.IP " *" 4 +Compression +.IP " *" 4 +Data translation between locales and codesets +.IP " *" 4 +.IR inode +storage +.P +The format chosen to support the goals is an extension of the +.BR ustar +format. Of the two formats previously available, only the +.BR ustar +format was selected for extensions because: +.IP " *" 4 +It was easier to extend in an upwards-compatible way. It offered version +flags and header block type fields with room for future +standardization. The +.BR cpio +format, while possessing a more flexible file naming methodology, could +not be extended without breaking some theoretical implementation +or using a dummy filename that could be a legitimate filename. +.IP " *" 4 +Industry experience since the original ``\c +.IR tar +wars'' fought in developing the ISO\ POSIX\(hy1 standard has clearly been in favor of the +.BR ustar +format, which is generally the default output format selected for +.IR pax +implementations on new systems. +.P +The new format was designed with one additional goal in mind: +reasonable behavior when an older +.IR tar +or +.IR pax +utility happened to read an archive. Since the POSIX.1\(hy1990 standard mandated that a +``format-reading utility'' had to treat unrecognized +.IR typeflag +values as regular files, this allowed the format to include all the +extended information in a pseudo-regular file that preceded each real +file. An option is given that allows the archive creator to set up +reasonable names for these files on the older systems. Also, the +normative text suggests that reasonable file access values be used for +this +.BR ustar +header block. Making these header files inaccessible for convenient +reading and deleting would not be reasonable. File permissions of 600 +or 700 are suggested. +.P +The +.BR ustar +.IR typeflag +field was used to accommodate the additional functionality of the new +format rather than magic or version because the POSIX.1\(hy1990 standard (and, by +reference, the previous version of +.IR pax ), +mandated the behavior of the format-reading utility when it encountered +an unknown +.IR typeflag , +but was silent about the other two fields. +.P +Early proposals for the first version of this standard contained a proposed +archive format that was based on compatibility with the standard for +tape files (ISO\ 1001, similar to the format used historically on many +mainframes and minicomputers). This format was overly complex and required +considerable overhead in volume and header records. Furthermore, the +standard developers felt that it would not be acceptable to the community +of POSIX developers, so it was later changed to be a format more closely +related to historical practice on POSIX systems. +.P +The prefix and name split of pathnames in +.BR ustar +was replaced by the single path extended header record for simplicity. +.P +The concept of a global extended header (\c +.IR typeflag \c +.BR g ) +was controversial. If this were applied to an archive being recorded on +magnetic tape, a few unreadable blocks at the beginning of the tape +could be a serious problem; a utility attempting to extract as many +files as possible from a damaged archive could lose a large percentage +of file header information in this case. However, if the archive were +on a reliable medium, such as a CD\(hyROM, the global extended header +offers considerable potential size reductions by eliminating redundant +information. Thus, the text warns against using the global method for +unreliable media and provides a method for implanting global +information in the extended header for each file, rather than in the +.IR typeflag +.BR g +records. +.P +No facility for data translation or filtering on a per-file basis is +included because the standard developers could not invent an interface +that would allow this in an efficient manner. If a filter, such as +encryption or compression, is to be applied to all the files, it is +more efficient to apply the filter to the entire archive as a single +file. The standard developers considered interfaces that would invoke a +shell script for each file going into or out of the archive, but the +system overhead in this approach was considered to be too high. +.P +One such approach would be to have +.BR filter= +records that give a pathname for an executable. When the program is +invoked, the file and archive would be open for standard input/output +and all the header fields would be available as environment variables +or command-line arguments. The standard developers did discuss such +schemes, but they were omitted from POSIX.1\(hy2008 due to concerns about +excessive overhead. Also, the program itself would need to be in the +archive if it were to be used portably. +.P +There is currently no portable means of identifying the character +set(s) used for a file in the file system. Therefore, +.IR pax +has not been given a mechanism to generate charset records +automatically. The only portable means of doing this is for the user to +write the archive using the +.BR \(mio \c +.BR charset=string +command line option. This assumes that all of the files in the archive +use the same encoding. The ``implementation-defined'' text is +included to allow for a system that can identify the encodings used for +each of its files. +.P +The table of standards that accompanies the charset record description +is acknowledged to be very limited. Only a limited number of character +set standards is reasonable for maximal interchange. Any character set +is, of course, possible by prior agreement. It was suggested that +EBCDIC be listed, but it was omitted because it is not defined by a +formal standard. Formal standards, and then only those with reasonably +large followings, can be included here, simply as a matter of +practicality. The <\fIvalue\fP>s represent names of officially +registered character sets in the format required by the ISO\ 2375:\|1985 standard. +.P +The normal +<comma> +or +<blank>-separated +list rules are not followed in the case of keyword options to allow +ease of argument parsing for +.IR getopts . +.P +Further information on character encodings is in +.IR "pax Archive Character Set Encoding/Decoding". +.P +The standard developers have reserved keyword name space for vendor +extensions. It is suggested that the format to be used is: +.sp +.RS 4 +.nf +\fB +\fIVENDOR.keyword\fR +.fi \fR +.P +.RE +.P +where +.IR VENDOR +is the name of the vendor or organization in all uppercase letters. It +is further suggested that the keyword following the +<period> +be named differently than any of the standard keywords so that it could +be used for future standardization, if appropriate, by omitting the +.IR VENDOR +prefix. +.P +The <\fIlength\fP> field in the extended header record was included to +make it simpler to step through the records, even if a record contains +an unknown format (to a particular +.IR pax ) +with complex interactions of special characters. It also provides a +minor integrity checkpoint within the records to aid a program +attempting to recover files from a damaged archive. +.P +There are no extended header versions of the +.IR devmajor +and +.IR devminor +fields because the unspecified format +.BR ustar +header field should be sufficient. If they are not, vendor-specific +extended keywords (such as +.IR VENDOR.devmajor ) +should be used. +.P +Device and +.IR i -number +labeling of files was not adopted from +.IR cpio ; +files are interchanged strictly on a symbolic name basis, as in +.BR ustar . +.P +Just as with the +.BR ustar +format descriptions, the new format makes no special arrangements for +multi-volume archives. Each of the +.IR pax +archive types is assumed to be inside a single POSIX file and splitting +that file over multiple volumes (diskettes, tape cartridges, and so +on), processing their labels, and mounting each in the proper sequence +are considered to be implementation details that cannot be described +portably. +.P +The +.BR pax +format is intended for interchange, not only for backup on a single +(family of) systems. It is not as densely packed as might be possible +for backup: +.IP " *" 4 +It contains information as coded characters that could be coded in +binary. +.IP " *" 4 +It identifies extended records with name fields that could be omitted +in favor of a fixed-field layout. +.IP " *" 4 +It translates names into a portable character set and identifies +locale-related information, both of which are probably unnecessary for +backup. +.P +The requirements on restoring from an archive are slightly different +from the historical wording, allowing for non-monolithic privilege to +bring forward as much as possible. In particular, attributes such as +``high performance file'' might be broadly but not universally granted +while set-user-ID or +\fIchown\fR() +might be much more restricted. There is no implication in POSIX.1\(hy2008 that +the security information be honored after it is restored to the file +hierarchy, in spite of what might be improperly inferred by the silence +on that topic. That is a topic for another standard. +.P +Links are recorded in the fashion described here because a link can be +to any file type. It is desirable in general to be able to restore part +of an archive selectively and restore all of those files completely. If +the data is not associated with each link, it is not possible to do +this. However, the data associated with a file can be large, and when +selective restoration is not needed, this can be a significant burden. +The archive is structured so that files that have no associated data +can always be restored by the name of any link name of any link, and +the user may choose whether data is recorded with each instance of a +file that contains data. The format permits mixing of both types of +links in a single archive; this can be done for special needs, and +.IR pax +is expected to interpret such archives on input properly, despite the +fact that there is no +.IR pax +option that would force this mixed case on output. (When +.BR \(mio +.BR linkdata +is used, the output must contain the duplicate data, but the +implementation is free to include it or omit it when +.BR \(mio +.BR linkdata +is not used.) +.P +The time values are included as extended header records for those +implementations needing more than the eleven octal digits allowed by +the +.BR ustar +format. Portable file timestamps cannot be negative. If +.IR pax +encounters a file with a negative timestamp in +.BR copy +or +.BR write +mode, it can reject the file, substitute a non-negative timestamp, or +generate a non-portable timestamp with a leading +.BR '\(mi' . +Even though some implementations can support finer file-time +granularities than seconds, the normative text requires support only +for seconds since the Epoch because the ISO\ POSIX\(hy1 standard states them that way. The +.BR ustar +format includes only +.IR mtime ; +the new format adds +.IR atime +and +.IR ctime +for symmetry. The +.IR atime +access time restored to the file system will be affected by the +.BR \(mip +.BR a +and +.BR \(mip +.BR e +options. The +.IR ctime +creation time (actually +.IR inode +modification time) is described with appropriate privileges so that +it can be ignored when writing to the file system. POSIX does not +provide a portable means to change file creation time. Nothing is +intended to prevent a non-portable implementation of +.IR pax +from restoring the value. +.P +The +.IR gid , +.IR size , +and +.IR uid +extended header records were included to allow expansion beyond the +sizes specified in the regular +.IR tar +header. New file system architectures are emerging that will exhaust +the 12-digit size field. There are probably not many systems requiring +more than 8 digits for user and group IDs, but the extended header +values were included for completeness, allowing overrides for all of +the decimal values in the +.IR tar +header. +.P +The standard developers intended to describe the effective results of +.IR pax +with regard to file ownerships and permissions; implementations are not +restricted in timing or sequencing the restoration of such, provided +the results are as specified. +.P +Much of the text describing the extended headers refers to use in ``\c +.BR write +or +.BR copy +modes''. The +.BR copy +mode references are due to the normative text: ``The effect of the +copy shall be as if the copied files were written to an archive file +and then subsequently extracted .\|.\|.''. There is certainly no way to +test whether +.IR pax +is actually generating the extended headers in +.BR copy +mode, but the effects must be as if it had. +.SS "pax Archive Character Set Encoding/Decoding" +.P +There is a need to exchange archives of files between systems of +different native codesets. Filenames, group names, and user names must +be preserved to the fullest extent possible when an archive is read on +the receiving platform. Translation of the contents of files is not +within the scope of the +.IR pax +utility. +.P +There will also be the need to represent characters that are not +available on the receiving platform. These unsupported characters +cannot be automatically folded to the local set of characters due to +the chance of collisions. This could result in overwriting previous +extracted files from the archive or pre-existing files on the system. +.P +For these reasons, the codeset used to represent characters within the +extended header records of the +.IR pax +archive must be sufficiently rich to handle all commonly used character +sets. The fields requiring translation include, at a minimum, +filenames, user names, group names, and link pathnames. Implementations +may wish to have localized extended keywords that use non-portable +characters. +.P +The standard developers considered the following options: +.IP " *" 4 +The archive creator specifies the well-defined name of the source +codeset. The receiver must then recognize the codeset name and perform +the appropriate translations to the destination codeset. +.IP " *" 4 +The archive creator includes within the archive the character mapping +table for the source codeset used to encode extended header records. +The receiver must then read the character mapping table and perform the +appropriate translations to the destination codeset. +.IP " *" 4 +The archive creator translates the extended header records in the +source codeset into a canonical form. The receiver must then perform +the appropriate translations to the destination codeset. +.P +The approach that incorporates the name of the source codeset poses the +problem of codeset name registration, and makes the archive useless to +.IR pax +archive decoders that do not recognize that codeset. +.P +Because parts of an archive may be corrupted, the standard developers +felt that including the character map of the source codeset was too +fragile. The loss of this one key component could result in making the +entire archive useless. (The difference between this and the global +extended header decision was that the latter has a +workaround\(emduplicating extended header records on unreliable +media\(embut this would be too burdensome for large character set +maps.) +.P +Both of the above approaches also put an undue burden on the +.IR pax +archive receiver to handle the cross-product of all source and +destination codesets. +.P +To simplify the translation from the source codeset to the canonical +form and from the canonical form to the destination codeset, the +standard developers decided that the internal representation should be +a stateless encoding. A stateless encoding is one where each codepoint +has the same meaning, without regard to the decoder being in a specific +state. An example of a stateful encoding would be the Japanese +Shift-JIS; an example of a stateless encoding would be the ISO/IEC\ 646:\|1991 standard +(equivalent to 7-bit ASCII). +.P +For these reasons, the standard developers decided to adopt a canonical +format for the representation of file information strings. The obvious, +well-endorsed candidate is the ISO/IEC\ 10646\(hy1:\|2000 standard (based in part on Unicode), which +can be used to represent the characters of virtually all standardized +character sets. The standard developers initially agreed upon using +UCS2 (16-bit Unicode) as the internal representation. This repertoire +of characters provides a sufficiently rich set to represent all +commonly-used codesets. +.P +However, the standard developers found that the 16-bit Unicode +representation had some problems. It forced the issue of standardizing +byte ordering. The 2-byte length of each character made the extended +header records twice as long for the case of strings coded entirely +from historical 7-bit ASCII. For these reasons, the standard developers +chose the UTF\(hy8 defined in the ISO/IEC\ 10646\(hy1:\|2000 standard. This multi-byte representation +encodes UCS2 or UCS4 characters reliably and deterministically, +eliminating the need for a canonical byte ordering. In addition, NUL +octets and other characters possibly confusing to POSIX file systems do +not appear, except to represent themselves. It was realized that +certain national codesets take up more space after the encoding, due to +their placement within the UCS range; it was felt that the usefulness +of the encoding of the names outweighs the disadvantage of size +increase for file, user, and group names. +.P +The encoding of UTF\(hy8 is as follows: +.sp +.RS 4 +.nf +\fB +UCS4 Hex Encoding UTF-8 Binary Encoding +.P +00000000-0000007F 0xxxxxxx +00000080-000007FF 110xxxxx 10xxxxxx +00000800-0000FFFF 1110xxxx 10xxxxxx 10xxxxxx +00010000-001FFFFF 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx +00200000-03FFFFFF 111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx +04000000-7FFFFFFF 1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx +.fi \fR +.P +.RE +.P +where each +.BR 'x' +represents a bit value from the character being translated. +.SS "ustar Interchange Format" +.P +The description of the +.BR ustar +format reflects numerous enhancements over pre-1988 versions of the +historical +.IR tar +utility. The goal of these changes was not only to provide the +functional enhancements desired, but also to retain compatibility +between new and old versions. This compatibility has been retained. +Archives written using the old archive format are compatible with the +new format. +.P +Implementors should be aware that the previous file format did not +include a mechanism to archive directory type files. For this reason, +the convention of using a filename ending with +<slash> +was adopted to specify a directory on the archive. +.P +The total size of the +.IR name +and +.IR prefix +fields have been set to meet the minimum requirements for +{PATH_MAX}. +If a pathname will fit within the +.IR name +field, it is recommended that the pathname be stored there without the +use of the +.IR prefix +field. Although the name field is known to be too small to contain +{PATH_MAX} +characters, the value was not changed in this version of the archive +file format to retain backwards-compatibility, and instead the prefix +was introduced. Also, because of the earlier version of the format, +there is no way to remove the restriction on the +.IR linkname +field being limited in size to just that of the +.IR name +field. +.P +The +.IR size +field is required to be meaningful in all implementation extensions, +although it could be zero. This is required so that the data blocks can +always be properly counted. +.P +It is suggested that if device special files need to be represented +that cannot be represented in the standard format, that one of the +extension types (\c +.BR A \(hy\c +.BR Z ) +be used, and that the additional information for the special file be +represented as data and be reflected in the +.IR size +field. +.P +Attempting to restore a special file type, where it is converted to +ordinary data and conflicts with an existing filename, need not be +specially detected by the utility. If run as an ordinary user, +.IR pax +should not be able to overwrite the entries in, for example, +.BR /dev +in any case (whether the file is converted to another type or not). If +run as a privileged user, it should be able to do so, and it would be +considered a bug if it did not. The same is true of ordinary data files +and similarly named special files; it is impossible to anticipate the +needs of the user (who could really intend to overwrite the file), so +the behavior should be predictable (and thus regular) and rely on the +protection system as required. +.P +The value 7 in the +.IR typeflag +field is intended to define how contiguous files can be stored in a +.BR ustar +archive. POSIX.1\(hy2008 does not require the contiguous file extension, but does +define a standard way of archiving such files so that all conforming +systems can interpret these file types in a meaningful and consistent +manner. On a system that does not support extended file types, the +.IR pax +utility should do the best it can with the file and go on to the next. +.P +The file protection modes are those conventionally used by the +.IR ls +utility. This is extended beyond the usage in the ISO\ POSIX\(hy2 standard to support the +``shared text'' or ``sticky'' bit. It is intended that the conformance +document should not document anything beyond the existence of and +support of such a mode. Further extensions are expected to these bits, +particularly with overloading the set-user-ID and set-group-ID flags. +.SS "cpio Interchange Format" +.P +The reference to appropriate privileges in the +.BR cpio +format refers to an error on standard output; the +.BR ustar +format does not make comparable statements. +.P +The model for this format was the historical System V +.IR cpio \c +.BR \(mic +data interchange format. This model documents the portable version of +the +.BR cpio +format and not the binary version. It has the flexibility to transfer +data of any type described within POSIX.1\(hy2008, yet is extensible to transfer +data types specific to extensions beyond POSIX.1\(hy2008 (for example, contiguous +files). Because it describes existing practice, there is no question of +maintaining upwards-compatibility. +.SS "cpio Header" +.P +There has been some concern that the size of the +.IR c_ino +field of the header is too small to handle those systems that have very +large +.IR inode +numbers. However, the +.IR c_ino +field in the header is used strictly as a hard-link resolution +mechanism for archives. It is not necessarily the same value as the +.IR inode +number of the file in the location from which that file is extracted. +.P +The name +.IR c_magic +is based on historical usage. +.SS "cpio Filename" +.P +For most historical implementations of the +.IR cpio +utility, +{PATH_MAX} +octets can be used to describe the pathname without the addition of +any other header fields (the NUL character would be included in this +count). +{PATH_MAX} +is the minimum value for pathname size, documented as 256 bytes. +However, an implementation may use +.IR c_namesize +to determine the exact length of the pathname. With the current +description of the +.IR <cpio.h> +header, this pathname size can be as large as a number that is +described in six octal digits. +.P +Two values are documented under the +.IR c_mode +field values to provide for extensibility for known file types: +.IP "\fB0110\ 000\fP" 10 +Reserved for contiguous files. The implementation may treat the rest of +the information for this archive like a regular file. If this file type +is undefined, the implementation may create the file as a regular +file. +.P +This provides for extensibility of the +.BR cpio +format while allowing for the ability to read old archives. Files of an +unknown type may be read as ``regular files'' on some implementations. +On a system that does not support extended file types, the +.IR pax +utility should do the best it can with the file and go on to the next. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIcp\fR\^", +.IR "\fIed\fR\^", +.IR "\fIgetopts\fR\^", +.IR "\fIls\fR\^", +.IR "\fIprintf\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.169" ", " "File Mode Bits", +.IR "Chapter 5" ", " "File Format Notation", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +.IR "\fB<cpio.h>\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIchown\fR\^(\|)", +.IR "\fIcreat\fR\^(\|)", +.IR "\fIfstatat\fR\^(\|)", +.IR "\fImkdir\fR\^(\|)", +.IR "\fImkfifo\fR\^(\|)", +.IR "\fIutime\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |