pax.html

IEEE 1003.1-2003, Single Unix Specification v3

<blockquote>
<p>The following environment variables shall affect the execution of <i>pax</i>:</p>

<dl compact>
<dt><i>LANG</i></dt>

<dd>Provide a default value for the internationalization variables that are unset or null. (See the Base Definitions volume of
IEEE&nbsp;Std&nbsp;1003.1-2001, <a href="../basedefs/xbd_chap08.html#tag_08_02">Section 8.2, Internationalization Variables</a> for
the precedence of internationalization variables used to determine the values of locale categories.)</dd>

<dt><i>LC_ALL</i></dt>

<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd>

<dt><i>LC_COLLATE</i></dt>

<dd><br>
Determine the locale for the behavior of ranges, equivalence classes, and multi-character collating elements used in the pattern
matching expressions for the <i>pattern</i> operand, the basic regular expression for the <b>-s</b> option, and the extended
regular expression defined for the <b>yesexpr</b> locale keyword in the <i>LC_MESSAGES</i> category.</dd>

<dt><i>LC_CTYPE</i></dt>

<dd>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 <b>yesexpr</b> locale keyword in the <i>LC_MESSAGES</i> category, and pattern matching.</dd>

<dt><i>LC_MESSAGES</i></dt>

<dd>Determine the locale for the processing of affirmative responses that should be used to affect the format and contents of
diagnostic messages written to standard error.</dd>

<dt><i>LC_TIME</i></dt>

<dd>Determine the format and contents of date and time strings when the <b>-v</b> option is specified.</dd>

<dt><i>NLSPATH</i></dt>

<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
Determine the location of message catalogs for the processing of <i>LC_MESSAGES .</i> <img src="../images/opt-end.gif" alt=
"[Option End]" border="0"></dd>

<dt><i>TMPDIR</i></dt>

<dd>Determine the pathname that provides part of the default global extended header record file, as described for the <b>-o</b>
<b>globexthdr=</b> keyword in the OPTIONS section.</dd>

<dt><i>TZ</i></dt>

<dd>Determine the timezone used to calculate date and time strings when the <b>-v</b> option is specified. If <i>TZ</i> is unset or
null, an unspecified default timezone shall be used.</dd>
</dl>
</blockquote>

<h4><a name="tag_04_100_09"></a>ASYNCHRONOUS EVENTS</h4>

<blockquote>
<p>Default.</p>
</blockquote>

<h4><a name="tag_04_100_10"></a>STDOUT</h4>

<blockquote>
<p>In <b>write</b> mode, if <b>-f</b> 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 <b>-x</b> <i>format</i>).</p>

<p>In <b>list</b> mode, when the <b>-o</b> <b>listopt</b>= <i>format</i> has been specified, the selected archive members shall be
written to standard output using the format described under <a href="#tag_04_100_04_01">List Mode Format Specifications</a> . In
<b>list</b> mode without the <b>-o</b> <b>listopt</b>= <i>format</i> option, the table of contents of the selected archive members
shall be written to standard output using the following format:</p>

<pre>
<tt>"%s\n", &lt;</tt><i>pathname</i><tt>&gt;
</tt>
</pre>

<p>If the <b>-v</b> option is specified in <b>list</b> mode, the table of contents of the selected archive members shall be written
to standard output using the following formats.</p>

<p>For pathnames representing hard links to previous members of the archive:</p>

<pre>
<tt>"%s<img src="../images/delta.gif" border="0">==<img src="../images/delta.gif" border=
"0">%s\n", &lt;</tt><i>ls</i> <tt>-l</tt> <i>listing</i><tt>&gt;, &lt;</tt><i>linkname</i><tt>&gt;
</tt>
</pre>

<p>For all other pathnames:</p>

<pre>
<tt>"%s\n", &lt;</tt><i>ls</i> <tt>-l</tt> <i>listing</i><tt>&gt;
</tt>
</pre>

