3266 lines
144 KiB
HTML
3266 lines
144 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title>pax</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="pax"></a> <a name="tag_04_100"></a><!-- pax -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_04_100_01"></a>NAME</h4>
|
|
|
|
<blockquote>pax - portable archive interchange</blockquote>
|
|
|
|
<h4><a name="tag_04_100_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<p><code><tt>pax</tt> <b>[</b><tt>-cdnv</tt><b>][</b><tt>-H|-L</tt><b>][</b><tt>-f</tt> <i>archive</i><b>][</b><tt>-s</tt>
|
|
<i>replstr</i><b>]</b><tt>...</tt><b>[</b><i>pattern</i><tt>...</tt><b>]</b><tt><br>
|
|
<br>
|
|
pax -r</tt><b>[</b><tt>-cdiknuv</tt><b>][</b><tt>-H|-L</tt><b>][</b><tt>-f</tt> <i>archive</i><b>][</b><tt>-o</tt>
|
|
<i>options</i><b>]</b><tt>...</tt><b>[</b><tt>-p</tt> <i>string</i><b>]</b><tt>...<br>
|
|
</tt> <b>[</b><tt>-s</tt>
|
|
<i>replstr</i><b>]</b><tt>...</tt><b>[</b><i>pattern</i><tt>...</tt><b>]</b><tt><br>
|
|
<br>
|
|
pax -w</tt><b>[</b><tt>-dituvX</tt><b>][</b><tt>-H|-L</tt><b>][</b><tt>-b</tt>
|
|
<i>blocksize</i><b>][[</b><tt>-a</tt><b>][</b><tt>-f</tt> <i>archive</i><b>][</b><tt>-o</tt> <i>options</i><b>]</b><tt>...<br>
|
|
</tt> <b>[</b><tt>-s</tt> <i>replstr</i><b>]</b><tt>...</tt><b>[</b><tt>-x</tt>
|
|
<i>format</i><b>][</b><i>file</i><tt>...</tt><b>]</b><tt><br>
|
|
<br>
|
|
pax -r -w</tt><b>[</b><tt>-diklntuvX</tt><b>][</b><tt>-H|-L</tt><b>][</b><tt>-p</tt>
|
|
<i>string</i><b>]</b><tt>...</tt><b>[</b><tt>-s</tt> <i>replstr</i><b>]</b><tt>...<br>
|
|
</tt> <b>[</b><i>file</i><tt>...</tt><b>]</b> <i>directory</i><tt><br>
|
|
</tt></code></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_100_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>pax</i> 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 <b>-x</b> <i>format</i> option.</p>
|
|
|
|
<p>The action to be taken depends on the presence of the <b>-r</b> and <b>-w</b> options. The four combinations of <b>-r</b> and
|
|
<b>-w</b> are referred to as the four modes of operation: <b>list</b>, <b>read</b>, <b>write</b>, and <b>copy</b> modes,
|
|
corresponding respectively to the four forms shown in the SYNOPSIS section.</p>
|
|
|
|
<dl compact>
|
|
<dt><b>list</b></dt>
|
|
|
|
<dd>In <b>list</b> mode (when neither <b>-r</b> nor <b>-w</b> are specified), <i>pax</i> 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.</dd>
|
|
|
|
<dt><b>read</b></dt>
|
|
|
|
<dd>In <b>read</b> mode (when <b>-r</b> is specified, but <b>-w</b> is not), <i>pax</i> 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 <i>pax</i> was invoked as the current working directory.
|
|
|
|
<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>
|
|
|
|
<p>The ownership, access, and modification times, and file mode of the restored files are discussed under the <b>-p</b> option.</p>
|
|
</dd>
|
|
|
|
<dt><b>write</b></dt>
|
|
|
|
<dd>In <b>write</b> mode (when <b>-w</b> is specified, but <b>-r</b> is not), <i>pax</i> shall write the contents of the
|
|
<i>file</i> operands to the standard output in an archive format. If no <i>file</i> 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.</dd>
|
|
|
|
<dt><b>copy</b></dt>
|
|
|
|
<dd>In <b>copy</b> mode (when both <b>-r</b> and <b>-w</b> are specified), <i>pax</i> shall copy the <i>file</i> operands to the
|
|
destination directory.
|
|
|
|
<p>If no <i>file</i> 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>
|
|
|
|
<p>The effect of the <b>copy</b> shall be as if the copied files were written to an 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 IEEE Std 1003.1-2001, the results are implementation-defined; otherwise, it shall be an error
|
|
for the file named by the <i>directory</i> operand not to exist, not be writable by the user, or not be a file of type
|
|
directory.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p>In <b>read</b> or <b>copy</b> modes, if intermediate directories are necessary to extract an archive member, <i>pax</i> shall
|
|
perform actions equivalent to the <a href="../functions/mkdir.html"><i>mkdir</i>()</a> function defined in the System Interfaces
|
|
volume of IEEE Std 1003.1-2001, called with the following arguments:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>The intermediate directory used as the <i>path</i> argument</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The value of the bitwise-inclusive OR of S_IRWXU, S_IRWXG, and S_IRWXO as the <i>mode</i> argument</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>If any specified <i>pattern</i> or <i>file</i> operands are not matched by at least one file or archive member, <i>pax</i> shall
|
|
write a diagnostic message to standard error for each one that did not match and exit with a non-zero exit status.</p>
|
|
|
|
<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>
|
|
|
|
<p>A single archive can span multiple files. The <i>pax</i> utility shall determine, in an implementation-defined manner, what file
|
|
to read or write as the next file.</p>
|
|
|
|
<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 <i>pax</i> 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, <i>pax</i> 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, <i>pax</i> shall write a diagnostic message to standard error and shall
|
|
terminate.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_100_04"></a>OPTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>pax</i> utility shall conform to the Base Definitions volume of IEEE Std 1003.1-2001, <a href=
|
|
"../basedefs/xbd_chap12.html#tag_12_02">Section 12.2, Utility Syntax Guidelines</a>, except that the order of presentation of the
|
|
<b>-o</b>, <b>-p</b>, and <b>-s</b> options is significant.</p>
|
|
|
|
<p>The following options shall be supported:</p>
|
|
|
|
<dl compact>
|
|
<dt><b>-r</b></dt>
|
|
|
|
<dd>Read an archive file from standard input.</dd>
|
|
|
|
<dt><b>-w</b></dt>
|
|
|
|
<dd>Write files to the standard output in the specified archive format.</dd>
|
|
|
|
<dt><b>-a</b></dt>
|
|
|
|
<dd>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 IEEE Std 1003.1-2001 may impose restrictions on appending.</dd>
|
|
|
|
<dt><b>-b </b> <i>blocksize</i></dt>
|
|
|
|
<dd>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
|
|
<i>blocksize</i> value larger than 32256. Default blocking when creating archives depends on the archive format. (See the <b>-x</b>
|
|
option below.)</dd>
|
|
|
|
<dt><b>-c</b></dt>
|
|
|
|
<dd>Match all file or archive members except those specified by the <i>pattern</i> or <i>file</i> operands.</dd>
|
|
|
|
<dt><b>-d</b></dt>
|
|
|
|
<dd>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.</dd>
|
|
|
|
<dt><b>-f </b> <i>archive</i></dt>
|
|
|
|
<dd>Specify the pathname of the input or output archive, overriding the default standard input (in <b>list</b> or <b>read</b>
|
|
modes) or standard output ( <b>write</b> mode).</dd>
|
|
|
|
<dt><b>-H</b></dt>
|
|
|
|
<dd>If a symbolic link referencing a file of type directory is specified on the command line, <i>pax</i> 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 <i>pax</i> can normally archive is specified on the command line,
|
|
then <i>pax</i> shall archive the file referenced by the link, using the name of the link. The default behavior shall be to archive
|
|
the symbolic link itself.</dd>
|
|
|
|
<dt><b>-i</b></dt>
|
|
|
|
<dd>Interactively rename files or archive members. For each archive member matching a <i>pattern</i> operand or file matching a
|
|
<i>file</i> operand, a prompt shall be written to the file <b>/dev/tty</b>. 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 <b>/dev/tty</b>. 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 <i>pax</i> utility shall
|
|
immediately exit with a non-zero exit status if end-of-file is encountered when reading a response or if <b>/dev/tty</b> cannot be
|
|
opened for reading and writing.
|
|
|
|
<p>The results of extracting a hard link to a file that has been renamed during extraction are unspecified.</p>
|
|
</dd>
|
|
|
|
<dt><b>-k</b></dt>
|
|
|
|
<dd>Prevent the overwriting of existing files.</dd>
|
|
|
|
<dt><b>-l</b></dt>
|
|
|
|
<dd>(The letter ell.) In <b>copy</b> mode, hard links shall be made between the source and destination file hierarchies whenever
|
|
possible. If specified in conjunction with <b>-H</b> or <b>-L</b>, 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 <b>-H</b> nor
|
|
<b>-L</b> 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.</dd>
|
|
|
|
<dt><b>-L</b></dt>
|
|
|
|
<dd>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, <i>pax</i> 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 <i>pax</i> can
|
|
normally archive is specified on the command line or encountered during the traversal of a file hierarchy, <i>pax</i> shall archive
|
|
the file referenced by the link, using the name of the link. The default behavior shall be to archive the symbolic link
|
|
itself.</dd>
|
|
|
|
<dt><b>-n</b></dt>
|
|
|
|
<dd>Select the first archive member that matches each <i>pattern</i> 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).</dd>
|
|
|
|
<dt><b>-o </b> <i>options</i></dt>
|
|
|
|
<dd>Provide information to the implementation to modify the algorithm for extracting or writing files. The value of <i>options</i>
|
|
shall consist of one or more comma-separated keywords of the form:
|
|
|
|
<pre>
|
|
<i>keyword</i><b>[[</b><tt>:</tt><b>]</b><tt>=</tt><i>value</i><b>][</b><tt>,</tt><i>keyword</i><b>[[</b><tt>:</tt><b>]</b><tt>=</tt><i>value</i><b>]</b><tt>, ...</tt><b>]</b>
|
|
</pre>
|
|
|
|
<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>
|
|
|
|
<p>Keywords in the <i>options</i> argument shall be a string that would be a valid portable filename as described in the Base
|
|
Definitions volume of IEEE Std 1003.1-2001, <a href="../basedefs/xbd_chap03.html#tag_03_276">Section 3.276, Portable
|
|
Filename Character Set</a>. <basefont size="2"></p>
|
|
|
|
<dl>
|
|
<dt><b>Note:</b></dt>
|
|
|
|
<dd>Keywords are not expected to be filenames, merely to follow the same character composition rules as portable filenames.</dd>
|
|
</dl>
|
|
|
|
<basefont size="3">
|
|
|
|
<p>Keywords can be preceded with white space. The <i>value</i> field shall consist of zero or more characters; within <i>value</i>,
|
|
the application shall precede any literal comma with a backslash, which shall be ignored, but preserves the comma as part of
|
|
<i>value</i>. A comma as the final character, or a comma followed solely by white space as the final characters, in <i>options</i>
|
|
shall be ignored. Multiple <b>-o</b> options can be specified; if keywords given to these multiple <b>-o</b> 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 <i>options</i> shall be supported for the file formats as indicated:</p>
|
|
|
|
<dl compact>
|
|
<dt><b>delete</b>=<i>pattern</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, <i>pax</i> shall omit from
|
|
extended header records that it produces any keywords matching the string pattern. When used in <b>read</b> or <b>list</b> mode,
|
|
<i>pax</i> 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 <a href="xcu_chap02.html#tag_02_13_01"><i>Patterns Matching a Single
|
|
Character</i></a> and <a href="xcu_chap02.html#tag_02_13_02"><i>Patterns Matching Multiple Characters</i></a> . For example:
|
|
|
|
<pre>
|
|
<tt>-o</tt> <b>delete</b><tt>=</tt><i>security</i><tt>.*
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>would suppress security-related information. See <a href="#tag_04_100_13_03">pax Extended Header</a> for extended header record
|
|
keyword usage.</p>
|
|
</dd>
|
|
|
|
<dt><b>exthdr.name</b>=<i>string</i></dt>
|
|
|
|
<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> </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>
|
|
</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/%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> </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>
|
|
</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.%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>B</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>B</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,
|
|
" <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 </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>
|
|
|
|
<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 Std 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, "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 <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 </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 "address" and
|
|
"line" 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 <newline>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 </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 Std 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 <newline> 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 Std 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 <<i>entry type</i>> 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 <space>.</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 -> %s", <</tt><i>value of keyword</i><tt>>, <</tt><i>contents of link</i><tt>>
|
|
</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 <blank>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>
|
|
|
|
<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 Std 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", <</tt><i>pathname</i><tt>>
|
|
</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", <</tt><i>ls</i> <tt>-l</tt> <i>listing</i><tt>>, <</tt><i>linkname</i><tt>>
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>For all other pathnames:</p>
|
|
|
|
<pre>
|
|
<tt>"%s\n", <</tt><i>ls</i> <tt>-l</tt> <i>listing</i><tt>>
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>where <<i>ls </i> -l <i>listing</i>> 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 <blank>-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", <</tt><i>pathname</i><tt>>
|
|
</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 <newline>, 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">>><img src="../images/delta.gif" border=
|
|
"0">%s\n", <</tt><i>original pathname</i><tt>>, <</tt><i>new pathname</i><tt>>
|
|
</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 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 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", <</tt><i>length</i><tt>>, <</tt><i>keyword</i><tt>>, <</tt><i>value</i><tt>>
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>The extended header records shall be encoded according to the ISO/IEC 10646-1:2000 standard (UTF-8). The
|
|
<<i>length</i>> field, <blank>, equals sign, and <newline> shown shall be limited to the portable character set,
|
|
as encoded in UTF-8. The <<i>keyword</i>> and <<i>value</i>> fields can be any UTF-8 characters. The
|
|
<<i>length</i>> field shall be the decimal length of the extended header record in octets, including the trailing
|
|
<newline>.</p>
|
|
|
|
<p>The <<i>keyword</i>> 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 <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 <<i>value</i>> 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><value></b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b>Formal Standard</b></p>
|
|
</th>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">ISO-IR<img src="../images/delta.gif" border="0">646<img src="../images/delta.gif" border="0">1990</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">ISO/IEC 646:1990</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">ISO-IR<img src="../images/delta.gif" border="0">8859<img src="../images/delta.gif" border="0">1<img src=
|
|
"../images/delta.gif" border="0">1998</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">ISO/IEC 8859-1:1998</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">ISO-IR<img src="../images/delta.gif" border="0">8859<img src="../images/delta.gif" border="0">2<img src=
|
|
"../images/delta.gif" border="0">1999</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">ISO/IEC 8859-2:1999</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">ISO-IR<img src="../images/delta.gif" border="0">8859<img src="../images/delta.gif" border="0">3<img src=
|
|
"../images/delta.gif" border="0">1999</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">ISO/IEC 8859-3:1999</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">ISO-IR<img src="../images/delta.gif" border="0">8859<img src="../images/delta.gif" border="0">4<img src=
|
|
"../images/delta.gif" border="0">1998</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">ISO/IEC 8859-4:1998</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">ISO-IR<img src="../images/delta.gif" border="0">8859<img src="../images/delta.gif" border="0">5<img src=
|
|
"../images/delta.gif" border="0">1999</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">ISO/IEC 8859-5:1999</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">ISO-IR<img src="../images/delta.gif" border="0">8859<img src="../images/delta.gif" border="0">6<img src=
|
|
"../images/delta.gif" border="0">1999</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">ISO/IEC 8859-6:1999</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">ISO-IR<img src="../images/delta.gif" border="0">8859<img src="../images/delta.gif" border="0">7<img src=
|
|
"../images/delta.gif" border="0">1987</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">ISO/IEC 8859-7:1987</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">ISO-IR<img src="../images/delta.gif" border="0">8859<img src="../images/delta.gif" border="0">8<img src=
|
|
"../images/delta.gif" border="0">1999</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">ISO/IEC 8859-8:1999</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">ISO-IR<img src="../images/delta.gif" border="0">8859<img src="../images/delta.gif" border="0">9<img src=
|
|
"../images/delta.gif" border="0">1999</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">ISO/IEC 8859-9:1999</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">ISO-IR<img src="../images/delta.gif" border="0">8859<img src="../images/delta.gif" border="0">10<img src=
|
|
"../images/delta.gif" border="0">1998</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">ISO/IEC 8859-10:1998</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">ISO-IR<img src="../images/delta.gif" border="0">8859<img src="../images/delta.gif" border="0">13<img src=
|
|
"../images/delta.gif" border="0">1998</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">ISO/IEC 8859-13:1998</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">ISO-IR<img src="../images/delta.gif" border="0">8859<img src="../images/delta.gif" border="0">14<img src=
|
|
"../images/delta.gif" border="0">1998</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">ISO/IEC 8859-14:1998</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">ISO-IR<img src="../images/delta.gif" border="0">8859<img src="../images/delta.gif" border="0">15<img src=
|
|
"../images/delta.gif" border="0">1999</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">ISO/IEC 8859-15:1999</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">ISO-IR<img src="../images/delta.gif" border="0">10646<img src="../images/delta.gif" border="0">2000</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">ISO/IEC 10646:2000</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">ISO-IR<img src="../images/delta.gif" border="0">10646<img src="../images/delta.gif" border="0">2000<img src=
|
|
"../images/delta.gif" border="0">UTF-8</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">ISO/IEC 10646, UTF-8 encoding</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">BINARY</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">None.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
|
|
<p>The encoding is included in an extended header for information only; when <i>pax</i> is used as described in
|
|
IEEE Std 1003.1-2001, it shall not translate the file data into any other encoding. The <b>BINARY</b> entry indicates
|
|
unencoded binary data.</p>
|
|
|
|
<p>When used in <b>write</b> or <b>copy</b> mode, it is implementation-defined whether <i>pax</i> includes a <b>charset</b>
|
|
extended header record for a file.</p>
|
|
</dd>
|
|
|
|
<dt><b>comment</b></dt>
|
|
|
|
<dd>A series of characters used as a comment. All characters in the <<i>value</i>> field shall be ignored by <i>pax</i>.</dd>
|
|
|
|
<dt><b>ctime</b></dt>
|
|
|
|
<dd>The file creation time for the following file(s), equivalent to the value of the <i>st_ctime</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 creation time shall be
|
|
restored if the process has the appropriate privilege required to do so. The format of the <<i>value</i>> shall be as
|
|
described in <a href="#tag_04_100_13_05">pax Extended Header File Times</a> .</dd>
|
|
|
|
<dt><b>gid</b></dt>
|
|
|
|
<dd>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 <i>gid</i> field in the following header block(s). When used in <b>write</b> or
|
|
<b>copy</b> mode, <i>pax</i> shall include a <i>gid</i> extended header record for each file whose group ID is greater than 2097151
|
|
(octal 7777777).</dd>
|
|
|
|
<dt><b>gname</b></dt>
|
|
|
|
<dd>The group of the file(s), formatted as a group name in the group database. This record shall override the <i>gid</i> and
|
|
<i>gname</i> fields in the following header block(s), and any <i>gid</i> extended header record. When used in <b>read</b>,
|
|
<b>copy</b>, or <b>list</b> mode, <i>pax</i> shall translate the name from the UTF-8 encoding in the header record to the character
|
|
set appropriate for the group database on the receiving system. If any of the UTF-8 characters cannot be translated, and if the
|
|
<b>-o</b> <b>invalid=</b> UTF-8 option is not specified, the results are implementation-defined. When used in <b>write</b> or
|
|
<b>copy</b> mode, <i>pax</i> shall include a <b>gname</b> extended header record for each file whose group name cannot be
|
|
represented entirely with the letters and digits of the portable character set.</dd>
|
|
|
|
<dt><b>linkpath</b></dt>
|
|
|
|
<dd>The pathname of a link being created to another file, of any type, previously archived. This record shall override the
|
|
<i>linkname</i> field in the following <b>ustar</b> header block(s). The following <b>ustar</b> header block shall determine the
|
|
type of link created. If <i>typeflag</i> of the following header block is 1, it shall be a hard link. If <i>typeflag</i> is 2, it
|
|
shall be a symbolic link and the <b>linkpath</b> value shall be the contents of the symbolic link. The <i>pax</i> utility shall
|
|
translate the name of the link (contents of the symbolic link) from the UTF-8 encoding to the character set appropriate for the
|
|
local file system. When used in <b>write</b> or <b>copy</b> mode, <i>pax</i> shall include a <b>linkpath</b> extended header record
|
|
for each link whose pathname cannot be represented entirely with the members of the portable character set other than NUL.</dd>
|
|
|
|
<dt><b>mtime</b></dt>
|
|
|
|
<dd>The file modification time of the following file(s), equivalent to the value of the <i>st_mtime</i> member of the <b>stat</b>
|
|
structure for a file, as described in the <a href="../functions/stat.html"><i>stat</i>()</a> function. This record shall override
|
|
the <i>mtime</i> field in the following header block(s). The modification time shall be restored if the process has the appropriate
|
|
privilege required to do so. The format of the <<i>value</i>> shall be as described in <a href="#tag_04_100_13_05">pax
|
|
Extended Header File Times</a> .</dd>
|
|
|
|
<dt><b>path</b></dt>
|
|
|
|
<dd>The pathname of the following file(s). This record shall override the <i>name</i> and <i>prefix</i> fields in the following
|
|
header block(s). The <i>pax</i> utility shall translate the pathname of the file from the UTF-8 encoding to the character set
|
|
appropriate for the local file system.
|
|
|
|
<p>When used in <b>write</b> or <b>copy</b> mode, <i>pax</i> shall include a <i>path</i> extended header record for each file whose
|
|
pathname cannot be represented entirely with the members of the portable character set other than NUL.</p>
|
|
</dd>
|
|
|
|
<dt><b>realtime.</b><i>any</i></dt>
|
|
|
|
<dd>The keywords prefixed by "realtime." are reserved for future standardization.</dd>
|
|
|
|
<dt><b>security.</b><i>any</i></dt>
|
|
|
|
<dd>The keywords prefixed by "security." are reserved for future standardization.</dd>
|
|
|
|
<dt><b>size</b></dt>
|
|
|
|
<dd>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 <i>size</i> field in the following header block(s). When used in <b>write</b> or <b>copy</b> mode, <i>pax</i>
|
|
shall include a <i>size</i> extended header record for each file with a size value greater than 8589934591 (octal
|
|
77777777777).</dd>
|
|
|
|
<dt><b>uid</b></dt>
|
|
|
|
<dd>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 <i>uid</i> field in the following header block(s). When used in <b>write</b> or <b>copy</b> mode, <i>pax</i>
|
|
shall include a <i>uid</i> extended header record for each file whose owner ID is greater than 2097151 (octal 7777777).</dd>
|
|
|
|
<dt><b>uname</b></dt>
|
|
|
|
<dd>The owner of the following file(s), formatted as a user name in the user database. This record shall override the <i>uid</i>
|
|
and <i>uname</i> fields in the following header block(s), and any <i>uid</i> extended header record. When used in <b>read</b>,
|
|
<b>copy</b>, or <b>list</b> mode, <i>pax</i> shall translate the name from the UTF-8 encoding in the header record to the character
|
|
set appropriate for the user database on the receiving system. If any of the UTF-8 characters cannot be translated, and if the
|
|
<b>-o</b> <b>invalid=</b> UTF-8 option is not specified, the results are implementation-defined. When used in <b>write</b> or
|
|
<b>copy</b> mode, <i>pax</i> shall include a <b>uname</b> extended header record for each file whose user name cannot be
|
|
represented entirely with the letters and digits of the portable character set.</dd>
|
|
</dl>
|
|
|
|
<p>If the <<i>value</i>> 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>
|
|
|
|
<p>If a keyword in an extended header record (or in a <b>-o</b> option-argument) overrides or deletes a corresponding field in the
|
|
<b>ustar</b> header block, <i>pax</i> shall ignore the contents of that header block field.</p>
|
|
|
|
<p>Unlike the <b>ustar</b> header block fields, NULs shall not delimit <<i>value</i>>s; all characters within the
|
|
<<i>value</i>> field shall be considered data for the field. None of the length limitations of the <b>ustar</b> header block
|
|
fields in <a href="#tagtcjh_15">ustar Header Block</a> shall apply to the extended header records.</p>
|
|
|
|
<h5><a name="tag_04_100_13_04"></a>pax Extended Header Keyword Precedence</h5>
|
|
|
|
<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 <i>pax</i> is used in <b>read</b> or <b>list</b> modes, it shall determine a file attribute in
|
|
the following sequence:</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>If <b>-o</b> <b>delete=</b> <i>keyword-prefix</i> is used, the affected attributes shall be determined from step 7., if
|
|
applicable, or ignored otherwise.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If <b>-o</b> <i>keyword</i>:= is used, the affected attributes shall be ignored.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If <b>-o</b> <i>keyword</i> <b>:=</b> <i>value</i> is used, the affected attribute shall be assigned the value.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If there is a <i>typeflag</i> <b>x</b> extended header record, the affected attribute shall be assigned the
|
|
<<i>value</i>>. When extended header records conflict, the last one given in the header shall take precedence.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If <b>-o</b> <i>keyword</i> <b>=</b> <i>value</i> is used, the affected attribute shall be assigned the value.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If there is a <i>typeflag</i> <b>g</b> global extended header record, the affected attribute shall be assigned the
|
|
<<i>value</i>>. When global extended header records conflict, the last one given in the global header shall take
|
|
precedence.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Otherwise, the attribute shall be determined from the <b>ustar</b> header block.</p>
|
|
</li>
|
|
</ol>
|
|
|
|
<h5><a name="tag_04_100_13_05"></a>pax Extended Header File Times</h5>
|
|
|
|
<p>The <i>pax</i> utility shall write an <b>mtime</b> record for each file in <b>write</b> or <b>copy</b> modes if the file's
|
|
modification time cannot be represented exactly in the <b>ustar</b> header logical record described in <a href=
|
|
"#tag_04_100_13_06">ustar Interchange Format</a> . This can occur if the time is out of <b>ustar</b> 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 ( <tt>'.'</tt> ) 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 <b>read</b> or <b>copy</b> mode,
|
|
the <i>pax</i> utility shall truncate the time of a file to the greatest value that is not greater than the input header file time.
|
|
In <b>write</b> or <b>copy</b> mode, the <i>pax</i> 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.</p>
|
|
|
|
<h5><a name="tag_04_100_13_06"></a>ustar Interchange Format</h5>
|
|
|
|
<p>A <b>ustar</b> 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>
|
|
|
|
<p>The logical records may be grouped for physical I/O operations, as described under the <b>-b</b> <i>blocksize</i> and <b>-x</b>
|
|
<b>ustar</b> options. Each group of logical records may be written with a single operation equivalent to the <a href=
|
|
"../functions/write.html"><i>write</i>()</a> 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>
|
|
|
|
<p>The header logical record shall be structured as shown in the following table. All lengths and offsets are in decimal.<br>
|
|
</p>
|
|
|
|
<center><b><a name="tagtcjh_15"></a> Table: ustar Header Block</b></center>
|
|
|
|
<center>
|
|
<table border="1" cellpadding="3" align="center">
|
|
<tr valign="top">
|
|
<th align="center">
|
|
<p class="tent"><b>Field Name</b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b>Octet Offset</b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b>Length (in Octets)</b></p>
|
|
</th>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>name</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">0</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">100</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>mode</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">100</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">8</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>uid</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">108</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">8</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>gid</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">116</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">8</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>size</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">124</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">12</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>mtime</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">136</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">12</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>chksum</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">148</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">8</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>typeflag</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">156</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">1</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>linkname</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">157</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">100</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>magic</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">257</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">6</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>version</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">263</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">2</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>uname</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">265</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">32</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>gname</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">297</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">32</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>devmajor</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">329</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">8</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>devminor</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">337</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">8</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>prefix</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">345</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">155</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
|
|
<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>
|
|
|
|
<p>However, the <i>pax</i> utility shall never create filenames on the local system that cannot be accessed via the procedures
|
|
described in IEEE Std 1003.1-2001. 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
|
|
<i>pax</i> utility may choose to ignore these files as long as it produces an error indicating that the file is being ignored.</p>
|
|
|
|
<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>
|
|
|
|
<p>The fields <i>magic</i>, <i>uname</i>, and <i>gname</i> are character strings each terminated by a NUL character. The fields
|
|
<i>name</i>, <i>linkname</i>, and <i>prefix</i> are NUL-terminated character strings except when all characters in the array
|
|
contain non-NUL characters including the last character. The <i>version</i> field is two octets containing the characters
|
|
<tt>"00"</tt> (zero-zero). The <i>typeflag</i> 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>
|
|
|
|
<p>The <i>name</i> and the <i>prefix</i> fields shall produce the pathname of the file. A new pathname shall be formed, if
|
|
<i>prefix</i> is not an empty string (its first character is not NUL), by concatenating <i>prefix</i> (up to the first NUL
|
|
character), a slash character, and <i>name</i>; otherwise, <i>name</i> is used alone. In either case, <i>name</i> is terminated at
|
|
the first NUL character. If <i>prefix</i> 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, <i>pax</i> shall notify the user of the error,
|
|
and shall not store any part of the file-header or data-on the medium.</p>
|
|
|
|
<p>The <i>linkname</i> field, described below, shall not use the <i>prefix</i> to produce a pathname. As such, a <i>linkname</i> is
|
|
limited to 100 characters. If the name does not fit in the space provided, <i>pax</i> shall notify the user of the error, and shall
|
|
not attempt to store the link on the medium.</p>
|
|
|
|
<p>The <i>mode</i> field provides 12 bits encoded in the ISO/IEC 646:1991 standard octal digit representation. The encoded
|
|
bits shall represent the following values:<br>
|
|
</p>
|
|
|
|
<center><b>Table: ustar <i>mode</i> Field</b></center>
|
|
|
|
<center>
|
|
<table border="1" cellpadding="3" align="center">
|
|
<tr valign="top">
|
|
<th align="center">
|
|
<p class="tent"><b>Bit Value</b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b>IEEE Std 1003.1-2001 Bit</b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b>Description</b></p>
|
|
</th>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">04000</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">S_ISUID</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Set UID on execution.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">02000</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">S_ISGID</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Set GID on execution.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">01000</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"><reserved></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Reserved for future standardization.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">00400</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">S_IRUSR</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Read permission for file owner class.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">00200</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">S_IWUSR</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Write permission for file owner class.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">00100</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">S_IXUSR</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Execute/search permission for file owner class.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">00040</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">S_IRGRP</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Read permission for file group class.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">00020</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">S_IWGRP</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Write permission for file group class.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">00010</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">S_IXGRP</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Execute/search permission for file group class.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">00004</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">S_IROTH</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Read permission for file other class.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">00002</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">S_IWOTH</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Write permission for file other class.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">00001</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">S_IXOTH</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Execute/search permission for file other class.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
|
|
<p>When appropriate privilege is required to set one of these mode bits, and the user restoring the files from the archive does not
|
|
have the appropriate privilege, the mode bits for which the user does not have appropriate privilege shall be ignored. Some of the
|
|
mode bits in the archive format are not mentioned elsewhere in this volume of IEEE Std 1003.1-2001. If the implementation
|
|
does not support those bits, they may be ignored.</p>
|
|
|
|
<p>The <i>uid</i> and <i>gid</i> fields are the user and group ID of the owner and group of the file, respectively.</p>
|
|
|
|
<p>The <i>size</i> field is the size of the file in octets. If the <i>typeflag</i> field is set to specify a file to be of type 1
|
|
(a link) or 2 (a symbolic link), the <i>size</i> field shall be specified as zero. If the <i>typeflag</i> field is set to specify a
|
|
file of type 5 (directory), the <i>size</i> 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 <i>typeflag</i> field is set to 3 (character special file), 4 (block
|
|
special file), or 6 (FIFO), the meaning of the <i>size</i> field is unspecified by this volume of IEEE Std 1003.1-2001,
|
|
and no data logical records shall be stored on the medium. Additionally, for type 6, the <i>size</i> field shall be ignored when
|
|
reading. If the <i>typeflag</i> field is set to any other value, the number of logical records written following the header shall
|
|
be ( <i>size</i>+511)/512, ignoring any fraction in the result of the division.</p>
|
|
|
|
<p>The <i>mtime</i> 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 <a href=
|
|
"../functions/stat.html"><i>stat</i>()</a> function.</p>
|
|
|
|
<p>The <i>chksum</i> 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 <i>chksum</i> field is treated as if it were all spaces.</p>
|
|
|
|
<p>The <i>typeflag</i> field specifies the type of file archived. If a particular implementation does not recognize the type, or
|
|
the user does not have appropriate privilege 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 <i>size</i> field that could cause data logical records to be written on the medium
|
|
(see the previous description for <i>size</i>). If conversion to a regular file occurs, the <i>pax</i> utility shall produce an
|
|
error indicating that the conversion took place. All of the <i>typeflag</i> fields shall be coded in the ISO/IEC 646:1991
|
|
standard IRV:</p>
|
|
|
|
<dl compact>
|
|
<dt><tt>0</tt></dt>
|
|
|
|
<dd>Represents a regular file. For backwards-compatibility, a <i>typeflag</i> value of binary zero ( <tt>'\0'</tt> ) 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 <i>typeflag</i> value of the ISO/IEC 646:1991 standard IRV <tt>'0'</tt> .</dd>
|
|
|
|
<dt><tt>1</tt></dt>
|
|
|
|
<dd>Represents a file linked to another file, of any type, previously archived. Such files are identified by each file having the
|
|
same device and file serial number. The linked-to name is specified in the <i>linkname</i> field with a NUL-character terminator if
|
|
it is less than 100 octets in length.</dd>
|
|
|
|
<dt><tt>2</tt></dt>
|
|
|
|
<dd>Represents a symbolic link. The contents of the symbolic link shall be stored in the <i>linkname</i> field.</dd>
|
|
|
|
<dt><tt>3,4</tt></dt>
|
|
|
|
<dd>Represent character special files and block special files respectively. In this case the <i>devmajor</i> and <i>devminor</i>
|
|
fields shall contain information defining the device, the format of which is unspecified by this volume of
|
|
IEEE Std 1003.1-2001. Implementations may map the device specifications to their own local specification or may ignore
|
|
the entry.</dd>
|
|
|
|
<dt><tt>5</tt></dt>
|
|
|
|
<dd>Specifies a directory or subdirectory. On systems where disk allocation is performed on a directory basis, the <i>size</i>
|
|
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 <i>size</i> field of zero indicates no such limiting. Systems that do not support limiting in this manner
|
|
should ignore the <i>size</i> field.</dd>
|
|
|
|
<dt><tt>6</tt></dt>
|
|
|
|
<dd>Specifies a FIFO special file. Note that the archiving of a FIFO file archives the existence of this file and not its
|
|
contents.</dd>
|
|
|
|
<dt><tt>7</tt></dt>
|
|
|
|
<dd>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).</dd>
|
|
|
|
<dt><tt>A-Z</tt></dt>
|
|
|
|
<dd>The letters <tt>'A'</tt> to <tt>'Z'</tt> , inclusive, are reserved for custom implementations. All other values are reserved
|
|
for future versions of IEEE Std 1003.1-2001.</dd>
|
|
</dl>
|
|
|
|
<p>Attempts to archive a socket using <b>ustar</b> interchange format shall produce a diagnostic message. Handling of other file
|
|
types is implementation-defined.</p>
|
|
|
|
<p>The <i>magic</i> field is the specification that this archive was output in this archive format. If this field contains
|
|
<b>ustar</b> (the five characters from the ISO/IEC 646:1991 standard IRV shown followed by NUL), the <i>uname</i> and
|
|
<i>gname</i> 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 <i>uid</i> and <i>gid</i> fields.</p>
|
|
|
|
<h5><a name="tag_04_100_13_07"></a>cpio Interchange Format</h5>
|
|
|
|
<p>The octet-oriented <b>cpio</b> 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>
|
|
|
|
<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>
|
|
|
|
<p>For the octet-oriented <b>cpio</b> archive format, the individual entry information shall be in the order indicated and
|
|
described by the following table; see also the <a href="../basedefs/cpio.h.html"><i><cpio.h></i></a> header.<br>
|
|
</p>
|
|
|
|
<center><b><a name="tagtcjh_16"></a> Table: Octet-Oriented cpio Archive Entry</b></center>
|
|
|
|
<center>
|
|
<table border="1" cellpadding="3" align="center">
|
|
<tr valign="top">
|
|
<th align="center">
|
|
<p class="tent"><b>Header Field Name</b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b>Length (in Octets)</b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b>Interpreted as</b></p>
|
|
</th>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>c_magic</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">6</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Octal number</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>c_dev</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">6</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Octal number</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>c_ino</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">6</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Octal number</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>c_mode</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">6</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Octal number</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>c_uid</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">6</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Octal number</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>c_gid</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">6</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Octal number</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>c_nlink</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">6</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Octal number</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>c_rdev</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">6</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Octal number</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>c_mtime</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">11</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Octal number</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>c_namesize</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">6</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Octal number</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>c_filesize</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">11</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Octal number</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<th align="center">
|
|
<p class="tent"><b>Filename Field Name</b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b>Length</b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b>Interpreted as</b></p>
|
|
</th>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>c_name</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"><i>c_namesize</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Pathname string</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<th align="center">
|
|
<p class="tent"><b>File Data Field Name</b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b>Length</b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b>Interpreted as</b></p>
|
|
</th>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>c_filedata</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"><i>c_filesize</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Data</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
|
|
<h5><a name="tag_04_100_13_08"></a>cpio Header</h5>
|
|
|
|
<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:</p>
|
|
|
|
<dl compact>
|
|
<dt><i>c_magic</i></dt>
|
|
|
|
<dd>Identify the archive as being a transportable archive by containing the identifying value <tt>"070707"</tt> .</dd>
|
|
|
|
<dt><i>c_dev</i>, <i>c_ino</i></dt>
|
|
|
|
<dd>Contains values that uniquely identify the file within the archive (that is, no files contain the same pair of <i>c_dev</i> and
|
|
<i>c_ino</i> values unless they are links to the same file). The values shall be determined in an unspecified manner.</dd>
|
|
|
|
<dt><i>c_mode</i></dt>
|
|
|
|
<dd>Contains the file type and access permissions as defined in the following table.<br>
|
|
<center><b><a name="tagtcjh_17"></a> Table: Values for cpio c_mode Field</b></center>
|
|
|
|
<center>
|
|
<table border="1" cellpadding="3" align="center">
|
|
<tr valign="top">
|
|
<th align="center">
|
|
<p class="tent"><b>File Permissions Name</b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b>Value</b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b>Indicates</b></p>
|
|
</th>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">C_IRUSR</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">000400</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Read by owner</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">C_IWUSR</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">000200</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Write by owner</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">C_IXUSR</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">000100</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Execute by owner</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">C_IRGRP</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">000040</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Read by group</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">C_IWGRP</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">000020</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Write by group</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">C_IXGRP</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">000010</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Execute by group</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">C_IROTH</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">000004</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Read by others</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">C_IWOTH</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">000002</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Write by others</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">C_IXOTH</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">000001</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Execute by others</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">C_ISUID</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">004000</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Set <i>uid</i></p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">C_ISGID</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">002000</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Set <i>gid</i></p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">C_ISVTX</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">001000</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Reserved</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<th align="center">
|
|
<p class="tent"><b>File Type Name</b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b>Value</b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b>Indicates</b></p>
|
|
</th>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">C_ISDIR</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">040000</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Directory</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">C_ISFIFO</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">010000</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">FIFO</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">C_ISREG</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">0100000</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Regular file</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">C_ISLNK</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">0120000</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Symbolic link</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">C_ISBLK</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">060000</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Block special file</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">C_ISCHR</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">020000</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Character special file</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">C_ISSOCK</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">0140000</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Socket</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">C_ISCTG</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">0110000</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Reserved</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
|
|
<p>Directories, FIFOs, symbolic links, and regular files shall be supported on a system conforming to this volume of
|
|
IEEE Std 1003.1-2001; 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.</p>
|
|
</dd>
|
|
|
|
<dt><i>c_uid</i></dt>
|
|
|
|
<dd>Contains the user ID of the owner.</dd>
|
|
|
|
<dt><i>c_gid</i></dt>
|
|
|
|
<dd>Contains the group ID of the group.</dd>
|
|
|
|
<dt><i>c_nlink</i></dt>
|
|
|
|
<dd>Contains the number of links referencing the file at the time the archive was created.</dd>
|
|
|
|
<dt><i>c_rdev</i></dt>
|
|
|
|
<dd>Contains implementation-defined information for character or block special files.</dd>
|
|
|
|
<dt><i>c_mtime</i></dt>
|
|
|
|
<dd>Contains the latest time of modification of the file at the time the archive was created.</dd>
|
|
|
|
<dt><i>c_namesize</i></dt>
|
|
|
|
<dd>Contains the length of the pathname, including the terminating NUL character.</dd>
|
|
|
|
<dt><i>c_filesize</i></dt>
|
|
|
|
<dd>Contains the length of the file in octets. This shall be the length of the data section following the header structure.</dd>
|
|
</dl>
|
|
|
|
<h5><a name="tag_04_100_13_09"></a>cpio Filename</h5>
|
|
|
|
<p>The <i>c_name</i> field shall contain the pathname of the file. The length of this field in octets is the value of
|
|
<i>c_namesize</i>.</p>
|
|
|
|
<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>
|
|
|
|
<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 <i>pax</i> utility shall never create filenames on the local system that cannot be accessed via the procedures described
|
|
previously in this volume of IEEE Std 1003.1-2001. 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 <i>pax</i> utility may choose to ignore these files as long as it produces an error indicating that the file is being
|
|
ignored.</p>
|
|
|
|
<h5><a name="tag_04_100_13_10"></a>cpio File Data</h5>
|
|
|
|
<p>Following <i>c_name</i>, there shall be <i>c_filesize</i> octets of data. Interpretation of such data occurs in a manner
|
|
dependent on the file. If <i>c_filesize</i> is zero, no data shall be contained in <i>c_filedata</i>.</p>
|
|
|
|
<p>When restoring from an archive:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>If the user does not have the appropriate privilege to create a file of the specified type, <i>pax</i> shall ignore the entry
|
|
and write an error message to standard error.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Only regular files 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.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If a user does not have appropriate privilege 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 IEEE Std 1003.1-2001. If the implementation does not
|
|
support those flags, they may be ignored.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<h5><a name="tag_04_100_13_11"></a>cpio Special Entries</h5>
|
|
|
|
<p>FIFO special files, directories, and the trailer shall be recorded with <i>c_filesize</i> equal to zero. For other special
|
|
files, <i>c_filesize</i> is unspecified by this volume of IEEE Std 1003.1-2001. 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
|
|
<b>TRAILER!!!</b> shall indicate the end of the archive; the contents of octets in the last block of the archive following such a
|
|
header are undefined.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_100_14"></a>EXIT STATUS</h4>
|
|
|
|
<blockquote>
|
|
<p>The following exit values shall be returned:</p>
|
|
|
|
<dl compact>
|
|
<dt> 0</dt>
|
|
|
|
<dd>All files were processed successfully.</dd>
|
|
|
|
<dt>>0</dt>
|
|
|
|
<dd>An error occurred.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_100_15"></a>CONSEQUENCES OF ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>If <i>pax</i> 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 <b>-p</b> 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 <i>pax</i> cannot
|
|
create a link to a file, <i>pax</i> shall not, by default, create a second copy of the file.</p>
|
|
|
|
<p>If the extraction of a file from an archive is prematurely terminated by a signal or error, <i>pax</i> may have only partially
|
|
extracted the file or (if the <b>-n</b> 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.</p>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_04_100_16"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>The <b>-p</b> (privileges) option was invented to reconcile differences between historical <i>tar</i> and <i>cpio</i>
|
|
implementations. In particular, the two utilities use <b>-m</b> in diametrically opposed ways. The <b>-p</b> 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:</p>
|
|
|
|
<dl compact>
|
|
<dt><b>-p e</b></dt>
|
|
|
|
<dd>``Preserve everything". This would be used by the historical superuser, someone with all the appropriate privileges, to
|
|
preserve all aspects of the files as they are recorded in the archive. The <b>e</b> flag is the sum of <b>o</b> and <b>p</b>, and
|
|
other implementation-defined attributes.</dd>
|
|
|
|
<dt><b>-p p</b></dt>
|
|
|
|
<dd>``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.</dd>
|
|
</dl>
|
|
|
|
<p>The one pathname per line format of standard input precludes pathnames containing <newline>s. Although such pathnames
|
|
violate the portable filename guidelines, they may exist and their presence may inhibit usage of <i>pax</i> 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>
|
|
|
|
<p>It is almost certain that appropriate privileges are required for <i>pax</i> to accomplish parts of this volume of
|
|
IEEE Std 1003.1-2001. Specifically, creating files of type block special or character special, restoring file access
|
|
times unless the files are owned by the user (the <b>-t</b> option), or preserving file owner, group, and mode (the <b>-p</b>
|
|
option) all probably require appropriate privileges.</p>
|
|
|
|
<p>In <b>read</b> 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>
|
|
|
|
<p>The <b>cpio</b> and <b>ustar</b> formats can only support files up to 8589934592 bytes (8 * 2^30) in size.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_100_17"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<p>The following command:</p>
|
|
|
|
<pre>
|
|
<tt>pax -w -f /dev/rmt/1m .
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>copies the contents of the current directory to tape drive 1, medium density (assuming historical System V device naming
|
|
procedures-the historical BSD device name would be <b>/dev/rmt9</b>).</p>
|
|
|
|
<p>The following commands:</p>
|
|
|
|
<pre>
|
|
<tt>mkdir</tt> <i>newdir</i><tt>pax -rw</tt> <i>olddir newdir</i>
|
|
</pre>
|
|
|
|
<p>copy the <i>olddir</i> directory hierarchy to <i>newdir</i>.</p>
|
|
|
|
<pre>
|
|
<tt>pax -r -s ',^//*usr//*,,' -f a.pax
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>reads the archive <b>a.pax</b>, with all files rooted in <b>/usr</b> in the archive extracted relative to the current
|
|
directory.</p>
|
|
|
|
<p>Using the option:</p>
|
|
|
|
<pre>
|
|
<tt>-o listopt="%M %(atime)T %(size)D %(name)s"
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>overrides the default output description in Standard Output and instead writes:</p>
|
|
|
|
<pre>
|
|
<tt>-rw-rw--- Jan 12 15:53 1492 /usr/foo/bar
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>Using the options:</p>
|
|
|
|
<pre>
|
|
<tt>-o listopt='%L\t%(size)D\n%.7' \
|
|
-o listopt='(name)s\n%(ctime)T\n%T'
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>overrides the default output description in Standard Output and instead writes:</p>
|
|
|
|
<pre>
|
|
<tt>/usr/foo/bar -> /tmp 1492
|
|
/usr/fo
|
|
Jan 12 1991
|
|
Jan 31 15:53
|
|
</tt>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_100_18"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>pax</i> utility was new for the ISO POSIX-2:1993 standard. It represents a peaceful compromise between advocates of
|
|
the historical <i>tar</i> and <i>cpio</i> utilities.</p>
|
|
|
|
<p>A fundamental difference between <i>cpio</i> and <i>tar</i> was in the way directories were treated. The <i>cpio</i> 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 <i>tar</i>, a directory matched every file in the file hierarchy it rooted.</p>
|
|
|
|
<p>The <i>pax</i> utility offers both interfaces; by default, directories map into the file hierarchy they root. The <b>-d</b>
|
|
option causes <i>pax</i> to skip any file not explicitly referenced, as <i>cpio</i> historically did. The <i>tar</i> <b>-</b>
|
|
<i>style</i> behavior was chosen as the default because it was believed that this was the more common usage and because <i>tar</i>
|
|
is the more commonly available interface, as it was historically provided on both System V and BSD implementations.</p>
|
|
|
|
<p>The data interchange format specification in this volume of IEEE Std 1003.1-2001 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 <i>cpio</i>, but not
|
|
in <i>tar</i>.) In order to avoid these two problems, the <i>pax</i> specification has an additional "privilege" mechanism, the
|
|
<b>-p</b> option. Only a <i>pax</i> invocation with the privileges needed, and which has the <b>-p</b> option set using the
|
|
<tt>e</tt> specification character, has the "appropriate privilege" to restore full ownership and permission information.</p>
|
|
|
|
<p>Note also that this volume of IEEE Std 1003.1-2001 requires that the file ownership and access permissions shall be
|
|
set, on extraction, in the same fashion as the <a href="../functions/creat.html"><i>creat</i>()</a> 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>
|
|
|
|
<p>Users should note that directories may be created by <i>pax</i> 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>
|
|
|
|
<p>The table of contents output is written to standard output to facilitate pipeline processing.</p>
|
|
|
|
<p>An early proposal had hard links displaying for all pathnames. This was removed because it complicates the output of the case
|
|
where <b>-v</b> is not specified and does not match historical <i>cpio</i> usage. The hard-link information is available in the
|
|
<b>-v</b> display.</p>
|
|
|
|
<p>The description of the <b>-l</b> option allows implementations to make hard links to symbolic links.
|
|
IEEE Std 1003.1-2001 does not specify any way to create a hard link to a symbolic link, but many implementations provide
|
|
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 <b>-H</b> or <b>-L</b> is specified). When in <b>read</b> mode and in
|
|
<b>copy</b> mode, implementations supporting hard links to symbolic links should use them when appropriate.</p>
|
|
|
|
<p>The archive formats inherited from the POSIX.1-1990 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 <i>pax</i> is used in
|
|
<b>copy</b>( <b>-rw</b>) mode (copying directory hierarchies), the ability to use extensions from the <b>-x</b> <b>pax</b> format
|
|
overcomes these restrictions.</p>
|
|
|
|
<p>The default <i>blocksize</i> value of 5120 bytes for <i>cpio</i> was selected because it is one of the standard block-size
|
|
values for <i>cpio</i>, set when the <b>-B</b> option is specified. (The other default block-size value for <i>cpio</i> is 512
|
|
bytes, and this was considered to be too small.) The default block value of 10240 bytes for <i>tar</i> was selected because that is
|
|
the standard block-size value for BSD <i>tar</i>. The maximum block size of 32256 bytes (2<small><sup>15</sup></small>-512 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 <a href="../utilities/dd.html"><i>dd</i></a> 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
|
|
IEEE Std 1003.1-2001 as unimportant and not likely to affect the structure of the resulting archive.</p>
|
|
|
|
<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>
|
|
|
|
<p>The intended use of the <b>-n</b> 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 <b>-n</b> 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 <i>pax</i> 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 IEEE Std 1003.1-2001, 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 <i>pax</i> 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 <b>-n</b> option can be easily obtained using the <b>-s</b> option or a <a
|
|
href="../utilities/sed.html"><i>sed</i></a> 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>
|
|
|
|
<p>In this version, the <b>-n</b> was removed from the <b>copy</b> mode synopsis of <i>pax</i>; it is inapplicable because there
|
|
are no pattern operands specified in this mode.</p>
|
|
|
|
<p>There is another method than <i>pax</i> for copying subtrees in IEEE Std 1003.1-2001 described as part of the <a href=
|
|
"../utilities/cp.html"><i>cp</i></a> utility. Both methods are historical practice: <a href="../utilities/cp.html"><i>cp</i></a>
|
|
provides a simpler, more intuitive interface, while <i>pax</i> offers a finer granularity of control. Each provides additional
|
|
functionality to the other; in particular, <i>pax</i> maintains the hard-link structure of the hierarchy while <a href=
|
|
"../utilities/cp.html"><i>cp</i></a> 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>
|
|
|
|
<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>
|
|
|
|
<p>The <b>-d</b> option (do not create intermediate directories not listed in the archive) found in early proposals was originally
|
|
provided as a complement to the historic <b>-d</b> option of <i>cpio</i>. It has been deleted.</p>
|
|
|
|
<p>The <b>-s</b> option in early proposals specified a subset of the substitution command from the <a href=
|
|
"../utilities/ed.html"><i>ed</i></a> utility. As there was no reason for only a subset to be supported, the <b>-s</b> option is now
|
|
compatible with the current <a href="../utilities/ed.html"><i>ed</i></a> specification. Since the delimiter can be any non-null
|
|
character, the following usage with single spaces is valid:</p>
|
|
|
|
<pre>
|
|
<tt>pax -s " foo bar " ...
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>The <b>-t</b> 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>
|
|
|
|
<p>The default behavior of <i>pax</i> with regard to file modification times is the same as historical implementations of
|
|
<i>tar</i>. It is not the historical behavior of <i>cpio</i>.</p>
|
|
|
|
<p>Because the <b>-i</b> option uses <b>/dev/tty</b>, utilities without a controlling terminal are not able to use this option.</p>
|
|
|
|
<p>The <b>-y</b> option, found in early proposals, has been deleted because a line containing a single period for the <b>-i</b>
|
|
option has equivalent functionality. The special lines for the <b>-i</b> option (a single period and the empty line) are historical
|
|
practice in <i>cpio</i>.</p>
|
|
|
|
<p>In early drafts, a <b>-e</b> <i>charmap</i> 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-8 should be an adequate substitute.</p>
|
|
|
|
<p>The <b>-k</b> option was added to address international concerns about the dangers involved in the character set transformations
|
|
of <b>-e</b> (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 <b>-o</b> <b>invalid=</b> option-specifically the UTF-8 action. (Note that an existing file that is named with a
|
|
UTF-8 encoding is still subject to overwriting in this case. The <b>-k</b> option closes that loophole.)</p>
|
|
|
|
<p>Some of the file characteristics referenced in this volume of IEEE Std 1003.1-2001 might not be supported by some
|
|
archive formats. For example, neither the <b>tar</b> nor <b>cpio</b> formats contain the file access time. For this reason, the
|
|
<tt>e</tt> specification character has been provided, intended to cause all file characteristics specified in the archive to be
|
|
retained.</p>
|
|
|
|
<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 <a href="../utilities/umask.html"><i>umask</i></a> of the user, with sufficient
|
|
permissions to allow file creation. After all files have been extracted, <i>pax</i> would then reset the access and modification
|
|
times and permissions as necessary.</p>
|
|
|
|
<p>The list-mode formatting description borrows heavily from the one defined by the <a href=
|
|
"../utilities/printf.html"><i>printf</i></a> 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>
|
|
|
|
<p>The <tt>T</tt> conversion specifier allows time fields to be displayed in any of the date formats. Unlike the <a href=
|
|
"../utilities/ls.html"><i>ls</i></a> utility, <i>pax</i> does not adjust the format when the date is less than six months in the
|
|
past. This makes parsing the output more predictable.</p>
|
|
|
|
<p>The <tt>D</tt> conversion specifier handles the ability to display the major/minor or file size, as with <a href=
|
|
"../utilities/ls.html"><i>ls</i></a>, by using <tt>%-8(</tt><i>size</i><tt>)D</tt>.</p>
|
|
|
|
<p>The <tt>L</tt> conversion specifier handles the <a href="../utilities/ls.html"><i>ls</i></a> display for symbolic links.</p>
|
|
|
|
<p>Conversion specifiers were added to generate existing known types used for <a href="../utilities/ls.html"><i>ls</i></a>.</p>
|
|
|
|
<h5><a name="tag_04_100_18_01"></a>pax Interchange Format</h5>
|
|
|
|
<p>The new POSIX data interchange format was developed primarily to satisfy international concerns that the <b>ustar</b> and
|
|
<b>cpio</b> 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:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>Support international character encodings and locale information</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Support security information (ACLs, and so on)</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Support future file types, such as realtime or contiguous files</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Include data areas for implementation use</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Support systems with words larger than 32 bits and timers with subsecond granularity</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>The following were not goals for this format because these are better handled by separate utilities or are inappropriate for a
|
|
portable format:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>Encryption</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Compression</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Data translation between locales and codesets</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p><i>inode</i> storage</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>The format chosen to support the goals is an extension of the <b>ustar</b> format. Of the two formats previously available, only
|
|
the <b>ustar</b> format was selected for extensions because:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>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 <b>cpio</b> 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.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Industry experience since the original " <i>tar</i> wars" fought in developing the ISO POSIX-1 standard has clearly been
|
|
in favor of the <b>ustar</b> format, which is generally the default output format selected for <i>pax</i> implementations on new
|
|
systems.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>The new format was designed with one additional goal in mind: reasonable behavior when an older <i>tar</i> or <i>pax</i> utility
|
|
happened to read an archive. Since the POSIX.1-1990 standard mandated that a "format-reading utility" had to treat unrecognized
|
|
<i>typeflag</i> 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 <b>ustar</b> 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>
|
|
|
|
<p>The <b>ustar</b> <i>typeflag</i> field was used to accommodate the additional functionality of the new format rather than magic
|
|
or version because the POSIX.1-1990 standard (and, by reference, the previous version of <i>pax</i>), mandated the behavior of the
|
|
format-reading utility when it encountered an unknown <i>typeflag</i>, but was silent about the other two fields.</p>
|
|
|
|
<p>Early proposals of the first revision to IEEE Std 1003.1-2001 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>
|
|
|
|
<p>The prefix and name split of pathnames in <b>ustar</b> was replaced by the single path extended header record for
|
|
simplicity.</p>
|
|
|
|
<p>The concept of a global extended header ( <i>typeflag</i> <b>g</b>) 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-ROM, 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 <i>typeflag</i>
|
|
<b>g</b> records.</p>
|
|
|
|
<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>
|
|
|
|
<p>One such approach would be to have <b>filter=</b> 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
|
|
IEEE Std 1003.1-2001 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>
|
|
|
|
<p>There is currently no portable means of identifying the character set(s) used for a file in the file system. Therefore,
|
|
<i>pax</i> 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 <b>-o</b> <b>charset=</b> <i>string</i> 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>
|
|
|
|
<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 <<i>value</i>>s
|
|
represent names of officially registered character sets in the format required by the ISO 2375:1985 standard.</p>
|
|
|
|
<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 <a href="../utilities/getopts.html"><i>getopts</i></a>.</p>
|
|
|
|
<p>Further information on character encodings is in <a href="#tag_04_100_18_02">pax Archive Character Set Encoding/Decoding</a>
|
|
.</p>
|
|
|
|
<p>The standard developers have reserved keyword name space for vendor extensions. It is suggested that the format to be used
|
|
is:</p>
|
|
|
|
<pre>
|
|
<i>VENDOR.keyword</i>
|
|
</pre>
|
|
|
|
<p>where <i>VENDOR</i> 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 <i>VENDOR</i> prefix.</p>
|
|
|
|
<p>The <<i>length</i>> 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 <i>pax</i>) 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>
|
|
|
|
<p>There are no extended header versions of the <i>devmajor</i> and <i>devminor</i> fields because the unspecified format
|
|
<b>ustar</b> header field should be sufficient. If they are not, vendor-specific extended keywords (such as <i>VENDOR.devmajor</i>)
|
|
should be used.</p>
|
|
|
|
<p>Device and <i>i</i>-number labeling of files was not adopted from <i>cpio</i>; files are interchanged strictly on a symbolic
|
|
name basis, as in <b>ustar</b>.</p>
|
|
|
|
<p>Just as with the <b>ustar</b> format descriptions, the new format makes no special arrangements for multi-volume archives. Each
|
|
of the <i>pax</i> 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>
|
|
|
|
<p>The <b>pax</b> 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:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>It contains information as coded characters that could be coded in binary.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>It identifies extended records with name fields that could be omitted in favor of a fixed-field layout.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>It translates names into a portable character set and identifies locale-related information, both of which are probably
|
|
unnecessary for backup.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<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 <a href="../functions/chown.html"><i>chown</i>()</a> might be much more restricted.
|
|
There is no implication in IEEE Std 1003.1-2001 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>
|
|
|
|
<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 <i>pax</i> is
|
|
expected to interpret such archives on input properly, despite the fact that there is no <i>pax</i> option that would force this
|
|
mixed case on output. (When <b>-o</b> <b>linkdata</b> is used, the output must contain the duplicate data, but the implementation
|
|
is free to include it or omit it when <b>-o</b> <b>linkdata</b> is not used.)</p>
|
|
|
|
<p>The time values are included as extended header records for those implementations needing more than the eleven octal digits
|
|
allowed by the <b>ustar</b> format. Portable file timestamps cannot be negative. If <i>pax</i> encounters a file with a negative
|
|
timestamp in <b>copy</b> or <b>write</b> mode, it can reject the file, substitute a non-negative timestamp, or generate a
|
|
non-portable timestamp with a leading <tt>'-'</tt> . 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-1 standard states
|
|
them that way. The <b>ustar</b> format includes only <i>mtime</i>; the new format adds <i>atime</i> and <i>ctime</i> for symmetry.
|
|
The <i>atime</i> access time restored to the file system will be affected by the <b>-p</b> <b>a</b> and <b>-p</b> <b>e</b> options.
|
|
The <i>ctime</i> creation time (actually <i>inode</i> modification time) is described with "appropriate privilege" 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 <i>pax</i> from restoring the value.</p>
|
|
|
|
<p>The <i>gid</i>, <i>size</i>, and <i>uid</i> extended header records were included to allow expansion beyond the sizes specified
|
|
in the regular <i>tar</i> 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 <i>tar</i> header.</p>
|
|
|
|
<p>The standard developers intended to describe the effective results of <i>pax</i> 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>
|
|
|
|
<p>Much of the text describing the extended headers refers to use in " <b>write</b> or <b>copy</b> modes". The <b>copy</b> 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 <i>pax</i> is actually generating the extended
|
|
headers in <b>copy</b> mode, but the effects must be as if it had.</p>
|
|
|
|
<h5><a name="tag_04_100_18_02"></a>pax Archive Character Set Encoding/Decoding</h5>
|
|
|
|
<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 <i>pax</i> utility.</p>
|
|
|
|
<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>
|
|
|
|
<p>For these reasons, the codeset used to represent characters within the extended header records of the <i>pax</i> 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>
|
|
|
|
<p>The standard developers considered the following options:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>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.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>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.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>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>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>The approach that incorporates the name of the source codeset poses the problem of codeset name registration, and makes the
|
|
archive useless to <i>pax</i> archive decoders that do not recognize that codeset.</p>
|
|
|
|
<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-duplicating extended header records on
|
|
unreliable media-but this would be too burdensome for large character set maps.)</p>
|
|
|
|
<p>Both of the above approaches also put an undue burden on the <i>pax</i> archive receiver to handle the cross-product of all
|
|
source and destination codesets.</p>
|
|
|
|
<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>
|
|
|
|
<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-1: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>
|
|
|
|
<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-8 defined in the
|
|
ISO/IEC 10646-1: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>
|
|
|
|
<p>The encoding of UTF-8 is as follows:</p>
|
|
|
|
<pre>
|
|
<tt>UCS4 Hex Encoding UTF-8 Binary Encoding
|
|
<br>
|
|
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
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>where each <tt>'x'</tt> represents a bit value from the character being translated.</p>
|
|
|
|
<h5><a name="tag_04_100_18_03"></a>ustar Interchange Format</h5>
|
|
|
|
<p>The description of the <b>ustar</b> format reflects numerous enhancements over pre-1988 versions of the historical <i>tar</i>
|
|
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>
|
|
|
|
<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>
|
|
|
|
<p>The total size of the <i>name</i> and <i>prefix</i> fields have been set to meet the minimum requirements for {PATH_MAX}. If a
|
|
pathname will fit within the <i>name</i> field, it is recommended that the pathname be stored there without the use of the
|
|
<i>prefix</i> 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 <i>linkname</i> field being limited in size
|
|
to just that of the <i>name</i> field.</p>
|
|
|
|
<p>The <i>size</i> 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>
|
|
|
|
<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 ( <b>A</b>- <b>Z</b>) be used, and that the additional information for the special file be represented as
|
|
data and be reflected in the <i>size</i> field.</p>
|
|
|
|
<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, <i>pax</i> should not be able to overwrite the entries in,
|
|
for example, <b>/dev</b> 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>
|
|
|
|
<p>The value 7 in the <i>typeflag</i> field is intended to define how contiguous files can be stored in a <b>ustar</b> archive.
|
|
IEEE Std 1003.1-2001 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 <i>pax</i> utility should do the best it can with the file and go on to the next.</p>
|
|
|
|
<p>The file protection modes are those conventionally used by the <a href="../utilities/ls.html"><i>ls</i></a> utility. This is
|
|
extended beyond the usage in the ISO POSIX-2 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.</p>
|
|
|
|
<h5><a name="tag_04_100_18_04"></a>cpio Interchange Format</h5>
|
|
|
|
<p>The reference to appropriate privilege in the <b>cpio</b> format refers to an error on standard output; the <b>ustar</b> format
|
|
does not make comparable statements.</p>
|
|
|
|
<p>The model for this format was the historical System V <i>cpio</i> <b>-c</b> data interchange format. This model documents the
|
|
portable version of the <b>cpio</b> format and not the binary version. It has the flexibility to transfer data of any type
|
|
described within IEEE Std 1003.1-2001, yet is extensible to transfer data types specific to extensions beyond
|
|
IEEE Std 1003.1-2001 (for example, contiguous files). Because it describes existing practice, there is no question of
|
|
maintaining upwards-compatibility.</p>
|
|
|
|
<h5><a name="tag_04_100_18_05"></a>cpio Header</h5>
|
|
|
|
<p>There has been some concern that the size of the <i>c_ino</i> field of the header is too small to handle those systems that have
|
|
very large <i>inode</i> numbers. However, the <i>c_ino</i> field in the header is used strictly as a hard-link resolution mechanism
|
|
for archives. It is not necessarily the same value as the <i>inode</i> number of the file in the location from which that file is
|
|
extracted.</p>
|
|
|
|
<p>The name <i>c_magic</i> is based on historical usage.</p>
|
|
|
|
<h5><a name="tag_04_100_18_06"></a>cpio Filename</h5>
|
|
|
|
<p>For most historical implementations of the <i>cpio</i> 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 <i>c_namesize</i> to determine the exact length of the
|
|
pathname. With the current description of the <a href="../basedefs/cpio.h.html"><i><cpio.h></i></a> header, this pathname
|
|
size can be as large as a number that is described in six octal digits.</p>
|
|
|
|
<p>Two values are documented under the <i>c_mode</i> field values to provide for extensibility for known file types:</p>
|
|
|
|
<dl compact>
|
|
<dt><b>0110 000</b></dt>
|
|
|
|
<dd>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.</dd>
|
|
</dl>
|
|
|
|
<p>This provides for extensibility of the <b>cpio</b> 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
|
|
<i>pax</i> utility should do the best it can with the file and go on to the next.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_100_19"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_100_20"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="xcu_chap02.html#tag_02"><i>Shell Command Language</i></a> , <a href="cp.html"><i>cp</i></a> , <a href=
|
|
"ed.html"><i>ed</i></a> , <a href="getopts.html"><i>getopts</i></a> , <a href="ls.html"><i>ls</i></a> , <a href=
|
|
"printf.html"><i>printf</i>()</a> , the Base Definitions volume of IEEE Std 1003.1-2001, <a href=
|
|
"../basedefs/cpio.h.html"><i><cpio.h></i></a>, the System Interfaces volume of IEEE Std 1003.1-2001, <a href=
|
|
"../functions/chown.html"><i>chown</i>()</a>, <a href="../functions/creat.html"><i>creat</i>()</a>, <a href=
|
|
"../functions/mkdir.html"><i>mkdir</i>()</a>, <a href="../functions/mkfifo.html"><i>mkfifo</i>()</a>, <a href=
|
|
"../functions/stat.html"><i>stat</i>()</a>, <a href="../functions/utime.html"><i>utime</i>()</a>, <a href=
|
|
"../functions/write.html"><i>write</i>()</a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_100_21"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 4.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_100_22"></a>Issue 5</h4>
|
|
|
|
<blockquote>
|
|
<p>A note is added to the APPLICATION USAGE indicating that the <b>cpio</b> and <b>tar</b> formats can only support files up to 8
|
|
gigabytes in size.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_100_23"></a>Issue 6</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>pax</i> utility is aligned with the IEEE P1003.2b draft standard:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>Support has been added for symbolic links in the options and interchange formats.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>A new format has been devised, based on extensions to <b>ustar</b>.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>References to the "extended" <b>tar</b> and <b>cpio</b> formats derived from the POSIX.1-1990 standard have been changed to
|
|
remove the "extended" adjective because this could cause confusion with the extended <i>tar</i> header added in this revision.
|
|
(All references to <i>tar</i> are actually to <b>ustar</b>.)</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>The <i>TZ</i> entry is added to the ENVIRONMENT VARIABLES section.</p>
|
|
|
|
<p>IEEE PASC Interpretation 1003.2 #168 is applied, clarifying that <a href="../functions/mkdir.html"><i>mkdir</i>()</a> and <a
|
|
href="../functions/mkfifo.html"><i>mkfifo</i>()</a> calls can ignore an [EEXIST] error when extracting an archive.</p>
|
|
|
|
<p>IEEE PASC Interpretation 1003.2 #180 is applied, clarifying how extracted files are created when in <b>read</b> mode.</p>
|
|
|
|
<p>IEEE PASC Interpretation 1003.2 #181 is applied, clarifying the description of the <b>-t</b> option.</p>
|
|
|
|
<p>IEEE PASC Interpretation 1003.2 #195 is applied.</p>
|
|
|
|
<p>IEEE PASC Interpretation 1003.2 #206 is applied, clarifying the handling of links for the <b>-H</b>, <b>-L</b>, and <b>-l</b>
|
|
options.</p>
|
|
</blockquote>
|
|
|
|
<div class="box"><em>End of informative text.</em></div>
|
|
|
|
<hr>
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
|
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
|
]</font></center>
|
|
|
|
<!--footer end-->
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|