ar.html

IEEE 1003.1-2003, Single Unix Specification v3

</pre>

<p>where <i>file</i> is the operand specified on the command line.</p>

<p>If the <b>-p</b> option is used with the <b>-v</b> option, <i>ar</i> shall precede the contents of each file with:</p>

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

<p>where <i>file</i> is the operand specified on the command line, if <i>file</i> operands were specified, and the name of the file
in the archive if they were not.</p>

<p>If the <b>-r</b> option is used with the <b>-v</b> option:</p>

<ul>
<li>
<p>If <i>file</i> is already in the archive, the standard output format shall be:</p>

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

<p>where &lt;<i>file</i>&gt; is the operand specified on the command line.</p>
</li>

<li>
<p>If <i>file</i> is not already in the archive, the standard output format shall be:</p>

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

<p>where &lt;<i>file</i>&gt; is the operand specified on the command line.</p>
</li>
</ul>

<p>If the <b>-t</b> option is used, <i>ar</i> shall write the names of the files in the archive to the standard output in the
format:</p>

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

<p>where <i>file</i> is the operand specified on the command line, if <i>file</i> operands were specified, or the name of the file
in the archive if they were not.</p>

<p>If the <b>-t</b> option is used with the <b>-v</b> option, the standard output format shall be:</p>

<pre>
<tt>"%s %u/%u %u %s %d %d:%d %d %s\n", &lt;</tt><i>member mode</i><tt>&gt;, &lt;</tt><i>user ID</i><tt>&gt;,
    &lt;</tt><i>group ID</i><tt>&gt;, &lt;</tt><i>number of bytes in member</i><tt>&gt;,
    &lt;</tt><i>abbreviated month</i><tt>&gt;, &lt;</tt><i>day-of-month</i><tt>&gt;, &lt;</tt><i>hour</i><tt>&gt;,
    &lt;</tt><i>minute</i><tt>&gt;, &lt;</tt><i>year</i><tt>&gt;, &lt;</tt><i>file</i><tt>&gt;
</tt>
</pre>

<p>where:</p>

<dl compact>
<dt>&lt;<i>file</i>&gt;</dt>

<dd>Shall be the operand specified on the command line, if <i>file</i> operands were specified, or the name of the file in the
archive if they were not.</dd>

<dt>&lt;<i>member&nbsp;mode</i>&gt;</dt>

<dd><br>
Shall be formatted the same as the &lt;<i>file&nbsp;mode</i>&gt; string defined in the STDOUT section of <a href=
"../utilities/ls.html"><i>ls</i></a>, except that the first character, the &lt;<i>entry&nbsp;type</i>&gt;, is not used; the string
represents the file mode of the file in the archive at the time it was added to or replaced in the archive.</dd>
</dl>

<p>The following represent the last-modification time of a file when it was most recently added to or replaced in the archive:</p>

<dl compact>
<dt>&lt;<i>abbreviated&nbsp;month</i>&gt;</dt>

<dd><br>
Equivalent to the format of the <tt>%b</tt> conversion specification format in <a href=
"../utilities/date.html"><i>date</i></a>.</dd>

<dt>&lt;<i>day-of-month</i>&gt;</dt>

<dd><br>
Equivalent to the format of the <tt>%e</tt> conversion specification format in <a href=
"../utilities/date.html"><i>date</i></a>.</dd>

<dt>&lt;<i>hour</i>&gt;</dt>

<dd>Equivalent to the format of the <tt>%H</tt> conversion specification format in <a href=
"../utilities/date.html"><i>date</i></a>.</dd>

<dt>&lt;<i>minute</i>&gt;</dt>

<dd>Equivalent to the format of the <tt>%M</tt> conversion specification format in <a href=
"../utilities/date.html"><i>date</i></a>.</dd>

<dt>&lt;<i>year</i>&gt;</dt>

<dd>Equivalent to the format of the <tt>%Y</tt> conversion specification format in <a href=
"../utilities/date.html"><i>date</i></a>.</dd>
</dl>

<p>When <i>LC_TIME</i> does not specify the POSIX locale, a different format and order of presentation of these fields relative to
each other may be used in a format appropriate in the specified locale.</p>

<p>If the <b>-x</b> option is used with the <b>-v</b> option, the standard output format shall be:</p>

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

<p>where <i>file</i> is the operand specified on the command line, if <i>file</i> operands were specified, or the name of the file
in the archive if they were not.</p>
</blockquote>

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

<blockquote>
<p>The standard error shall be used only for diagnostic messages. The diagnostic message about creating a new archive when
<b>-c</b> is not specified shall not modify the exit status.</p>
</blockquote>

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

