625 lines
29 KiB
HTML
625 lines
29 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>ar</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="ar"></a> <a name="tag_04_03"></a><!-- ar -->
|
|
<!--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_03_01"></a>NAME</h4>
|
|
|
|
<blockquote>ar - create and maintain library archives</blockquote>
|
|
|
|
<h4><a name="tag_04_03_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<div class="box"><code><tt><sup>[<a href="javascript:open_code('SD')">SD</a>]</sup> <img src="../images/opt-start.gif" alt=
|
|
"[Option Start]" border="0"> ar -d</tt><b>[</b><tt>-v</tt><b>]</b> <i>archive file</i> <tt>... <img src="../images/opt-end.gif"
|
|
alt="[Option End]" border="0"></tt></code></div>
|
|
|
|
<tt><br>
|
|
<br>
|
|
</tt>
|
|
<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt=
|
|
"[Option Start]" border="0"> ar -m</tt><b>[</b><tt>-abiv</tt><b>][</b><i>posname</i><b>]</b> <i>archive file</i> <tt>... <img src=
|
|
"../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div>
|
|
|
|
<tt><br>
|
|
<br>
|
|
<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> ar -p</tt><b>[</b><tt>-v</tt><b>]<img src="../images/opt-start.gif"
|
|
border="0">[</b><tt>-s</tt><b>]<img src="../images/opt-end.gif" border="0"></b><i>archive</i> <b>[</b><i>file</i>
|
|
<tt>...</tt><b>]</b><tt><br>
|
|
<br>
|
|
</tt>
|
|
<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt=
|
|
"[Option Start]" border="0"> ar -q</tt><b>[</b><tt>-cv</tt><b>]</b> <i>archive file</i> <tt>... <img src="../images/opt-end.gif"
|
|
alt="[Option End]" border="0"></tt></code></div>
|
|
|
|
<tt><br>
|
|
<br>
|
|
<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> ar -r</tt><b>[</b><tt>-cuv</tt><b>]<img src="../images/opt-start.gif"
|
|
border="0">[</b><tt>-abi</tt><b>][</b><i>posname</i><b>]<img src="../images/opt-end.gif" border="0"></b><i>archive file</i>
|
|
<tt>...<br>
|
|
<br>
|
|
<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> ar -t</tt><b>[</b><tt>-v</tt><b>]<img src="../images/opt-start.gif"
|
|
border="0">[</b><tt>-s</tt><b>]<img src="../images/opt-end.gif" border="0"></b><i>archive</i> <b>[</b><i>file</i>
|
|
<tt>...</tt><b>]</b><tt><br>
|
|
<br>
|
|
<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> ar -x</tt><b>[</b><tt>-v</tt><b>]<img src="../images/opt-start.gif"
|
|
border="0">[</b><tt>-sCT</tt><b>]<img src="../images/opt-end.gif" border="0"></b><i>archive</i> <b>[</b><i>file</i>
|
|
<tt>...</tt><b>]</b><tt><br>
|
|
</tt></blockquote>
|
|
|
|
<h4><a name="tag_04_03_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>ar</i> utility is part of the Software Development Utilities option.</p>
|
|
|
|
<p>The <i>ar</i> utility can be used to create and maintain groups of files combined into an archive. Once an archive has been
|
|
created, new files can be added, and existing files in an archive can be extracted, deleted, or replaced. When an archive consists
|
|
entirely of valid object files, the implementation shall format the archive so that it is usable as a library for link editing (see
|
|
<a href="../utilities/c99.html"><i>c99</i></a> and <a href="../utilities/fort77.html"><i>fort77</i></a>). When some of the archived
|
|
files are not valid object files, the suitability of the archive for library use is undefined. <sup>[<a href=
|
|
"javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> If an
|
|
archive consists entirely of printable files, the entire archive shall be printable.</p>
|
|
|
|
<p>When <i>ar</i> creates an archive, it creates administrative information indicating whether a symbol table is present in the
|
|
archive. When there is at least one object file that <i>ar</i> recognizes as such in the archive, an archive symbol table shall be
|
|
created in the archive and maintained by <i>ar</i>; it is used by the link editor to search the archive. Whenever the <i>ar</i>
|
|
utility is used to create or update the contents of such an archive, the symbol table shall be rebuilt. The <b>-s</b> option shall
|
|
force the symbol table to be rebuilt. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
|
|
<p>All <i>file</i> operands can be pathnames. However, files within archives shall be named by a filename, which is the last
|
|
component of the pathname used when the file was entered into the archive. The comparison of <i>file</i> operands to the names of
|
|
files in archives shall be performed by comparing the last component of the operand to the name of the file in the archive.</p>
|
|
|
|
<p>It is unspecified whether multiple files in the archive may be identically named. In the case of such files, however, each
|
|
<i>file</i> <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]"
|
|
border="0"> and <i>posname</i> <img src="../images/opt-end.gif" alt="[Option End]" border="0"> operand shall match only the
|
|
first file in the archive having a name that is the same as the last component of the operand.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_03_04"></a>OPTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>ar</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>.</p>
|
|
|
|
<p>The following options shall be supported:</p>
|
|
|
|
<dl compact>
|
|
<dt><b>-a</b></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
Position new files in the archive after the file named by the <i>posname</i> operand. <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"></dd>
|
|
|
|
<dt><b>-b</b></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
Position new files in the archive before the file named by the <i>posname</i> operand. <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"></dd>
|
|
|
|
<dt><b>-c</b></dt>
|
|
|
|
<dd>Suppress the diagnostic message that is written to standard error by default when the archive <i>archive</i> is created.</dd>
|
|
|
|
<dt><b>-C</b></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
Prevent extracted files from replacing like-named files in the file system. This option is useful when <b>-T</b> is also used, to
|
|
prevent truncated filenames from replacing files with the same prefix. <img src="../images/opt-end.gif" alt="[Option End]" border=
|
|
"0"></dd>
|
|
|
|
<dt><b>-d</b></dt>
|
|
|
|
<dd>Delete one or more <i>file</i>s from <i>archive</i>.</dd>
|
|
|
|
<dt><b>-i</b></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
Position new files in the archive before the file in the archive named by the <i>posname</i> operand (equivalent to <b>-b</b>).
|
|
<img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd>
|
|
|
|
<dt><b>-m</b></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
Move the named files in the archive. The <b>-a</b>, <b>-b</b>, or <b>-i</b> options with the <i>posname</i> operand indicate the
|
|
position; otherwise, move the names files in the archive to the end of the archive. <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"></dd>
|
|
|
|
<dt><b>-p</b></dt>
|
|
|
|
<dd>Write the contents of the <i>file</i>s in the archive named by <i>file</i> operands from <i>archive</i> to the standard output.
|
|
If no <i>file</i> operands are specified, the contents of all files in the archive shall be written in the order of the
|
|
archive.</dd>
|
|
|
|
<dt><b>-q</b></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
Append the named files to the end of the archive. In this case <i>ar</i> does not check whether the added files are already in the
|
|
archive. This is useful to bypass the searching otherwise done when creating a large archive piece by piece. <img src=
|
|
"../images/opt-end.gif" alt="[Option End]" border="0"></dd>
|
|
|
|
<dt><b>-r</b></dt>
|
|
|
|
<dd>Replace or add <i>file</i>s to <i>archive</i>. If the archive named by <i>archive</i> does not exist, a new archive shall be
|
|
created and a diagnostic message shall be written to standard error (unless the <b>-c</b> option is specified). If no <i>file</i>s
|
|
are specified and the <i>archive</i> exists, the results are undefined. Files that replace existing files in the archive shall not
|
|
change the order of the archive. Files that do not replace existing files in the archive shall be appended to the archive <sup>[<a
|
|
href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> unless
|
|
a <b>-a</b>, <b>-b</b>, or <b>-i</b> option specifies another position. <img src="../images/opt-end.gif" alt="[Option End]" border=
|
|
"0"></dd>
|
|
|
|
<dt><b>-s</b></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
Force the regeneration of the archive symbol table even if <i>ar</i> is not invoked with an option that modifies the archive
|
|
contents. This option is useful to restore the archive symbol table after it has been stripped; see <a href=
|
|
"../utilities/strip.html"><i>strip</i></a>. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd>
|
|
|
|
<dt><b>-t</b></dt>
|
|
|
|
<dd>Write a table of contents of <i>archive</i> to the standard output. The files specified by the <i>file</i> operands shall be
|
|
included in the written list. If no <i>file</i> operands are specified, all files in <i>archive</i> shall be included in the order
|
|
of the archive.</dd>
|
|
|
|
<dt><b>-T</b></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
Allow filename truncation of extracted files whose archive names are longer than the file system can support. By default,
|
|
extracting a file with a name that is too long shall be an error; a diagnostic message shall be written and the file shall not be
|
|
extracted. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd>
|
|
|
|
<dt><b>-u</b></dt>
|
|
|
|
<dd>Update older files in the archive. When used with the <b>-r</b> option, files in the archive shall be replaced only if the
|
|
corresponding <i>file</i> has a modification time that is at least as new as the modification time of the file in the archive.</dd>
|
|
|
|
<dt><b>-v</b></dt>
|
|
|
|
<dd>Give verbose output. When used with the option characters <b>-d</b>, <b>-r</b>, or <b>-x</b>, write a detailed file-by-file
|
|
description of the archive creation and maintenance activity, as described in the STDOUT section.
|
|
|
|
<p>When used with <b>-p</b>, write the name of the file in the archive to the standard output before writing the file in the
|
|
archive itself to the standard output, as described in the STDOUT section.</p>
|
|
|
|
<p>When used with <b>-t</b>, include a long listing of information about the files in the archive, as described in the STDOUT
|
|
section.</p>
|
|
</dd>
|
|
|
|
<dt><b>-x</b></dt>
|
|
|
|
<dd>Extract the files in the archive named by the <i>file</i> operands from <i>archive</i>. The contents of the archive shall not
|
|
be changed. If no <i>file</i> operands are given, all files in the archive shall be extracted. The modification time of each file
|
|
extracted shall be set to the time the file is extracted from the archive.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_03_05"></a>OPERANDS</h4>
|
|
|
|
<blockquote>
|
|
<p>The following operands shall be supported:</p>
|
|
|
|
<dl compact>
|
|
<dt><i>archive</i></dt>
|
|
|
|
<dd>A pathname of the archive.</dd>
|
|
|
|
<dt><i>file</i></dt>
|
|
|
|
<dd>A pathname. Only the last component shall be used when comparing against the names of files in the archive. If two or more
|
|
<i>file</i> operands have the same last pathname component (basename), the results are unspecified. The implementation's archive
|
|
format shall not truncate valid filenames of files added to or replaced in the archive.</dd>
|
|
|
|
<dt><i>posname</i></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
The name of a file in the archive, used for relative positioning; see options <b>-m</b> and <b>-r</b>. <img src=
|
|
"../images/opt-end.gif" alt="[Option End]" border="0"></dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_03_06"></a>STDIN</h4>
|
|
|
|
<blockquote>
|
|
<p>Not used.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_03_07"></a>INPUT FILES</h4>
|
|
|
|
<blockquote>
|
|
<p>The archive named by <i>archive</i> shall be a file in the format created by <i>ar</i> <b>-r</b>.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_03_08"></a>ENVIRONMENT VARIABLES</h4>
|
|
|
|
<blockquote>
|
|
<p>The following environment variables shall affect the execution of <i>ar</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_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).</dd>
|
|
|
|
<dt><i>LC_MESSAGES</i></dt>
|
|
|
|
<dd>Determine the locale 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 content for date and time strings written by <i>ar</i> <b>-tv</b>.</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 overrides the default directory for temporary files, if any.</dd>
|
|
|
|
<dt><i>TZ</i></dt>
|
|
|
|
<dd>Determine the timezone used to calculate date and time strings written by <i>ar</i> <b>-tv</b>. If <i>TZ</i> is unset or null,
|
|
an unspecified default timezone shall be used.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_03_09"></a>ASYNCHRONOUS EVENTS</h4>
|
|
|
|
<blockquote>
|
|
<p>Default.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_03_10"></a>STDOUT</h4>
|
|
|
|
<blockquote>
|
|
<p>If the <b>-d</b> option is used with the <b>-v</b> option, the standard output format shall be:</p>
|
|
|
|
<pre>
|
|
<tt>"d - %s\n", <</tt><i>file</i><tt>>
|
|
</tt>
|
|
</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<%s>\n\n", <</tt><i>file</i><tt>>
|
|
</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", <</tt><i>file</i><tt>>
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>where <<i>file</i>> 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", <</tt><i>file</i><tt>>
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>where <<i>file</i>> 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", <</tt><i>file</i><tt>>
|
|
</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", <</tt><i>member mode</i><tt>>, <</tt><i>user ID</i><tt>>,
|
|
<</tt><i>group ID</i><tt>>, <</tt><i>number of bytes in member</i><tt>>,
|
|
<</tt><i>abbreviated month</i><tt>>, <</tt><i>day-of-month</i><tt>>, <</tt><i>hour</i><tt>>,
|
|
<</tt><i>minute</i><tt>>, <</tt><i>year</i><tt>>, <</tt><i>file</i><tt>>
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>where:</p>
|
|
|
|
<dl compact>
|
|
<dt><<i>file</i>></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><<i>member mode</i>></dt>
|
|
|
|
<dd><br>
|
|
Shall be formatted the same as the <<i>file mode</i>> string defined in the STDOUT section of <a href=
|
|
"../utilities/ls.html"><i>ls</i></a>, except that the first character, the <<i>entry type</i>>, 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><<i>abbreviated month</i>></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><<i>day-of-month</i>></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><<i>hour</i>></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><<i>minute</i>></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><<i>year</i>></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", <</tt><i>file</i><tt>>
|
|
</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> 0</dt>
|
|
|
|
<dd>Successful completion.</dd>
|
|
|
|
<dt>>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 "archives". 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 Std 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 Std 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 Std 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 "magic" string <tt>"!<arch>\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>"<newline>"</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 <space>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
|
|
<newline>, 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 Std 1003.1-2001, <a
|
|
href="../basedefs/xbd_chap13.html#tag_13">Chapter 13, Headers</a>, <a href="../basedefs/unistd.h.html"><i><unistd.h></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 P1003.2b draft standard.</p>
|
|
|
|
<p>The normative text is reworded to avoid use of the term "must" 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 "file" to refer to a file in the
|
|
file system hierarchy, "archive" to refer to the archive being operated upon by the <i>ar</i> utility, and "file in the
|
|
archive" to refer to a copy of a file that is contained in the archive.</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>
|
|
|