pax.html

IEEE 1003.1-2003, Single Unix Specification v3

<dd><br>
(Applicable only to the <b>-x</b> <b>pax</b> format.) This keyword allows user control over the name that is written into the
<b>ustar</b> header blocks for the extended header produced under the circumstances described in <a href="#tag_04_100_13_02">pax
Header Block</a> . The name shall be the contents of <i>string</i>, after the following character substitutions have been made: 

<center>
<table border="1" cellpadding="3" align="center">
<tr valign="top">
<th align="center">
<p class="tent"><b><i>string</i></b></p>
</th>
<th align="center">
<p class="tent"><b>&nbsp;</b></p>
</th>
</tr>

<tr valign="top">
<th align="center">
<p class="tent"><b>Includes:</b></p>
</th>
<th align="center">
<p class="tent"><b>Replaced By:</b></p>
</th>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">%d</p>
</td>
<td align="left">
<p class="tent">The directory name of the file, equivalent to the result of the <a href=
"../utilities/dirname.html"><i>dirname</i></a> utility on the translated pathname.</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">%f</p>
</td>
<td align="left">
<p class="tent">The filename of the file, equivalent to the result of the <a href="../utilities/basename.html"><i>basename</i></a>
utility on the translated pathname.</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">%p</p>
</td>
<td align="left">
<p class="tent">The process ID of the <i>pax</i> process.</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">%%</p>
</td>
<td align="left">
<p class="tent">A <tt>'%'</tt> character.</p>
</td>
</tr>
</table>
</center>

<p>Any other <tt>'%'</tt> characters in <i>string</i> produce undefined results.</p>

<p>If no <b>-o</b> <b>exthdr.name=</b> <i>string</i> is specified, <i>pax</i> shall use the following default value:</p>

<pre>
<tt>%d/PaxHeaders.%p/%f
</tt>
</pre>
</dd>

<dt><b>globexthdr.name</b>=<i>string</i></dt>

<dd><br>
(Applicable only to the <b>-x</b> <b>pax</b> format.) When used in <b>write</b> or <b>copy</b> mode with the appropriate options,
<i>pax</i> shall create global extended header records with <b>ustar</b> header blocks that will be treated as regular files by
previous versions of <i>pax</i>. This keyword allows user control over the name that is written into the <b>ustar</b> header blocks
for global extended header records. The name shall be the contents of string, after the following character substitutions have been
made: 

<center>
<table border="1" cellpadding="3" align="center">
<tr valign="top">
<th align="center">
<p class="tent"><b><i>string</i></b></p>
</th>
<th align="center">
<p class="tent"><b>&nbsp;</b></p>
</th>
</tr>

<tr valign="top">
<th align="center">
<p class="tent"><b>Includes:</b></p>
</th>
<th align="center">
<p class="tent"><b>Replaced By:</b></p>
</th>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">%n</p>
</td>
<td align="left">
<p class="tent">An integer that represents the sequence number of the global extended header record in the archive, starting at
1.</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">%p</p>
</td>
<td align="left">
<p class="tent">The process ID of the <i>pax</i> process.</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">%%</p>
</td>
<td align="left">
<p class="tent">A <tt>'%'</tt> character.</p>
</td>
</tr>
</table>
</center>

<p>Any other <tt>'%'</tt> characters in <i>string</i> produce undefined results.</p>

<p>If no <b>-o</b> <b>globexthdr.name=</b> <i>string</i> is specified, <i>pax</i> shall use the following default value:</p>

<pre>
<tt>$TMPDIR/GlobalHead.%p.%n
</tt>
</pre>

<p>where $ <i>TMPDIR</i> represents the value of the <i>TMPDIR</i> environment variable. If <i>TMPDIR</i> is not set, <i>pax</i>
shall use <b>/tmp</b>.</p>
</dd>

<dt><b>invalid</b>=<i>action</i></dt>

<dd><br>
(Applicable only to the <b>-x</b> <b>pax</b> format.) This keyword allows user control over the action <i>pax</i> takes upon
encountering values in an extended header record that, in <b>read</b> or <b>copy</b> mode, are invalid in the destination hierarchy
or, in <b>list</b> mode, cannot be written in the codeset and current locale of the implementation. The following are invalid
values that shall be recognized by <i>pax</i>: 

<ul>
<li>
<p>In <b>read</b> or <b>copy</b> mode, a filename or link name that contains character encodings invalid in the destination
hierarchy. (For example, the name may contain embedded NULs.)</p>
</li>

<li>
<p>In <b>read</b> or <b>copy</b> 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).</p>
</li>

<li>
<p>In <b>list</b> 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>
</li>
</ul>

<p>The following mutually-exclusive values of the <i>action</i> argument are supported:</p>

<dl compact>
<dt><b>bypass</b></dt>

<dd>In <b>read</b> or <b>copy</b> mode, <i>pax</i> shall bypass the file, causing no change to the destination hierarchy. In
<b>list</b> mode, <i>pax</i> shall write all requested valid values for the file, but its method for writing invalid values is
unspecified.</dd>