<blockquote>
<p>Archives are files with unspecified formats.</p>
</blockquote>

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

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_04_03_14"></a>EXIT STATUS</h4>

<blockquote>
<p>The following exit values shall be returned:</p>

<dl compact>
<dt>&nbsp;0</dt>

<dd>Successful completion.</dd>

<dt>&gt;0</dt>

<dd>An error occurred.</dd>
</dl>
</blockquote>

<h4><a name="tag_04_03_15"></a>CONSEQUENCES OF ERRORS</h4>

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

<hr>
<div class="box"><em>The following sections are informative.</em></div>

<h4><a name="tag_04_03_16"></a>APPLICATION USAGE</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_04_03_17"></a>EXAMPLES</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_04_03_18"></a>RATIONALE</h4>

<blockquote>
<p>The archive format is not described. It is recognized that there are several known <i>ar</i> formats, which are not compatible.
The <i>ar</i> utility is included, however, to allow creation of archives that are intended for use only on one machine. The
archive is specified as a file, and it can be moved as a file. This does allow an archive to be moved from one machine to another
machine that uses the same implementation of <i>ar</i>.</p>

<p>Utilities such as <a href="../utilities/pax.html"><i>pax</i></a> (and its forebears <i>tar</i> and <i>cpio</i>) also provide
portable &quot;archives&quot;. This is a not a duplication; the <i>ar</i> utility is included to provide an interface primarily for <a
href="../utilities/make.html"><i>make</i></a> and the compilers, based on a historical model.</p>

<p>In historical implementations, the <b>-q</b> option (available on XSI-conforming systems) is known to execute quickly because
<i>ar</i> does not check on whether the added members are already in the archive. This is useful to bypass the searching otherwise
done when creating a large archive piece-by-piece. These remarks may but need not remain true for a brand new implementation of
this utility; hence, these remarks have been moved into the RATIONALE.</p>

<p>BSD implementations historically required applications to provide the <b>-s</b> option whenever the archive was supposed to
contain a symbol table. As in this volume of IEEE&nbsp;Std&nbsp;1003.1-2001, System V historically creates or updates an archive
symbol table whenever an object file is removed from, added to, or updated in the archive.</p>

<p>The OPERANDS section requires what might seem to be true without specifying it: the archive cannot truncate the filenames below
{NAME_MAX}. Some historical implementations do so, however, causing unexpected results for the application. Therefore, this volume
of IEEE&nbsp;Std&nbsp;1003.1-2001 makes the requirement explicit to avoid misunderstandings.</p>

<p>According to the System V documentation, the options <b>-dmpqrtx</b> are not required to begin with a hyphen ( <tt>'-'</tt> ).
This volume of IEEE&nbsp;Std&nbsp;1003.1-2001 requires that a conforming application use the leading hyphen.</p>

<p>The archive format used by the 4.4 BSD implementation is documented in this RATIONALE as an example:</p>

<blockquote>A file created by <i>ar</i> begins with the &quot;magic&quot; string <tt>"!&lt;arch&gt;\n"</tt> . The rest of the archive is
made up of objects, each of which is composed of a header for a file, a possible filename, and the file contents. The header is
portable between machine architectures, and, if the file contents are printable, the archive is itself printable. 

<p>The header is made up of six ASCII fields, followed by a two-character trailer. The fields are the object name (16 characters),
the file last modification time (12 characters), the user and group IDs (each 6 characters), the file mode (8 characters), and the
file size (10 characters). All numeric fields are in decimal, except for the file mode, which is in octal.</p>

<p>The modification time is the file <i>st_mtime</i> field. The user and group IDs are the file <i>st_uid</i> and <i>st_gid</i>
fields. The file mode is the file <i>st_mode</i> field. The file size is the file <i>st_size</i> field. The two-byte trailer is the
string <tt>"`&lt;newline&gt;"</tt> .</p>

<p>Only the name field has any provision for overflow. If any filename is more than 16 characters in length or contains an embedded
space, the string <tt>"#1/"</tt> followed by the ASCII length of the name is written in the name field. The file size (stored in
the archive header) is incremented by the length of the name. The name is then written immediately following the archive
header.</p>

<p>Any unused characters in any of these fields are written as &lt;space&gt;s. If any fields are their particular maximum number of
characters in length, there is no separation between the fields.</p>

<p>Objects in the archive are always an even number of bytes long; files that are an odd number of bytes long are padded with a
&lt;newline&gt;, although the size in the header does not reflect this.</p>
</blockquote>