<p>where &lt;<i>ls&nbsp;</i> -l&nbsp;<i>listing</i>&gt; shall be the format specified by the <a href=
"../utilities/ls.html"><i>ls</i></a> utility with the <b>-l</b> 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 &lt;blank&gt;-separated fields shall be written.</p>

<p>In <b>list</b> mode, standard output shall not be buffered more than a line at a time.</p>
</blockquote>

<h4><a name="tag_04_100_11"></a>STDERR</h4>

<blockquote>
<p>If <b>-v</b> is specified in <b>read</b>, <b>write</b>, or <b>copy</b> modes, <i>pax</i> shall write the pathnames it processes
to the standard error output using the following format:</p>

<pre>
<tt>"%s\n", &lt;</tt><i>pathname</i><tt>&gt;
</tt>
</pre>

<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 &lt;newline&gt;, which shall not be buffered, is written when the file has been read or written.</p>

<p>If the <b>-s</b> option is specified, and the replacement string has a trailing <tt>'p'</tt> , substitutions shall be written to
standard error in the following format:</p>

<pre>
<tt>"%s<img src="../images/delta.gif" border="0">&gt;&gt;<img src="../images/delta.gif" border=
"0">%s\n", &lt;</tt><i>original pathname</i><tt>&gt;, &lt;</tt><i>new pathname</i><tt>&gt;
</tt>
</pre>

<p>In all operating modes of <i>pax</i>, 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>

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

<p>When <i>pax</i> is in <b>read</b> mode or <b>list</b> mode, using the <b>-x</b> <b>pax</b> archive format, 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 write a diagnostic message to standard error, shall process
the file as described for the <b>-o</b> <b>invalid=</b> option, and then shall process the next file in the archive.</p>
</blockquote>

<h4><a name="tag_04_100_12"></a>OUTPUT FILES</h4>

<blockquote>
<p>In <b>read</b> mode, the extracted output files shall be of the archived file type. In <b>copy</b> 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 ( <b>-p</b>), modification time ( <b>-u</b>), and invalid-value ( <b>-o</b> <b>invalid</b>=) tests allow
it.</p>

<p>In <b>write</b> mode, the output file named by the <b>-f</b> option-argument shall be a file formatted according to one of the
specifications in the EXTENDED DESCRIPTION section, or some other implementation-defined format.</p>
</blockquote>

<h4><a name="tag_04_100_13"></a>EXTENDED DESCRIPTION</h4>

<blockquote>
<h5><a name="tag_04_100_13_01"></a>pax Interchange Format</h5>

<p>A <i>pax</i> archive tape or file produced in the <b>-x</b> <b>pax</b> format shall contain a series of blocks. The physical
layout of the archive shall be identical to the <b>ustar</b> format described in <a href="#tag_04_100_13_06">ustar Interchange
Format</a> . Each file archived shall be represented by the following sequence:</p>

<ul>
<li>
<p>An optional header block with extended header records. This header block is of the form described in <a href=
"#tag_04_100_13_02">pax Header Block</a> , with a <i>typeflag</i> value of <b>x</b> or <b>g</b>. The extended header records,
described in <a href="#tag_04_100_13_03">pax Extended Header</a> , shall be included as the data for this header block.</p>
</li>

<li>
<p>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.</p>
</li>

<li>
<p>Zero or more blocks that contain the contents of the file.</p>
</li>
</ul>

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

<p>A schematic of an example archive with global extended header records and two actual files is shown in <a href="#tagfcjh_1">pax
Format Archive Example</a> . In the example, the second file in the archive has no extended header preceding it, presumably because
it has no need for extended attributes.</p>

<dl compact>
<dt></dt>

<dd><img src=".././Figures/xcu-pax.gif"></dd>
</dl>

<center><b><a name="tagfcjh_1"></a> Figure: pax Format Archive Example</b></center>

<h5><a name="tag_04_100_13_02"></a>pax Header Block</h5>

<p>The <b>pax</b> header block shall be identical to the <b>ustar</b> header block described in <a href="#tag_04_100_13_06">ustar
Interchange Format</a> , except that two additional <i>typeflag</i> values are defined:</p>