<dt><b>rename</b></dt>

<dd>In <b>read</b> or <b>copy</b> mode, <i>pax</i> shall act as if the <b>-i</b> option were in effect for each file with invalid
filename or link name values, allowing the user to provide a replacement name interactively. In <b>list</b> mode, <i>pax</i> shall
behave identically to the <b>bypass</b> action.</dd>

<dt><b>UTF-8</b></dt>

<dd>When used in <b>read</b>, <b>copy</b>, or <b>list</b> mode and a filename, link name, owner name, or any other field in an
extended header record cannot be translated from the <b>pax</b> UTF-8 codeset format to the codeset and current locale of the
implementation, <i>pax</i> shall use the actual UTF-8 encoding for the name.</dd>

<dt><b>write</b></dt>

<dd>In <b>read</b> or <b>copy</b> mode, <i>pax</i> shall write the file, translating or truncating the name, regardless of whether
this may overwrite an existing file with a valid name. In <b>list</b> mode, <i>pax</i> shall behave identically to the
<b>bypass</b> action.</dd>
</dl>

<p>If no <b>-o</b> <b>invalid=</b> option is specified, <i>pax</i> shall act as if <b>-o</b> <b>invalid=</b> <b>bypass</b> were
specified. Any overwriting of existing files that may be allowed by the <b>-o</b> <b>invalid=</b> actions shall be subject to
permission ( <b>-p</b>) and modification time ( <b>-u</b>) restrictions, and shall be suppressed if the <b>-k</b> option is also
specified.</p>
</dd>

<dt><b>linkdata</b></dt>

<dd><br>
(Applicable only to the <b>-x</b> <b>pax</b> format.) In <b>write</b> mode, <i>pax</i> 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.</dd>

<dt><b>listopt</b>=<i>format</i></dt>

<dd><br>
This keyword specifies the output format of the table of contents produced when the <b>-v</b> option is specified in <b>list</b>
mode. See <a href="#tag_04_100_04_01">List Mode Format Specifications</a> . To avoid ambiguity, the <b>listopt=</b> <i>format</i>
shall be the only or final <b>keyword=</b> <i>value</i> pair in a <b>-o</b> option-argument; all characters in the remainder of the
option-argument shall be considered part of the format string. When multiple <b>-o</b> <b>listopt=</b> <i>format</i> options are
specified, the format strings shall be considered a single, concatenated string, evaluated in command line order.</dd>

<dt><b>times</b></dt>

<dd><br>
(Applicable only to the <b>-x</b> <i>pax</i> format.) When used in <b>write</b> or <b>copy</b> mode, <i>pax</i> shall include
<b>atime</b>, <b>ctime</b>, and <b>mtime</b> extended header records for each file. See <a href="#tag_04_100_13_05">pax Extended
Header File Times</a> .</dd>
</dl>

<p>In addition to these keywords, if the <b>-x</b> <i>pax</i> format is specified, any of the keywords and values defined in <a
href="#tag_04_100_13_03">pax Extended Header</a> , including implementation extensions, can be used in <b>-o</b> option-arguments,
in either of two modes:</p>

<dl compact>
<dt><b>keyword</b>=<i>value</i></dt>

<dd><br>
When used in <b>write</b> or <b>copy</b> mode, these keyword/value pairs shall be included at the beginning of the archive as
<b>typeflag</b> <b>g</b> global extended header records. When used in <b>read</b> or <b>list</b> mode, these keyword/value pairs
shall act as if they had been at the beginning of the archive as <b>typeflag</b> <b>g</b> global extended header records.</dd>

<dt><b>keyword</b>:=<i>value</i></dt>

<dd><br>
When used in <b>write</b> or <b>copy</b> mode, these keyword/value pairs shall be included as records at the beginning of a
<b>typeflag</b> <b>x</b> extended header for each file. (This shall be equivalent to the equal-sign form except that it creates no
<b>typeflag</b> <b>g</b> global extended header records.) When used in <b>read</b> or <b>list</b> 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: 

<pre>
<tt>pax -r -o "
gname:=mygroup,
" &lt;archive
</tt>
</pre>

<p>the group name will be forced to a new value for all files read from the archive.</p>
</dd>
</dl>

<p>The precedence of <b>-o</b> keywords over various fields in the archive is described in <a href="#tag_04_100_13_04">pax Extended
Header Keyword Precedence</a> .</p>
</dd>

<dt><b>-p&nbsp;</b> <i>string</i></dt>

<dd>Specify one or more file characteristic options (privileges). The <i>string</i> option-argument shall be a string specifying
file characteristics to be retained or discarded on extraction. The string shall consist of the specification characters <tt>a</tt>
, <tt>e</tt> , <tt>m</tt> , <tt>o</tt> , and <tt>p</tt> . Other implementation-defined characters can be included. Multiple
characteristics can be concatenated within the same string and multiple <b>-p</b> options can be specified. The meaning of the
specification characters are as follows: 

<dl compact>
<dt><tt>a</tt></dt>