<p>The <i>ar</i> utility description requires that (when all its members are valid object files) <i>ar</i> produce an object code
library, which the linkage editor can use to extract object modules. If the linkage editor needs a symbol table to permit random
access to the archive, <i>ar</i> must provide it; however, <i>ar</i> does not require a symbol table.</p>

<p>The BSD <b>-o</b> option was omitted. It is a rare conforming application that uses <i>ar</i> to extract object code from a
library with concern for its modification time, since this can only be of importance to <a href=
"../utilities/make.html"><i>make</i></a>. Hence, since this functionality is not deemed important for applications portability, the
modification time of the extracted files is set to the current time.</p>

<p>There is at least one known implementation (for a small computer) that can accommodate only object files for that system,
disallowing mixed object and other files. The ability to handle any type of file is not only historical practice for most
implementations, but is also a reasonable expectation.</p>

<p>Consideration was given to changing the output format of <i>ar</i> <b>-tv</b> to the same format as the output of <a href=
"../utilities/ls.html"><i>ls</i></a> <b>-l</b>. This would have made parsing the output of <i>ar</i> the same as that of <a href=
"../utilities/ls.html"><i>ls</i></a>. This was rejected in part because the current <i>ar</i> format is commonly used and changes
would break historical usage. Second, <i>ar</i> gives the user ID and group ID in numeric format separated by a slash. Changing
this to be the user name and group name would not be correct if the archive were moved to a machine that contained a different user
database. Since <i>ar</i> cannot know whether the archive was generated on the same machine, it cannot tell what to report.</p>

<p>The text on the <b>-ur</b> option combination is historical practice-since one filename can easily represent two different files
(for example, <b>/a/foo</b> and <b>/b/foo</b>), it is reasonable to replace the file in the archive even when the modification time
in the archive is identical to that in the file system.</p>
</blockquote>

<h4><a name="tag_04_03_19"></a>FUTURE DIRECTIONS</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_04_03_20"></a>SEE ALSO</h4>

<blockquote>
<p><a href="c99.html"><i>c99</i></a> , <a href="date.html"><i>date</i></a> , <a href="fort77.html"><i>fort77</i></a> , <a href=
"pax.html"><i>pax</i></a> , <a href="strip.html"><i>strip</i></a> the Base Definitions volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a
href="../basedefs/xbd_chap13.html#tag_13">Chapter 13, Headers</a>, <a href="../basedefs/unistd.h.html"><i>&lt;unistd.h&gt;</i></a>
description of {POSIX_NO_TRUNC}</p>
</blockquote>

<h4><a name="tag_04_03_21"></a>CHANGE HISTORY</h4>

<blockquote>
<p>First released in Issue 2.</p>
</blockquote>

<h4><a name="tag_04_03_22"></a>Issue 5</h4>

<blockquote>
<p>The FUTURE DIRECTIONS section is added.</p>
</blockquote>

<h4><a name="tag_04_03_23"></a>Issue 6</h4>

<blockquote>
<p>This utility is marked as part of the Software Development Utilities option.</p>

<p>The STDOUT description is changed for the <b>-v</b> option to align with the IEEE&nbsp;P1003.2b draft standard.</p>

<p>The normative text is reworded to avoid use of the term &quot;must&quot; for application requirements.</p>

<p>The <i>TZ</i> entry is added to the ENVIRONMENT VARIABLES section.</p>

<p>IEEE PASC Interpretation 1003.2 #198 is applied, changing the description to consistently use &quot;file&quot; to refer to a file in the
file system hierarchy, &quot;archive&quot; to refer to the archive being operated upon by the <i>ar</i> utility, and &quot;file in the
archive&quot; to refer to a copy of a file that is contained in the archive.</p>

<p>IEEE&nbsp;Std 1003.1-2001/Cor&nbsp;1-2002, item XCU/TC1/D6/10 is applied, making corrections to the SYNOPSIS. The change was
needed since the <b>-a</b>, <b>-b</b>, and <b>-i</b> options are mutually-exclusive, and <i>posname</i> is required if any of these
options is specified.</p>

<p>IEEE&nbsp;Std 1003.1-2001/Cor&nbsp;1-2002, item XCU/TC1/D6/11 is applied, correcting the description of the two-byte trailer in
RATIONALE which had missed out a backquote. The correct trailer is a backquote followed by a &lt;newline&gt;.</p>
</blockquote>

<div class="box"><em>End of informative text.</em></div>

<hr>
<hr size="2" noshade>
<center><font size="2"><!--footer start-->
UNIX &reg; is a registered Trademark of The Open Group.<br>
POSIX &reg; 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>