pax.html

IEEE 1003.1-2003, Single Unix Specification v3

<dd>Do not preserve file access times.</dd>

<dt><tt>e</tt></dt>

<dd>Preserve the user ID, group ID, file mode bits (see the Base Definitions volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href=
"../basedefs/xbd_chap03.html#tag_03_168">Section 3.168, File Mode Bits</a>), access time, modification time, and any other
implementation-defined file characteristics.</dd>

<dt><tt>m</tt></dt>

<dd>Do not preserve file modification times.</dd>

<dt><tt>o</tt></dt>

<dd>Preserve the user ID and group ID.</dd>

<dt><tt>p</tt></dt>

<dd>Preserve the file mode bits. Other implementation-defined file mode attributes may be preserved.</dd>
</dl>

<p>In the preceding list, &quot;preserve&quot; 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 <b>-p</b> 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 <a href="xcu_chap01.html#tag_01_07_01_04"><i>File Read, Write, and
Creation</i></a> ).</p>

<p>If neither the <tt>e</tt> nor the <tt>o</tt> specification character is specified, or the user ID and group ID are not preserved
for any reason, <i>pax</i> shall not set the S_ISUID and S_ISGID bits of the file mode.</p>

<p>If the preservation of any of these items fails for any reason, <i>pax</i> 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>

<p>If file characteristic letters in any of the <i>string</i> option-arguments are duplicated or conflict with each other, the ones
given last shall take precedence. For example, if <b>-p</b> <tt>eme</tt> is specified, file modification times are preserved.</p>
</dd>

<dt><b>-s&nbsp;</b> <i>replstr</i></dt>

<dd>Modify file or archive member names named by <i>pattern</i> or <i>file</i> operands according to the substitution expression
<i>replstr</i>, using the syntax of the <a href="../utilities/ed.html"><i>ed</i></a> utility. The concepts of &quot;address&quot; and
&quot;line&quot; are meaningless in the context of the <i>pax</i> utility, and shall not be supplied. The format shall be: 

<pre>
<tt>-s /</tt><i>old</i><tt>/</tt><i>new</i><tt>/</tt><b>[</b><tt>gp</tt><b>]</b>
</pre>

<p>where as in <a href="../utilities/ed.html"><i>ed</i></a>, <i>old</i> is a basic regular expression and <i>new</i> can contain an
ampersand, <tt>'\n'</tt> (where <i>n</i> is a digit) backreferences, or subexpression matching. The <i>old</i> string shall also be
permitted to contain &lt;newline&gt;s.</p>

<p>Any non-null character can be used as a delimiter ( <tt>'/'</tt> shown here). Multiple <b>-s</b> expressions can be specified;
the expressions shall be applied in the order specified, terminating with the first successful substitution. The optional trailing
<tt>'g'</tt> is as defined in the <a href="../utilities/ed.html"><i>ed</i></a> utility. The optional trailing <tt>'p'</tt> 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.</p>
</dd>

<dt><b>-t</b></dt>

<dd>When reading files from the file system, and if the user has the permissions required by <a href=
"../functions/utime.html"><i>utime</i>()</a> to do so, set the access time of each file read to the access time that it had before
being read by <i>pax</i>.</dd>

<dt><b>-u</b></dt>

<dd>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 <b>read</b> 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 <b>write</b> 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 <b>-a</b> 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 <b>copy</b> 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.</dd>

<dt><b>-v</b></dt>

<dd>In <b>list</b> mode, produce a verbose table of contents (see the STDOUT section). Otherwise, write archive member pathnames to
standard error (see the STDERR section).</dd>

<dt><b>-x&nbsp;</b> <i>format</i></dt>

<dd>Specify the output archive format. The <i>pax</i> utility shall support the following formats: 

<dl compact>
<dt><b>cpio</b></dt>

<dd>The <b>cpio</b> interchange format; see the EXTENDED DESCRIPTION section. The default <i>blocksize</i> for this format for
character special archive files shall be 5120. Implementations shall support all <i>blocksize</i> values less than or equal to
32256 that are multiples of 512.</dd>

<dt><b>pax</b></dt>

<dd>The <b>pax</b> interchange format; see the EXTENDED DESCRIPTION section. The default <i>blocksize</i> for this format for
character special archive files shall be 5120. Implementations shall support all <i>blocksize</i> values less than or equal to
32256 that are multiples of 512.</dd>

