1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
|
<table class="head">
<tr>
<td class="head-ltitle">AR(5)</td>
<td class="head-vol">File Formats Manual</td>
<td class="head-rtitle">AR(5)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">ar</code> — <span class="Nd">archive file
format for <a class="Xr">ar(1)</a> and
<a class="Xr">ranlib(1)</a></span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="In">#include
<<a class="In">ar.h</a>></code></p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp"><a class="Xr">ar(1)</a> archives are created and managed by the
<a class="Xr">ar(1)</a> and <a class="Xr">ranlib(1)</a> utilities. These
archives are typically used during program development to hold libraries of
program objects. An <a class="Xr">ar(1)</a> archive is contained in a single
operating system file.</p>
<p class="Pp">This manual page documents two variants of the
<a class="Xr">ar(1)</a> archive format: the BSD archive format, and the
SVR4/GNU archive format.</p>
<p class="Pp">In both variants the archive file starts with an identifying byte
sequence of the seven ASCII characters
‘<code class="Li">!<arch></code>’ followed by a ASCII
linefeed character (see the constant “ARMAG” in the header
file <code class="In"><<a class="In">ar.h</a>></code>).</p>
<p class="Pp">Archive members follow the initial identifying byte sequence. Each
archive member is prefixed by a fixed size header describing the file
attributes associated with the member.</p>
<section class="Ss">
<h2 class="Ss" id="Archive_Headers"><a class="permalink" href="#Archive_Headers">Archive
Headers</a></h2>
<p class="Pp">An archive header describes the file attributes for the archive
member that follows it. The <code class="Nm">ar</code> format only supports
a limited number of attributes: the file name, the file creation time stamp,
the uid and gid of the creator, the file mode and the file size.</p>
<p class="Pp">Archive headers are placed at an even byte offset in the archive
file. If the data for an archive member ends at an odd byte offset, then a
padding byte with value 0x0A is used to position the next archive header on
an even byte offset.</p>
<p class="Pp">An archive header comprises the following fixed sized fields:</p>
<dl class="Bl-tag">
<dt><var class="Ar">ar_name</var></dt>
<dd>(16 bytes) The file name of the archive member. The format of this field
varies between the BSD and SVR4/GNU formats and is described in more
detail in the section
<a class="Sx" href="#Representing_File_Names">Representing File Names</a>
below.</dd>
<dt><var class="Ar">ar_date</var></dt>
<dd>(12 bytes) The file modification time for the member in seconds since the
epoch, encoded as a decimal number.</dd>
<dt><var class="Ar">ar_uid</var></dt>
<dd>(6 bytes) The uid associated with the archive member, encoded as a decimal
number.</dd>
<dt><var class="Ar">ar_gid</var></dt>
<dd>(6 bytes) The gid associated with the archive member, encoded as a decimal
number.</dd>
<dt><var class="Ar">ar_mode</var></dt>
<dd>(8 bytes) The file mode for the archive member, encoded as an octal
number.</dd>
<dt><var class="Ar">ar_size</var></dt>
<dd>(10 bytes) In the SVR4/GNU archive format this field holds the size in
bytes of the archive member, encoded as a decimal number. In the BSD
archive format, for short file names, this field holds the size in bytes
of the archive member, encoded as a decimal number. For long file names
(see <a class="Sx" href="#Representing_File_Names">Representing File
Names</a> below), the field contains the combined size of the archive
member and its file name, encoded as a decimal number.</dd>
<dt><var class="Ar">ar_fmag</var></dt>
<dd>(2 bytes) This field holds 2 bytes with values 0x96 and 0x0A respectively,
marking the end of the header.</dd>
</dl>
<p class="Pp">Unused bytes in the fields of an archive header are set to the
value 0x20.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Representing_File_Names"><a class="permalink" href="#Representing_File_Names">Representing
File Names</a></h2>
<p class="Pp">The BSD and SVR4/GNU variants use different schemes for encoding
file names for members.</p>
<dl class="Bl-tag">
<dt>BSD</dt>
<dd>File names that are up to 16 bytes long and which do not contain embedded
spaces are stored directly in the <var class="Ar">ar_name</var> field of
the archive header. File names that are either longer than 16 bytes or
which contain embedded spaces are stored immediately after the archive
header and the <var class="Ar">ar_name</var> field of the archive header
is set to the string “#1/” followed by a decimal
representation of the number of bytes needed for the file name. In
addition, the <var class="Ar">ar_size</var> field of the archive header is
set to the decimal representation of the combined sizes of the archive
member and the file name. The file contents of the member follows the file
name without further padding.
<p class="Pp">As an example, if the file name for a member was “A
B” and its contents was the string “C D”, then the
<var class="Ar">ar_name</var> field of the header would contain
“<code class="Li">#1/3</code>”, the
<var class="Ar">ar_size</var> field of the header would contain
“<code class="Li">6</code>”, and the bytes immediately
following the header would be 0x41, 0x20, 0x42, 0x43, 0x20 and 0x44
(ASCII “A BC D”).</p>
</dd>
<dt>SVR4/GNU</dt>
<dd>File names that are up to 15 characters long are stored directly in the
<var class="Ar">ar_name</var> field of the header, terminated by a
“<code class="Li">/</code>” character.
<p class="Pp">If the file name is larger than would fit in space for the
<var class="Ar">ar_name</var> field, then the actual file name is kept
in the archive string table (see
<a class="Sx" href="#Archive_String_Tables">Archive String Tables</a>
below), and the decimal offset of the file name in the string table is
stored in the <var class="Ar">ar_name</var> field, prefixed by a
“<code class="Li">/</code>” character.</p>
<p class="Pp">As an example, if the real file name has been stored at offset
768 in the archive string table, the <var class="Ar">ar_name</var> field
of the header will contain the string “/768”.</p>
</dd>
</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="Special_Archive_Members"><a class="permalink" href="#Special_Archive_Members">Special
Archive Members</a></h2>
<p class="Pp">The following archive members are special.</p>
<dl class="Bl-tag">
<dt>“<code class="Li">/</code>”</dt>
<dd>In the SVR4/GNU variant of the archive format, the archive member with
name “<code class="Li">/</code>” denotes an archive symbol
table. If present, this member will be the very first member in the
archive.</dd>
<dt>“<code class="Li">//</code>”</dt>
<dd>In the SVR4/GNU variant of the archive format, the archive member with
name “<code class="Li">//</code>” denotes the archive string
table. This special member is used to hold filenames that do not fit in
the file name field of the header (see
<a class="Sx" href="#Representing_File_Names">Representing File Names</a>
above). If present, this member immediately follows the archive symbol
table if an archive symbol table is present, or is the first member
otherwise.</dd>
<dt>“<code class="Li">__.SYMDEF</code>”</dt>
<dd>This special member contains the archive symbol table in the BSD variant
of the archive format. If present, this member will be the very first
member in the archive.</dd>
</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="Archive_String_Tables"><a class="permalink" href="#Archive_String_Tables">Archive
String Tables</a></h2>
<p class="Pp">An archive string table is used in the SVR4/GNU archive format to
hold file names that are too large to fit into the constraints of the
<var class="Ar">ar_name</var> field of the archive header. An archive string
table contains a sequence of file names. Each file name in the archive
string table is terminated by the byte sequence 0x2F, 0x0A (the ASCII string
“/\n”). No padding is used to separate adjacent file
names.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Archive_Symbol_Tables"><a class="permalink" href="#Archive_Symbol_Tables">Archive
Symbol Tables</a></h2>
<p class="Pp">Archive symbol tables are used to speed up link editing by
providing a mapping between the program symbols defined in the archive and
the corresponding archive members. Archive symbol tables are managed by the
<a class="Xr">ranlib(1)</a> utility.</p>
<p class="Pp">The format of archive symbol tables is as follows:</p>
<dl class="Bl-tag">
<dt>BSD</dt>
<dd>In the BSD archive format, the archive symbol table comprises of two
parts: a part containing an array of <var class="Vt">struct ranlib</var>
descriptors, followed by a part containing a symbol string table. The
sizes and layout of the structures that make up a BSD format archive
symbol table are machine dependent.
<p class="Pp">The part containing <var class="Vt">struct ranlib</var>
descriptors begins with a field containing the size in bytes of the
array of <var class="Vt">struct ranlib</var> descriptors encoded as a C
<var class="Vt">long</var> value.</p>
<p class="Pp">The array of <var class="Vt">struct ranlib</var> descriptors
follows the size field. Each <var class="Vt">struct ranlib</var>
descriptor describes one symbol.</p>
<p class="Pp">A <var class="Vt">struct ranlib</var> descriptor comprises two
fields:</p>
<dl class="Bl-tag Bl-compact">
<dt><var class="Ar">ran_strx</var></dt>
<dd>(C <var class="Vt">long</var>) This field contains the zero-based
offset of the symbol name in the symbol string table.</dd>
<dt><var class="Ar">ran_off</var></dt>
<dd>(C <var class="Vt">long</var>) This field is the file offset to the
archive header for the archive member defining the symbol.</dd>
</dl>
<p class="Pp">The part containing the symbol string table begins with a
field containing the size in bytes of the string table, encoded as a C
<var class="Vt">long</var> value. This string table follows the size
field, and contains NUL-terminated strings for the symbols in the symbol
table.</p>
</dd>
<dt>SVR4/GNU</dt>
<dd>In the SVR4/GNU archive format, the archive symbol table starts with a
4-byte binary value containing the number of entries contained in the
archive symbol table. This count of entries is stored most significant
byte first.
<p class="Pp">Next, there are <var class="Ar">count</var> 4-byte numbers,
each stored most significant byte first. Each number is a binary offset
to the archive header for the member in the archive file for the
corresponding symbol table entry.</p>
<p class="Pp">After the binary offset values, there are
<var class="Ar">count</var> NUL-terminated strings in sequence, holding
the symbol names for the corresponding symbol table entries.</p>
</dd>
</dl>
</section>
</section>
<section class="Sh">
<h1 class="Sh" id="STANDARDS_COMPLIANCE"><a class="permalink" href="#STANDARDS_COMPLIANCE">STANDARDS
COMPLIANCE</a></h1>
<p class="Pp">The <a class="Xr">ar(1)</a> archive format is not currently
specified by a standard.</p>
<p class="Pp">This manual page documents the <a class="Xr">ar(1)</a> archive
formats used by the <span class="Ux">4.4BSD</span> and
<span class="Ux">UNIX</span> SVR4 operating system releases.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">ar(1)</a>, <a class="Xr">ld(1)</a>,
<a class="Xr">ranlib(1)</a>, <a class="Xr">elf(3)</a>,
<a class="Xr">elf_getarsym(3)</a>, <a class="Xr">elf_rand(3)</a></p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">November 28, 2010</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
