Un outil pour savoir si une commande est posix - retour accueil
git clone git://bebou.netlib.re/isposix
Log | Files | Refs | README |
ar.html (34190B)
1 <!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved -->
2 <!DOCTYPE HTML>
3 <html lang="en">
4 <head>
5 <meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0">
6 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
7 <link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 -->
8 <!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved -->
9 <title>ar</title>
10 </head>
11 <body bgcolor="white">
12 <div class="NAVHEADER">
13 <table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0">
14 <tr class="nav">
15 <td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/alias.html" accesskey="P"><<<
16 Previous</a></td>
17 <td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td>
18 <td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/asa.html" accesskey="N">Next >>></a></td>
19 </tr>
20 </table>
21 <hr align="left" width="100%"></div>
22 <script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3">
23 <center><font size="2">The Open Group Base Specifications Issue 8<br>
24 IEEE Std 1003.1-2024<br>
25 Copyright © 2001-2024 The IEEE and The Open Group</font></center>
26 <hr size="2" noshade>
27 <a name="top" id="top"></a> <a name="ar" id="ar"></a> <a name="tag_20_03" id="tag_20_03"></a><!-- ar -->
28 <h4 class="mansect"><a name="tag_20_03_01" id="tag_20_03_01"></a>NAME</h4>
29 <blockquote>ar — create and maintain library archives</blockquote>
30 <h4 class="mansect"><a name="tag_20_03_02" id="tag_20_03_02"></a>SYNOPSIS</h4>
31 <blockquote class="synopsis">
32 <div class="box"><code><tt><sup>[<a href="javascript:open_code('SD')">SD</a>]</sup> <img src="../images/opt-start.gif" alt=
33 "[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"
34 alt="[Option End]" border="0"></tt></code></div>
35 <tt><br>
36 <br></tt>
37 <div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt=
38 "[Option Start]" border="0"> ar -m</tt> <b>[</b><tt>-v</tt><b>]</b> <i>archive file</i><tt>...<br>
39 ar -m -a</tt> <b>[</b><tt>-v</tt><b>]</b> <i>posname archive file</i><tt>...<br>
40 ar -m -b</tt> <b>[</b><tt>-v</tt><b>]</b> <i>posname archive file</i><tt>...<br>
41 ar -m -i</tt> <b>[</b><tt>-v</tt><b>]</b> <i>posname archive file</i><tt>... <img src="../images/opt-end.gif" alt="[Option End]"
42 border="0"></tt></code></div>
43 <tt><br>
44 <br>
45 <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"
46 border="0">[</b><tt>-s</tt><b>]<img src="../images/opt-end.gif" border="0"></b> <i>archive</i>
47 <b>[</b><i>file</i><tt>...</tt><b>]</b> <tt><br>
48 <br></tt>
49 <div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt=
50 "[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"
51 alt="[Option End]" border="0"></tt></code></div>
52 <tt><br>
53 <br>
54 ar -r</tt> <b>[</b><tt>-cuv</tt><b>]</b> <i>archive file</i><tt>...<br>
55 <br></tt>
56 <div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt=
57 "[Option Start]" border="0"> ar -r -a</tt> <b>[</b><tt>-cuv</tt><b>]</b> <i>posname archive file</i><tt>...<br>
58 ar -r -b</tt> <b>[</b><tt>-cuv</tt><b>]</b> <i>posname archive file</i><tt>...<br>
59 ar -r -i</tt> <b>[</b><tt>-cuv</tt><b>]</b> <i>posname archive file</i><tt>... <img src="../images/opt-end.gif" alt="[Option End]"
60 border="0"></tt></code></div>
61 <tt><br>
62 <br>
63 <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"
64 border="0">[</b><tt>-s</tt><b>]<img src="../images/opt-end.gif" border="0"></b> <i>archive</i>
65 <b>[</b><i>file</i><tt>...</tt><b>]</b> <tt><br>
66 <br>
67 <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"
68 border="0">[</b><tt>-sCT</tt><b>]<img src="../images/opt-end.gif" border="0"></b> <i>archive</i>
69 <b>[</b><i>file</i><tt>...</tt><b>]</b> <tt><br></tt></blockquote>
70 <h4 class="mansect"><a name="tag_20_03_03" id="tag_20_03_03"></a>DESCRIPTION</h4>
71 <blockquote>
72 <p>The <i>ar</i> utility is part of the Software Development Utilities option.</p>
73 <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
74 created, new files can be added, and existing files in an archive can be extracted, deleted, or replaced. When an archive consists
75 entirely of valid object files, the implementation shall format the archive so that it is usable as a library for link editing (see
76 <a href="../utilities/c17.html"><i>c17</i></a>). When some of the archived files are not valid object files, the suitability of the
77 archive for library use is undefined. <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif"
78 alt="[Option Start]" border="0"> If an archive consists entirely of printable files, the entire archive shall be
79 printable.</p>
80 <p>When <i>ar</i> creates an archive, it creates administrative information indicating whether a symbol table is present in the
81 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
82 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>
83 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
84 force the symbol table to be rebuilt. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
85 <p>All <i>file</i> operands can be pathnames. However, files within archives shall be named by a filename, which is the last
86 component of the pathname used when the file was entered into the archive. The comparison of <i>file</i> operands to the names of
87 files in archives shall be performed by comparing the last component of the operand to the name of the file in the archive.</p>
88 <p>It is unspecified whether multiple files in the archive may be identically named. In the case of such files, however, each
89 <i>file</i> <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]"
90 border="0"> and <i>posname</i> <img src="../images/opt-end.gif" alt="[Option End]" border="0"> operand shall match only the
91 first file in the archive having a name that is the same as the last component of the operand.</p>
92 </blockquote>
93 <h4 class="mansect"><a name="tag_20_03_04" id="tag_20_03_04"></a>OPTIONS</h4>
94 <blockquote>
95 <p>The <i>ar</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax
96 Guidelines</i></a> , except for Guideline 9.</p>
97 <p>The following options shall be supported:</p>
98 <dl compact>
99 <dd></dd>
100 <dt><b>-a</b></dt>
101 <dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
102 Position new files in the archive after the file named by the <i>posname</i> operand. <img src="../images/opt-end.gif" alt=
103 "[Option End]" border="0"></dd>
104 <dt><b>-b</b></dt>
105 <dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
106 Position new files in the archive before the file named by the <i>posname</i> operand. <img src="../images/opt-end.gif" alt=
107 "[Option End]" border="0"></dd>
108 <dt><b>-c</b></dt>
109 <dd>Suppress the diagnostic message that is written to standard error by default when the archive <i>archive</i> is created.</dd>
110 <dt><b>-C</b></dt>
111 <dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
112 Prevent extracted files from replacing like-named files in the file system. This option is useful when <b>-T</b> is also used, to
113 prevent truncated filenames from replacing files with the same prefix. <img src="../images/opt-end.gif" alt="[Option End]" border=
114 "0"></dd>
115 <dt><b>-d</b></dt>
116 <dd>Delete one or more <i>file</i>s from <i>archive</i>.</dd>
117 <dt><b>-i</b></dt>
118 <dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
119 Position new files in the archive before the file in the archive named by the <i>posname</i> operand (equivalent to <b>-b</b>).
120 <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd>
121 <dt><b>-m</b></dt>
122 <dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
123 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
124 position; otherwise, move the names files in the archive to the end of the archive. <img src="../images/opt-end.gif" alt=
125 "[Option End]" border="0"></dd>
126 <dt><b>-p</b></dt>
127 <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.
128 If no <i>file</i> operands are specified, the contents of all files in the archive shall be written in the order of the
129 archive.</dd>
130 <dt><b>-q</b></dt>
131 <dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
132 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
133 archive. This is useful to bypass the searching otherwise done when creating a large archive piece by piece. <img src=
134 "../images/opt-end.gif" alt="[Option End]" border="0"></dd>
135 <dt><b>-r</b></dt>
136 <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
137 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
138 are specified and the <i>archive</i> exists, the results are undefined. Files that replace existing files in the archive shall not
139 change the order of the archive. Files that do not replace existing files in the archive shall be appended to the archive
140 <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
141 unless a <b>-a</b>, <b>-b</b>, or <b>-i</b> option specifies another position. <img src="../images/opt-end.gif" alt=
142 "[Option End]" border="0"></dd>
143 <dt><b>-s</b></dt>
144 <dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
145 Force the regeneration of the archive symbol table even if <i>ar</i> is not invoked with an option that modifies the archive
146 contents. This option is useful to restore the archive symbol table after it has been stripped; see <a href=
147 "../utilities/strip.html"><i>strip</i></a>. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd>
148 <dt><b>-t</b></dt>
149 <dd>Write a table of contents of <i>archive</i> to the standard output. Only the files specified by the <i>file</i> operands shall
150 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
151 order of the archive.</dd>
152 <dt><b>-T</b></dt>
153 <dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
154 Allow filename truncation of extracted files whose archive names are longer than the file system can support. By default,
155 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
156 extracted. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd>
157 <dt><b>-u</b></dt>
158 <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
159 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>
160 <dt><b>-v</b></dt>
161 <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
162 description of the archive creation and maintenance activity, as described in the STDOUT section.
163 <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
164 archive itself to the standard output, as described in the STDOUT section.</p>
165 <p>When used with <b>-t</b>, include a long listing of information about the files in the archive, as described in the STDOUT
166 section.</p>
167 </dd>
168 <dt><b>-x</b></dt>
169 <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
170 be changed. If no <i>file</i> operands are given, all files in the archive shall be extracted. The modification time of each file
171 extracted shall be set to the time the file is extracted from the archive.</dd>
172 </dl>
173 </blockquote>
174 <h4 class="mansect"><a name="tag_20_03_05" id="tag_20_03_05"></a>OPERANDS</h4>
175 <blockquote>
176 <p>The following operands shall be supported:</p>
177 <dl compact>
178 <dd></dd>
179 <dt><i>archive</i></dt>
180 <dd>A pathname of the archive.</dd>
181 <dt><i>file</i></dt>
182 <dd>A pathname. Only the last component shall be used when comparing against the names of files in the archive. If two or more
183 <i>file</i> operands have the same last pathname component (basename), the results are unspecified. The implementation's archive
184 format shall not truncate valid filenames of files added to or replaced in the archive.</dd>
185 <dt><i>posname</i></dt>
186 <dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
187 The name of a file in the archive, used for relative positioning; see options <b>-m</b> and <b>-r</b>. <img src=
188 "../images/opt-end.gif" alt="[Option End]" border="0"></dd>
189 </dl>
190 </blockquote>
191 <h4 class="mansect"><a name="tag_20_03_06" id="tag_20_03_06"></a>STDIN</h4>
192 <blockquote>
193 <p>Not used.</p>
194 </blockquote>
195 <h4 class="mansect"><a name="tag_20_03_07" id="tag_20_03_07"></a>INPUT FILES</h4>
196 <blockquote>
197 <p>The archive named by <i>archive</i> shall be a file in the format created by <i>ar</i> <b>-r</b>.</p>
198 </blockquote>
199 <h4 class="mansect"><a name="tag_20_03_08" id="tag_20_03_08"></a>ENVIRONMENT VARIABLES</h4>
200 <blockquote>
201 <p>The following environment variables shall affect the execution of <i>ar</i>:</p>
202 <dl compact>
203 <dd></dd>
204 <dt><i>LANG</i></dt>
205 <dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href=
206 "../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization
207 variables used to determine the values of locale categories.)</dd>
208 <dt><i>LC_ALL</i></dt>
209 <dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd>
210 <dt><i>LC_CTYPE</i></dt>
211 <dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as
212 opposed to multi-byte characters in arguments and input files).</dd>
213 <dt><i>LC_MESSAGES</i></dt>
214 <dd><br>
215 Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd>
216 <dt><i>LC_TIME</i></dt>
217 <dd>Determine the format and content for date and time strings written by <i>ar</i> <b>-tv</b>.</dd>
218 <dt><i>NLSPATH</i></dt>
219 <dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
220 Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border=
221 "0"></dd>
222 <dt><i>TMPDIR</i></dt>
223 <dd>Determine the pathname that overrides the default directory for temporary files, if any.</dd>
224 <dt><i>TZ</i></dt>
225 <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,
226 an unspecified default timezone shall be used.</dd>
227 </dl>
228 </blockquote>
229 <h4 class="mansect"><a name="tag_20_03_09" id="tag_20_03_09"></a>ASYNCHRONOUS EVENTS</h4>
230 <blockquote>
231 <p>Default.</p>
232 </blockquote>
233 <h4 class="mansect"><a name="tag_20_03_10" id="tag_20_03_10"></a>STDOUT</h4>
234 <blockquote>
235 <p>If the <b>-d</b> option is used with the <b>-v</b> option, the standard output format shall be:</p>
236 <pre>
237 <tt>"d - %s\n", <</tt><i>file</i><tt>>
238 </tt></pre>
239 <p>where <i>file</i> is the operand specified on the command line.</p>
240 <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>
241 <pre>
242 <tt>"\n<%s>\n\n", <</tt><i>file</i><tt>>
243 </tt></pre>
244 <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
245 in the archive if they were not.</p>
246 <p>If the <b>-r</b> option is used with the <b>-v</b> option:</p>
247 <ul>
248 <li>
249 <p>If <i>file</i> is already in the archive, the standard output format shall be:</p>
250 <pre>
251 <tt>"r - %s\n", <</tt><i>file</i><tt>>
252 </tt></pre>
253 <p>where <<i>file</i>> is the operand specified on the command line.</p>
254 </li>
255 <li>
256 <p>If <i>file</i> is not already in the archive, the standard output format shall be:</p>
257 <pre>
258 <tt>"a - %s\n", <</tt><i>file</i><tt>>
259 </tt></pre>
260 <p>where <<i>file</i>> is the operand specified on the command line.</p>
261 </li>
262 </ul>
263 <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
264 format:</p>
265 <pre>
266 <tt>"%s\n", <</tt><i>file</i><tt>>
267 </tt></pre>
268 <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
269 in the archive if they were not.</p>
270 <p>If the <b>-t</b> option is used with the <b>-v</b> option, the standard output format shall be:</p>
271 <pre>
272 <tt>"%s %u/%u %u %s %d %d:%d %d %s\n", <</tt><i>member mode</i><tt>>, <</tt><i>user ID</i><tt>>,
273 <</tt><i>group ID</i><tt>>, <</tt><i>number of bytes in member</i><tt>>,
274 <</tt><i>abbreviated month</i><tt>>, <</tt><i>day-of-month</i><tt>>, <</tt><i>hour</i><tt>>,
275 <</tt><i>minute</i><tt>>, <</tt><i>year</i><tt>>, <</tt><i>file</i><tt>>
276 </tt></pre>
277 <p>where:</p>
278 <dl compact>
279 <dd></dd>
280 <dt><<i>file</i>></dt>
281 <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
282 archive if they were not.</dd>
283 <dt><<i>member mode</i>></dt>
284 <dd><br>
285 Shall be formatted the same as the <<i>file mode</i>> string defined in the STDOUT section of <a href=
286 "../utilities/ls.html"><i>ls</i></a>, except that the first character, the <<i>entry type</i>>, is not used; the string
287 represents the file mode of the file in the archive at the time it was added to or replaced in the archive.</dd>
288 </dl>
289 <br>
290 <p>The following represent the last-modification time of a file when it was most recently added to or replaced in the archive:</p>
291 <dl compact>
292 <dd></dd>
293 <dt><<i>abbreviated month</i>></dt>
294 <dd><br>
295 Equivalent to the format of the <tt>%b</tt> conversion specification format in <a href=
296 "../utilities/date.html"><i>date</i></a>.</dd>
297 <dt><<i>day-of-month</i>></dt>
298 <dd><br>
299 Equivalent to the format of the <tt>%e</tt> conversion specification format in <a href=
300 "../utilities/date.html"><i>date</i></a>.</dd>
301 <dt><<i>hour</i>></dt>
302 <dd>Equivalent to the format of the <tt>%H</tt> conversion specification format in <a href=
303 "../utilities/date.html"><i>date</i></a>.</dd>
304 <dt><<i>minute</i>></dt>
305 <dd>Equivalent to the format of the <tt>%M</tt> conversion specification format in <a href=
306 "../utilities/date.html"><i>date</i></a>.</dd>
307 <dt><<i>year</i>></dt>
308 <dd>Equivalent to the format of the <tt>%Y</tt> conversion specification format in <a href=
309 "../utilities/date.html"><i>date</i></a>.</dd>
310 </dl>
311 <p>When <i>LC_TIME</i> does not specify the POSIX locale, a different format and order of presentation of these fields relative to
312 each other may be used in a format appropriate in the specified locale.</p>
313 <p>If the <b>-x</b> option is used with the <b>-v</b> option, the standard output format shall be:</p>
314 <pre>
315 <tt>"x - %s\n", <</tt><i>file</i><tt>>
316 </tt></pre>
317 <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
318 in the archive if they were not.</p>
319 </blockquote>
320 <h4 class="mansect"><a name="tag_20_03_11" id="tag_20_03_11"></a>STDERR</h4>
321 <blockquote>
322 <p>The standard error shall be used only for diagnostic messages. The diagnostic message about creating a new archive when
323 <b>-c</b> is not specified shall not modify the exit status.</p>
324 </blockquote>
325 <h4 class="mansect"><a name="tag_20_03_12" id="tag_20_03_12"></a>OUTPUT FILES</h4>
326 <blockquote>
327 <p>Archives are files with unspecified formats.</p>
328 </blockquote>
329 <h4 class="mansect"><a name="tag_20_03_13" id="tag_20_03_13"></a>EXTENDED DESCRIPTION</h4>
330 <blockquote>
331 <p>None.</p>
332 </blockquote>
333 <h4 class="mansect"><a name="tag_20_03_14" id="tag_20_03_14"></a>EXIT STATUS</h4>
334 <blockquote>
335 <p>The following exit values shall be returned:</p>
336 <dl compact>
337 <dd></dd>
338 <dt> 0</dt>
339 <dd>Successful completion.</dd>
340 <dt>>0</dt>
341 <dd>An error occurred.</dd>
342 </dl>
343 </blockquote>
344 <h4 class="mansect"><a name="tag_20_03_15" id="tag_20_03_15"></a>CONSEQUENCES OF ERRORS</h4>
345 <blockquote>
346 <p>Default.</p>
347 </blockquote>
348 <hr>
349 <div class="box"><em>The following sections are informative.</em></div>
350 <h4 class="mansect"><a name="tag_20_03_16" id="tag_20_03_16"></a>APPLICATION USAGE</h4>
351 <blockquote>
352 <p>None.</p>
353 </blockquote>
354 <h4 class="mansect"><a name="tag_20_03_17" id="tag_20_03_17"></a>EXAMPLES</h4>
355 <blockquote>
356 <p>None.</p>
357 </blockquote>
358 <h4 class="mansect"><a name="tag_20_03_18" id="tag_20_03_18"></a>RATIONALE</h4>
359 <blockquote>
360 <p>The archive format is not described. It is recognized that there are several known <i>ar</i> formats, which are not compatible.
361 The <i>ar</i> utility is included, however, to allow creation of archives that are intended for use only on one machine. The
362 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
363 machine that uses the same implementation of <i>ar</i>.</p>
364 <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
365 portable "archives". This is a not a duplication; the <i>ar</i> utility is included to provide an interface primarily for
366 <a href="../utilities/make.html"><i>make</i></a> and the compilers, based on a historical model.</p>
367 <p>In historical implementations, the <b>-q</b> option (available on XSI-conforming systems) is known to execute quickly because
368 <i>ar</i> does not check on whether the added members are already in the archive. This is useful to bypass the searching otherwise
369 done when creating a large archive piece-by-piece. These remarks may but need not remain true for a brand new implementation of
370 this utility; hence, these remarks have been moved into the RATIONALE.</p>
371 <p>BSD implementations historically required applications to provide the <b>-s</b> option whenever the archive was supposed to
372 contain a symbol table. As in this volume of POSIX.1-2024, System V historically creates or updates an archive symbol table
373 whenever an object file is removed from, added to, or updated in the archive.</p>
374 <p>The OPERANDS section requires what might seem to be true without specifying it: the archive cannot truncate the filenames below
375 {NAME_MAX}. Some historical implementations do so, however, causing unexpected results for the application. Therefore, this volume
376 of POSIX.1-2024 makes the requirement explicit to avoid misunderstandings.</p>
377 <p>According to the System V documentation, the options <b>-dmpqrtx</b> are not required to begin with a <hyphen-minus>
378 (<tt>'-'</tt>). This volume of POSIX.1-2024 requires that a conforming application use the leading <hyphen-minus>.</p>
379 <p>The archive format used by the 4.4 BSD implementation is documented in this RATIONALE as an example:</p>
380 <blockquote>A file created by <i>ar</i> begins with the "magic" string <tt>"!<arch>\n"</tt>. The rest of the archive is
381 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
382 portable between machine architectures, and, if the file contents are printable, the archive is itself printable.
383 <p>The header is made up of six ASCII fields, followed by a two-character trailer. The fields are the object name (16 characters),
384 the file last modification time (12 characters), the user and group IDs (each 6 characters), the file mode (8 characters), and the
385 file size (10 characters). All numeric fields are in decimal, except for the file mode, which is in octal.</p>
386 <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>
387 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
388 string <tt>"`<newline>"</tt>.</p>
389 <p>Only the name field has any provision for overflow. If any filename is more than 16 characters in length or contains an embedded
390 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
391 the archive header) is incremented by the length of the name. The name is then written immediately following the archive
392 header.</p>
393 <p>Any unused characters in any of these fields are written as <space> characters. If any fields are their particular maximum
394 number of characters in length, there is no separation between the fields.</p>
395 <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
396 <newline>, although the size in the header does not reflect this.</p>
397 </blockquote>
398 <p>The <i>ar</i> utility description requires that (when all its members are valid object files) <i>ar</i> produce an object code
399 library, which the linkage editor can use to extract object modules. If the linkage editor needs a symbol table to permit random
400 access to the archive, <i>ar</i> must provide it; however, <i>ar</i> does not require a symbol table.</p>
401 <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
402 library with concern for its modification time, since this can only be of importance to <a href=
403 "../utilities/make.html"><i>make</i></a>. Hence, since this functionality is not deemed important for applications portability, the
404 modification time of the extracted files is set to the current time.</p>
405 <p>There is at least one known implementation (for a small computer) that can accommodate only object files for that system,
406 disallowing mixed object and other files. The ability to handle any type of file is not only historical practice for most
407 implementations, but is also a reasonable expectation.</p>
408 <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=
409 "../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=
410 "../utilities/ls.html"><i>ls</i></a>. This was rejected in part because the current <i>ar</i> format is commonly used and changes
411 would break historical usage. Second, <i>ar</i> gives the user ID and group ID in numeric format separated by a <slash>.
412 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
413 different user database. Since <i>ar</i> cannot know whether the archive was generated on the same machine, it cannot tell what to
414 report.</p>
415 <p>The text on the <b>-ur</b> option combination is historical practice—since one filename can easily represent two different files
416 (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
417 in the archive is identical to that in the file system.</p>
418 </blockquote>
419 <h4 class="mansect"><a name="tag_20_03_19" id="tag_20_03_19"></a>FUTURE DIRECTIONS</h4>
420 <blockquote>
421 <p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline>
422 character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to
423 treat this as an error. A future version of this standard may require implementations to treat this as an error.</p>
424 <p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a
425 <newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require
426 implementations to treat this as an error.</p>
427 </blockquote>
428 <h4 class="mansect"><a name="tag_20_03_20" id="tag_20_03_20"></a>SEE ALSO</h4>
429 <blockquote>
430 <p><a href="../utilities/c17.html#"><i>c17</i></a> , <a href="../utilities/date.html#"><i>date</i></a> , <a href=
431 "../utilities/pax.html#"><i>pax</i></a> , <a href="../utilities/strip.html#"><i>strip</i></a></p>
432 <p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href=
433 "../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a> , <a href=
434 "../basedefs/unistd.h.html"><i><unistd.h></i></a> , description of {POSIX_NO_TRUNC}</p>
435 </blockquote>
436 <h4 class="mansect"><a name="tag_20_03_21" id="tag_20_03_21"></a>CHANGE HISTORY</h4>
437 <blockquote>
438 <p>First released in Issue 2.</p>
439 </blockquote>
440 <h4 class="mansect"><a name="tag_20_03_22" id="tag_20_03_22"></a>Issue 5</h4>
441 <blockquote>
442 <p>The FUTURE DIRECTIONS section is added.</p>
443 </blockquote>
444 <h4 class="mansect"><a name="tag_20_03_23" id="tag_20_03_23"></a>Issue 6</h4>
445 <blockquote>
446 <p>This utility is marked as part of the Software Development Utilities option.</p>
447 <p>The STDOUT description is changed for the <b>-v</b> option to align with the IEEE P1003.2b draft standard.</p>
448 <p>The normative text is reworded to avoid use of the term "must" for application requirements.</p>
449 <p>The <i>TZ</i> entry is added to the ENVIRONMENT VARIABLES section.</p>
450 <p>IEEE PASC Interpretation 1003.2 #198 is applied, changing the description to consistently use "file" to refer to a file in the
451 file system hierarchy, "archive" to refer to the archive being operated upon by the <i>ar</i> utility, and "file in the
452 archive" to refer to a copy of a file that is contained in the archive.</p>
453 <p>IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/10 is applied, making corrections to the SYNOPSIS. The change
454 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
455 these options is specified.</p>
456 <p>IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/11 is applied, correcting the description of the two-byte
457 trailer in RATIONALE which had missed out a backquote. The correct trailer is a backquote followed by a <newline>.</p>
458 </blockquote>
459 <h4 class="mansect"><a name="tag_20_03_24" id="tag_20_03_24"></a>Issue 7</h4>
460 <blockquote>
461 <p>SD5-XCU-ERN-6 is applied, clarifying that Guideline 9 of the Utility Syntax Guidelines does not apply.</p>
462 <p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p>
463 <p>The description of the <b>-t</b> option is changed to say "Only the files specified ...".</p>
464 <p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0057 [584] is applied.</p>
465 </blockquote>
466 <h4 class="mansect"><a name="tag_20_03_25" id="tag_20_03_25"></a>Issue 8</h4>
467 <blockquote>
468 <p>Austin Group Defect 251 is applied, encouraging implementations to behave as follows:</p>
469 <ol type="a">
470 <li>
471 <p>Report an error if a utility is directed to display a pathname that contains any bytes that have the encoded value of a
472 <newline> character when <newline> is a terminator or separator in the output format being used.</p>
473 </li>
474 <li>
475 <p>Disallow the creation of filenames containing any bytes that have the encoded value of a <newline> character.</p>
476 </li>
477 </ol>
478 <p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p>
479 <p>Austin Group Defect 1330 is applied, removing obsolescent interfaces.</p>
480 </blockquote>
481 <div class="box"><em>End of informative text.</em></div>
482 <hr>
483 <p> </p>
484 <a href="#top"><span class="topOfPage">return to top of page</span></a><br>
485 <hr size="2" noshade>
486 <center><font size="2">UNIX® is a registered Trademark of The Open Group.<br>
487 POSIX™ is a Trademark of The IEEE.<br>
488 Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br>
489 [ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
490 "../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a>
491 ]</font></center>
492 <hr size="2" noshade>
493 <div class="NAVHEADER">
494 <table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0">
495 <tr class="nav">
496 <td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/alias.html" accesskey="P"><<<
497 Previous</a></td>
498 <td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td>
499 <td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/asa.html" accesskey="N">Next >>></a></td>
500 </tr>
501 </table>
502 <hr align="left" width="100%"></div>
503 </body>
504 </html>