<dt><b>ustar</b></dt>

<dd>The <b>tar</b> interchange format; see the EXTENDED DESCRIPTION section. The default <i>blocksize</i> for this format for
character special archive files shall be 10240. Implementations shall support all <i>blocksize</i> values less than or equal to
32256 that are multiples of 512.</dd>
</dl>

<p>Implementation-defined formats shall specify a default block size as well as any other block sizes supported for character
special archive files.</p>

<p>Any attempt to append to an archive file in a format different from the existing archive format shall cause <i>pax</i> to exit
immediately with a non-zero exit status.</p>

<p>In <b>copy</b> mode, if no <b>-x</b> format is specified, <i>pax</i> shall behave as if <b>-x</b> <i>pax</i> were specified.</p>
</dd>

<dt><b>-X</b></dt>

<dd>When traversing the file hierarchy specified by a pathname, <i>pax</i> shall not descend into directories that have a different
device ID ( <i>st_dev</i>; see the System Interfaces volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href=
"../functions/stat.html"><i>stat</i>()</a>).</dd>
</dl>

<p>The options that operate on the names of files or archive members ( <b>-c</b>, <b>-i</b>, <b>-n</b>, <b>-s</b>, <b>-u</b>, and
<b>-v</b>) shall interact as follows. In <b>read</b> mode, the archive members shall be selected based on the user-specified
<i>pattern</i> operands as modified by the <b>-c</b>, <b>-n</b>, and <b>-u</b> options. Then, any <b>-s</b> and <b>-i</b> options
shall modify, in that order, the names of the selected files. The <b>-v</b> option shall write names resulting from these
modifications.</p>

<p>In <b>write</b> mode, the files shall be selected based on the user-specified pathnames as modified by the <b>-n</b> and
<b>-u</b> options. Then, any <b>-s</b> and <b>-i</b> options shall modify, in that order, the names of these selected files. The
<b>-v</b> option shall write names resulting from these modifications.</p>

<p>If both the <b>-u</b> and <b>-n</b> options are specified, <i>pax</i> shall not consider a file selected unless it is newer than
the file to which it is compared.</p>

<h5><a name="tag_04_100_04_01"></a>List Mode Format Specifications</h5>

<p>In <b>list</b> mode with the <b>-o</b> <b>listopt=</b> <i>format</i> option, the <i>format</i> argument shall be applied for
each selected file. The <i>pax</i> utility shall append a &lt;newline&gt; to the <b>listopt</b> output for each selected file. The
<i>format</i> argument shall be used as the <i>format</i> string described in the Base Definitions volume of
IEEE&nbsp;Std&nbsp;1003.1-2001, <a href="../basedefs/xbd_chap05.html">Chapter 5, File Format Notation</a>, with the exceptions 1.
through 5. defined in the EXTENDED DESCRIPTION section of <a href="../utilities/printf.html"><i>printf</i></a>, plus the following
exceptions:</p>

<dl compact>
<dt>6.</dt>

<dd>The sequence ( <i>keyword</i>) can occur before a format conversion specifier. The conversion argument is defined by the value
of <i>keyword</i>. The implementation shall support the following keywords: 

<ul>
<li>
<p>Any of the Field Name entries in <a href="#tagtcjh_15">ustar Header Block</a> and <a href="#tagtcjh_16">Octet-Oriented cpio
Archive Entry</a> . The implementation may support the <i>cpio</i> keywords without the leading <b>c_</b> in addition to the form
required by <a href="#tagtcjh_17">Values for cpio c_mode Field</a> .</p>
</li>

<li>
<p>Any keyword defined for the extended header in <a href="#tag_04_100_13_03">pax Extended Header</a> .</p>
</li>

<li>
<p>Any keyword provided as an implementation-defined extension within the extended header defined in <a href=
"#tag_04_100_13_03">pax Extended Header</a> .</p>
</li>
</ul>

<p>For example, the sequence <tt>"%(charset)s"</tt> is the string value of the name of the character set in the extended
header.</p>

<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>

<p>All keyword values used as conversion arguments shall be translated from the UTF-8 encoding to the character set appropriate for
the local file system, user database, and so on, as applicable.</p>
</dd>

<dt>7.</dt>