<dl compact>
<dt><tt>x</tt></dt>

<dd>Represents extended header records for the following file in the archive (which shall have its own <b>ustar</b> header block).
The format of these extended header records shall be as described in <a href="#tag_04_100_13_03">pax Extended Header</a> .</dd>

<dt><tt>g</tt></dt>

<dd>Represents global extended header records for the following files in the archive. The format of these extended header records
shall be as described in <a href="#tag_04_100_13_03">pax Extended Header</a> . 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 <i>typeflag</i> <b>g</b> global headers should not be used with interchange media
that could suffer partial data loss in transporting the archive.</dd>
</dl>

<p>For both of these types, the <i>size</i> 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 <i>pax</i> utility. However, if this archive is read by a <i>pax</i>
utility conforming to the ISO&nbsp;POSIX-2: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>

<p>A further difference from the <b>ustar</b> header block is that data blocks for files of <i>typeflag</i> 1 (the digit one) (hard
link) may be included, which means that the size field may be greater than zero. Archives created by <i>pax</i> <b>-o</b>
<b>linkdata</b> shall include these data blocks with the hard links.</p>

<h5><a name="tag_04_100_13_03"></a>pax Extended Header</h5>

<p>A <b>pax</b> extended header contains values that are inappropriate for the <b>ustar</b> header block because of limitations in
that format: fields requiring a character encoding other than that described in the ISO/IEC&nbsp;646:1991 standard, fields
representing file attributes not described in the <b>ustar</b> header, and fields whose format or length do not fit the
requirements of the <b>ustar</b> header. The values in an extended header add attributes to the following file (or files; see the
description of the <i>typeflag</i> <b>g</b> header block) or override values in the following header block(s), as indicated in the
following list of keywords.</p>

<p>An extended header shall consist of one or more records, each constructed as follows:</p>

<pre>
<tt>"%d %s=%s\n", &lt;</tt><i>length</i><tt>&gt;, &lt;</tt><i>keyword</i><tt>&gt;, &lt;</tt><i>value</i><tt>&gt;
</tt>
</pre>

<p>The extended header records shall be encoded according to the ISO/IEC&nbsp;10646-1:2000 standard (UTF-8). The
&lt;<i>length</i>&gt; field, &lt;blank&gt;, equals sign, and &lt;newline&gt; shown shall be limited to the portable character set,
as encoded in UTF-8. The &lt;<i>keyword</i>&gt; and &lt;<i>value</i>&gt; fields can be any UTF-8 characters. The
&lt;<i>length</i>&gt; field shall be the decimal length of the extended header record in octets, including the trailing
&lt;newline&gt;.</p>

<p>The &lt;<i>keyword</i>&gt; 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 &quot;file(s)&quot; or &quot;block(s)&quot; is used to acknowledge
that a keyword affects the following single file after a <i>typeflag</i> <b>x</b> extended header, but possibly multiple files
after <i>typeflag</i> <b>g</b>. Any requirements in the list for <i>pax</i> to include a record when in <b>write</b> or <b>copy</b>
mode shall apply only when such a record has not already been provided through the use of the <b>-o</b> option. When used in
<b>copy</b> mode, <i>pax</i> shall behave as if an archive had been created with applicable extended header records and then
extracted.)</p>

<dl compact>
<dt><b>atime</b></dt>

<dd>The file access time for the following file(s), equivalent to the value of the <i>st_atime</i> member of the <b>stat</b>
structure for a file, as described by the <a href="../functions/stat.html"><i>stat</i>()</a> function. The access time shall be
restored if the process has the appropriate privilege required to do so. The format of the &lt;<i>value</i>&gt; shall be as
described in <a href="#tag_04_100_13_05">pax Extended Header File Times</a> .</dd>

<dt><b>charset</b></dt>

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

<center>
<table border="1" cellpadding="3" align="center">
<tr valign="top">
<th align="center">
<p class="tent"><b>&lt;value&gt;</b></p>
</th>
<th align="center">
<p class="tent"><b>Formal Standard</b></p>
</th>
</tr>