]>
Commit | Line | Data |
---|---|---|
223e47cc LB |
1 | llvm-ar - LLVM archiver |
2 | ======================= | |
3 | ||
4 | ||
5 | SYNOPSIS | |
6 | -------- | |
7 | ||
8 | ||
9 | **llvm-ar** [-]{dmpqrtx}[Rabfikou] [relpos] [count] <archive> [files...] | |
10 | ||
11 | ||
12 | DESCRIPTION | |
13 | ----------- | |
14 | ||
15 | ||
16 | The **llvm-ar** command is similar to the common Unix utility, ``ar``. It | |
17 | archives several files together into a single file. The intent for this is | |
18 | to produce archive libraries by LLVM bitcode that can be linked into an | |
19 | LLVM program. However, the archive can contain any kind of file. By default, | |
20 | **llvm-ar** generates a symbol table that makes linking faster because | |
21 | only the symbol table needs to be consulted, not each individual file member | |
22 | of the archive. | |
23 | ||
1a4d82fc JJ |
24 | The **llvm-ar** command can be used to *read* SVR4, GNU and BSD style archive |
25 | files. However, right now it can only write in the GNU format. If an | |
223e47cc | 26 | SVR4 or BSD style archive is used with the ``r`` (replace) or ``q`` (quick |
1a4d82fc | 27 | update) operations, the archive will be reconstructed in GNU format. |
223e47cc LB |
28 | |
29 | Here's where **llvm-ar** departs from previous ``ar`` implementations: | |
30 | ||
31 | ||
32 | *Symbol Table* | |
33 | ||
1a4d82fc JJ |
34 | Since **llvm-ar** supports bitcode files. The symbol table it creates |
35 | is in GNU format and includes both native and bitcode files. | |
223e47cc LB |
36 | |
37 | ||
38 | *Long Paths* | |
39 | ||
1a4d82fc JJ |
40 | Currently **llvm-ar** can read GNU and BSD long file names, but only writes |
41 | archives with the GNU format. | |
223e47cc LB |
42 | |
43 | ||
44 | ||
45 | OPTIONS | |
46 | ------- | |
47 | ||
48 | ||
49 | The options to **llvm-ar** are compatible with other ``ar`` implementations. | |
50 | However, there are a few modifiers (*R*) that are not found in other ``ar`` | |
51 | implementations. The options to **llvm-ar** specify a single basic operation to | |
52 | perform on the archive, a variety of modifiers for that operation, the name of | |
53 | the archive file, and an optional list of file names. These options are used to | |
54 | determine how **llvm-ar** should process the archive file. | |
55 | ||
56 | The Operations and Modifiers are explained in the sections below. The minimal | |
57 | set of options is at least one operator and the name of the archive. Typically | |
58 | archive files end with a ``.a`` suffix, but this is not required. Following | |
59 | the *archive-name* comes a list of *files* that indicate the specific members | |
60 | of the archive to operate on. If the *files* option is not specified, it | |
61 | generally means either "none" or "all" members, depending on the operation. | |
62 | ||
63 | Operations | |
64 | ~~~~~~~~~~ | |
65 | ||
66 | ||
67 | ||
68 | d | |
69 | ||
70 | Delete files from the archive. No modifiers are applicable to this operation. | |
71 | The *files* options specify which members should be removed from the | |
72 | archive. It is not an error if a specified file does not appear in the archive. | |
73 | If no *files* are specified, the archive is not modified. | |
74 | ||
75 | ||
76 | ||
77 | m[abi] | |
78 | ||
79 | Move files from one location in the archive to another. The *a*, *b*, and | |
80 | *i* modifiers apply to this operation. The *files* will all be moved | |
81 | to the location given by the modifiers. If no modifiers are used, the files | |
82 | will be moved to the end of the archive. If no *files* are specified, the | |
83 | archive is not modified. | |
84 | ||
85 | ||
86 | ||
1a4d82fc | 87 | p |
223e47cc | 88 | |
1a4d82fc JJ |
89 | Print files to the standard output. This operation simply prints the |
90 | *files* indicated to the standard output. If no *files* are | |
91 | specified, the entire archive is printed. Printing bitcode files is | |
92 | ill-advised as they might confuse your terminal settings. The *p* | |
93 | operation never modifies the archive. | |
223e47cc LB |
94 | |
95 | ||
96 | ||
1a4d82fc | 97 | q |
223e47cc | 98 | |
1a4d82fc | 99 | Quickly append files to the end of the archive. This operation quickly adds the |
223e47cc LB |
100 | *files* to the archive without checking for duplicates that should be |
101 | removed first. If no *files* are specified, the archive is not modified. | |
102 | Because of the way that **llvm-ar** constructs the archive file, its dubious | |
103 | whether the *q* operation is any faster than the *r* operation. | |
104 | ||
105 | ||
106 | ||
1a4d82fc | 107 | r[abu] |
223e47cc | 108 | |
1a4d82fc | 109 | Replace or insert file members. The *a*, *b*, and *u* |
223e47cc LB |
110 | modifiers apply to this operation. This operation will replace existing |
111 | *files* or insert them at the end of the archive if they do not exist. If no | |
112 | *files* are specified, the archive is not modified. | |
113 | ||
114 | ||
115 | ||
116 | t[v] | |
117 | ||
118 | Print the table of contents. Without any modifiers, this operation just prints | |
119 | the names of the members to the standard output. With the *v* modifier, | |
120 | **llvm-ar** also prints out the file type (B=bitcode, S=symbol | |
121 | table, blank=regular file), the permission mode, the owner and group, the | |
122 | size, and the date. If any *files* are specified, the listing is only for | |
123 | those files. If no *files* are specified, the table of contents for the | |
124 | whole archive is printed. | |
125 | ||
126 | ||
127 | ||
128 | x[oP] | |
129 | ||
130 | Extract archive members back to files. The *o* modifier applies to this | |
131 | operation. This operation retrieves the indicated *files* from the archive | |
132 | and writes them back to the operating system's file system. If no | |
133 | *files* are specified, the entire archive is extract. | |
134 | ||
135 | ||
136 | ||
137 | ||
138 | Modifiers (operation specific) | |
139 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
140 | ||
141 | ||
142 | The modifiers below are specific to certain operations. See the Operations | |
143 | section (above) to determine which modifiers are applicable to which operations. | |
144 | ||
145 | ||
146 | [a] | |
147 | ||
148 | When inserting or moving member files, this option specifies the destination of | |
149 | the new files as being after the *relpos* member. If *relpos* is not found, | |
150 | the files are placed at the end of the archive. | |
151 | ||
152 | ||
153 | ||
154 | [b] | |
155 | ||
156 | When inserting or moving member files, this option specifies the destination of | |
157 | the new files as being before the *relpos* member. If *relpos* is not | |
158 | found, the files are placed at the end of the archive. This modifier is | |
159 | identical to the *i* modifier. | |
160 | ||
161 | ||
162 | ||
223e47cc LB |
163 | [i] |
164 | ||
165 | A synonym for the *b* option. | |
166 | ||
167 | ||
168 | ||
223e47cc LB |
169 | [o] |
170 | ||
171 | When extracting files, this option will cause **llvm-ar** to preserve the | |
172 | original modification times of the files it writes. | |
173 | ||
174 | ||
175 | ||
223e47cc LB |
176 | [u] |
177 | ||
178 | When replacing existing files in the archive, only replace those files that have | |
179 | a time stamp than the time stamp of the member in the archive. | |
180 | ||
181 | ||
182 | ||
183 | ||
184 | Modifiers (generic) | |
185 | ~~~~~~~~~~~~~~~~~~~ | |
186 | ||
187 | ||
188 | The modifiers below may be applied to any operation. | |
189 | ||
190 | ||
191 | [c] | |
192 | ||
193 | For all operations, **llvm-ar** will always create the archive if it doesn't | |
194 | exist. Normally, **llvm-ar** will print a warning message indicating that the | |
195 | archive is being created. Using this modifier turns off that warning. | |
196 | ||
197 | ||
198 | ||
199 | [s] | |
200 | ||
201 | This modifier requests that an archive index (or symbol table) be added to the | |
202 | archive. This is the default mode of operation. The symbol table will contain | |
203 | all the externally visible functions and global variables defined by all the | |
1a4d82fc | 204 | bitcode files in the archive. |
223e47cc LB |
205 | |
206 | ||
207 | ||
208 | [S] | |
209 | ||
210 | This modifier is the opposite of the *s* modifier. It instructs **llvm-ar** to | |
211 | not build the symbol table. If both *s* and *S* are used, the last modifier to | |
212 | occur in the options will prevail. | |
213 | ||
214 | ||
215 | ||
216 | [v] | |
217 | ||
218 | This modifier instructs **llvm-ar** to be verbose about what it is doing. Each | |
219 | editing operation taken against the archive will produce a line of output saying | |
220 | what is being done. | |
221 | ||
222 | ||
223 | ||
224 | ||
225 | ||
226 | STANDARDS | |
227 | --------- | |
228 | ||
229 | ||
230 | The **llvm-ar** utility is intended to provide a superset of the IEEE Std 1003.2 | |
231 | (POSIX.2) functionality for ``ar``. **llvm-ar** can read both SVR4 and BSD4.4 (or | |
232 | Mac OS X) archives. If the ``f`` modifier is given to the ``x`` or ``r`` operations | |
233 | then **llvm-ar** will write SVR4 compatible archives. Without this modifier, | |
234 | **llvm-ar** will write BSD4.4 compatible archives that have long names | |
235 | immediately after the header and indicated using the "#1/ddd" notation for the | |
236 | name in the header. | |
237 | ||
238 | ||
239 | FILE FORMAT | |
240 | ----------- | |
241 | ||
242 | ||
243 | The file format for LLVM Archive files is similar to that of BSD 4.4 or Mac OSX | |
244 | archive files. In fact, except for the symbol table, the ``ar`` commands on those | |
245 | operating systems should be able to read LLVM archive files. The details of the | |
246 | file format follow. | |
247 | ||
248 | Each archive begins with the archive magic number which is the eight printable | |
249 | characters "!<arch>\n" where \n represents the newline character (0x0A). | |
250 | Following the magic number, the file is composed of even length members that | |
251 | begin with an archive header and end with a \n padding character if necessary | |
252 | (to make the length even). Each file member is composed of a header (defined | |
253 | below), an optional newline-terminated "long file name" and the contents of | |
254 | the file. | |
255 | ||
256 | The fields of the header are described in the items below. All fields of the | |
257 | header contain only ASCII characters, are left justified and are right padded | |
258 | with space characters. | |
259 | ||
260 | ||
261 | name - char[16] | |
262 | ||
263 | This field of the header provides the name of the archive member. If the name is | |
264 | longer than 15 characters or contains a slash (/) character, then this field | |
265 | contains ``#1/nnn`` where ``nnn`` provides the length of the name and the ``#1/`` | |
266 | is literal. In this case, the actual name of the file is provided in the ``nnn`` | |
267 | bytes immediately following the header. If the name is 15 characters or less, it | |
268 | is contained directly in this field and terminated with a slash (/) character. | |
269 | ||
270 | ||
271 | ||
272 | date - char[12] | |
273 | ||
274 | This field provides the date of modification of the file in the form of a | |
275 | decimal encoded number that provides the number of seconds since the epoch | |
276 | (since 00:00:00 Jan 1, 1970) per Posix specifications. | |
277 | ||
278 | ||
279 | ||
280 | uid - char[6] | |
281 | ||
282 | This field provides the user id of the file encoded as a decimal ASCII string. | |
283 | This field might not make much sense on non-Unix systems. On Unix, it is the | |
284 | same value as the st_uid field of the stat structure returned by the stat(2) | |
285 | operating system call. | |
286 | ||
287 | ||
288 | ||
289 | gid - char[6] | |
290 | ||
291 | This field provides the group id of the file encoded as a decimal ASCII string. | |
292 | This field might not make much sense on non-Unix systems. On Unix, it is the | |
293 | same value as the st_gid field of the stat structure returned by the stat(2) | |
294 | operating system call. | |
295 | ||
296 | ||
297 | ||
298 | mode - char[8] | |
299 | ||
300 | This field provides the access mode of the file encoded as an octal ASCII | |
301 | string. This field might not make much sense on non-Unix systems. On Unix, it | |
302 | is the same value as the st_mode field of the stat structure returned by the | |
303 | stat(2) operating system call. | |
304 | ||
305 | ||
306 | ||
307 | size - char[10] | |
308 | ||
309 | This field provides the size of the file, in bytes, encoded as a decimal ASCII | |
310 | string. | |
311 | ||
312 | ||
313 | ||
314 | fmag - char[2] | |
315 | ||
316 | This field is the archive file member magic number. Its content is always the | |
317 | two characters back tick (0x60) and newline (0x0A). This provides some measure | |
318 | utility in identifying archive files that have been corrupted. | |
319 | ||
320 | ||
223e47cc LB |
321 | offset - vbr encoded 32-bit integer |
322 | ||
323 | The offset item provides the offset into the archive file where the bitcode | |
324 | member is stored that is associated with the symbol. The offset value is 0 | |
325 | based at the start of the first "normal" file member. To derive the actual | |
326 | file offset of the member, you must add the number of bytes occupied by the file | |
327 | signature (8 bytes) and the symbol tables. The value of this item is encoded | |
328 | using variable bit rate encoding to reduce the size of the symbol table. | |
329 | Variable bit rate encoding uses the high bit (0x80) of each byte to indicate | |
330 | if there are more bytes to follow. The remaining 7 bits in each byte carry bits | |
331 | from the value. The final byte does not have the high bit set. | |
332 | ||
333 | ||
334 | ||
335 | length - vbr encoded 32-bit integer | |
336 | ||
337 | The length item provides the length of the symbol that follows. Like this | |
338 | *offset* item, the length is variable bit rate encoded. | |
339 | ||
340 | ||
341 | ||
342 | symbol - character array | |
343 | ||
344 | The symbol item provides the text of the symbol that is associated with the | |
345 | *offset*. The symbol is not terminated by any character. Its length is provided | |
346 | by the *length* field. Note that is allowed (but unwise) to use non-printing | |
347 | characters (even 0x00) in the symbol. This allows for multiple encodings of | |
348 | symbol names. | |
349 | ||
350 | ||
351 | ||
352 | ||
353 | EXIT STATUS | |
354 | ----------- | |
355 | ||
356 | ||
357 | If **llvm-ar** succeeds, it will exit with 0. A usage error, results | |
358 | in an exit code of 1. A hard (file system typically) error results in an | |
359 | exit code of 2. Miscellaneous or unknown errors result in an | |
360 | exit code of 3. | |
361 | ||
362 | ||
363 | SEE ALSO | |
364 | -------- | |
365 | ||
366 | ||
1a4d82fc | 367 | ar(1) |