<dd>An additional conversion specifier character, <tt>T</tt> , shall be used to specify time formats. The <tt>T</tt> conversion
specifier character can be preceded by the sequence ( <i>keyword=</i> <i>subformat</i>), where <i>subformat</i> is a date format as
defined by <a href="../utilities/date.html"><i>date</i></a> operands. The default <i>keyword</i> shall be <b>mtime</b> and the
default subformat shall be: 

<pre>
<tt>%b %e %H:%M %Y
</tt>
</pre>
</dd>

<dt>8.</dt>

<dd>An additional conversion specifier character, <tt>M</tt> , shall be used to specify the file mode string as defined in <a href=
"../utilities/ls.html"><i>ls</i></a> Standard Output. If ( <i>keyword</i>) is omitted, the <b>mode</b> keyword shall be used. For
example, <tt>%.1M</tt> writes the single character corresponding to the &lt;<i>entry&nbsp;type</i>&gt; field of the <a href=
"../utilities/ls.html"><i>ls</i></a> <b>-l</b> command.</dd>

<dt>9.</dt>

<dd>An additional conversion specifier character, <tt>D</tt> , shall be used to specify the device for block or special files, if
applicable, in an implementation-defined format. If not applicable, and ( <i>keyword</i>) is specified, then this conversion shall
be equivalent to <tt>%(</tt><i>keyword</i><tt>)u</tt>. If not applicable, and ( <i>keyword</i>) is omitted, then this conversion
shall be equivalent to &lt;space&gt;.</dd>

<dt>10.</dt>

<dd>An additional conversion specifier character, <tt>F</tt> , shall be used to specify a pathname. The <tt>F</tt> conversion
character can be preceded by a sequence of comma-separated keywords: 

<pre>
<tt>(</tt><i>keyword</i><b>[</b><tt>,</tt><i>keyword</i><b>]</b> <tt>... )
</tt>
</pre>

<p>The values for all the keywords that are non-null shall be concatenated together, each separated by a <tt>'/'</tt> . The default
shall be ( <b>path</b>) if the keyword <b>path</b> is defined; otherwise, the default shall be ( <b>prefix</b>, <b>name</b>).</p>
</dd>

<dt>11.</dt>

<dd>An additional conversion specifier character, <tt>L</tt> , shall be used to specify a symbolic line expansion. If the current
file is a symbolic link, then <tt>%L</tt> shall expand to: 

<pre>
<tt>"%s -&gt; %s", &lt;</tt><i>value of keyword</i><tt>&gt;, &lt;</tt><i>contents of link</i><tt>&gt;
</tt>
</pre>

<p>Otherwise, the <tt>%L</tt> conversion specification shall be the equivalent of <tt>%F</tt> .</p>
</dd>
</dl>
</blockquote>

<h4><a name="tag_04_100_05"></a>OPERANDS</h4>

<blockquote>
<p>The following operands shall be supported:</p>

<dl compact>
<dt><i>directory</i></dt>

<dd>The destination directory pathname for <b>copy</b> mode.</dd>

<dt><i>file</i></dt>

<dd>A pathname of a file to be copied or archived.</dd>

<dt><i>pattern</i></dt>

<dd>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 <a href="xcu_chap02.html#tag_02_13"><i>Pattern Matching Notation</i></a> , including the filename
expansion rules in <a href="xcu_chap02.html#tag_02_13_03"><i>Patterns Used for Filename Expansion</i></a> . The default, if no
<i>pattern</i> is specified, is to select all members in the archive.</dd>
</dl>
</blockquote>

<h4><a name="tag_04_100_06"></a>STDIN</h4>

<blockquote>
<p>In <b>write</b> mode, the standard input shall be used only if no <i>file</i> operands are specified. It shall be a text file
containing a list of pathnames, one per line, without leading or trailing &lt;blank&gt;s.</p>

<p>In <b>list</b> and <b>read</b> modes, if <b>-f</b> is not specified, the standard input shall be an archive file.</p>

<p>Otherwise, the standard input shall not be used.</p>
</blockquote>

<h4><a name="tag_04_100_07"></a>INPUT FILES</h4>

<blockquote>
<p>The input file named by the <i>archive</i> 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>

<p>The file <b>/dev/tty</b> shall be used to write prompts and read responses.</p>
</blockquote>

<h4><a name="tag_04_100_08"></a>ENVIRONMENT VARIABLES</h4>