1 llvm-ar - LLVM archiver
2 =======================
9 **llvm-ar** [-]{dmpqrtx}[Rabfikou] [relpos] [count] <archive> [files...]
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
24 The **llvm-ar** command can be used to *read* both SVR4 and BSD style archive
25 files. However, it cannot be used to write them. While the **llvm-ar** command
26 produces files that are *almost* identical to the format used by other ``ar``
27 implementations, it has two significant departures in order to make the
28 archive appropriate for LLVM. The first departure is that **llvm-ar** only
29 uses BSD4.4 style long path names (stored immediately after the header) and
30 never contains a string table for long names. The second departure is that the
31 symbol table is formated for efficient construction of an in-memory data
32 structure that permits rapid (red-black tree) lookups. Consequently, archives
33 produced with **llvm-ar** usually won't be readable or editable with any
34 ``ar`` implementation or useful for linking. Using the ``f`` modifier to flatten
35 file names will make the archive readable by other ``ar`` implementations
36 but not for linking because the symbol table format for LLVM is unique. If an
37 SVR4 or BSD style archive is used with the ``r`` (replace) or ``q`` (quick
38 update) operations, the archive will be reconstructed in LLVM format. This
39 means that the string table will be dropped (in deference to BSD 4.4 long names)
40 and an LLVM symbol table will be added (by default). The system symbol table
43 Here's where **llvm-ar** departs from previous ``ar`` implementations:
48 Since **llvm-ar** is intended to archive bitcode files, the symbol table
49 won't make much sense to anything but LLVM. Consequently, the symbol table's
50 format has been simplified. It consists simply of a sequence of pairs
51 of a file member index number as an LSB 4byte integer and a null-terminated
58 Some ``ar`` implementations (SVR4) use a separate file member to record long
59 path names (> 15 characters). **llvm-ar** takes the BSD 4.4 and Mac OS X
60 approach which is to simply store the full path name immediately preceding
61 the data for the file. The path name is null terminated and may contain the
68 Most ``ar`` implementations do not recurse through directories but simply
69 ignore directories if they are presented to the program in the *files*
70 option. **llvm-ar**, however, can recurse through directory structures and
71 add all the files under a directory, if requested.
77 When **llvm-ar** prints out the verbose table of contents (``tv`` option), it
78 precedes the usual output with a character indicating the basic kind of
79 content in the file. A blank means the file is a regular file. A 'B' means
80 the file is an LLVM bitcode file. An 'S' means the file is the symbol table.
89 The options to **llvm-ar** are compatible with other ``ar`` implementations.
90 However, there are a few modifiers (*R*) that are not found in other ``ar``
91 implementations. The options to **llvm-ar** specify a single basic operation to
92 perform on the archive, a variety of modifiers for that operation, the name of
93 the archive file, and an optional list of file names. These options are used to
94 determine how **llvm-ar** should process the archive file.
96 The Operations and Modifiers are explained in the sections below. The minimal
97 set of options is at least one operator and the name of the archive. Typically
98 archive files end with a ``.a`` suffix, but this is not required. Following
99 the *archive-name* comes a list of *files* that indicate the specific members
100 of the archive to operate on. If the *files* option is not specified, it
101 generally means either "none" or "all" members, depending on the operation.
110 Delete files from the archive. No modifiers are applicable to this operation.
111 The *files* options specify which members should be removed from the
112 archive. It is not an error if a specified file does not appear in the archive.
113 If no *files* are specified, the archive is not modified.
119 Move files from one location in the archive to another. The *a*, *b*, and
120 *i* modifiers apply to this operation. The *files* will all be moved
121 to the location given by the modifiers. If no modifiers are used, the files
122 will be moved to the end of the archive. If no *files* are specified, the
123 archive is not modified.
129 Print files to the standard output. The *k* modifier applies to this
130 operation. This operation simply prints the *files* indicated to the
131 standard output. If no *files* are specified, the entire archive is printed.
132 Printing bitcode files is ill-advised as they might confuse your terminal
133 settings. The *p* operation never modifies the archive.
139 Quickly append files to the end of the archive. The *R*, and *f*
140 modifiers apply to this operation. This operation quickly adds the
141 *files* to the archive without checking for duplicates that should be
142 removed first. If no *files* are specified, the archive is not modified.
143 Because of the way that **llvm-ar** constructs the archive file, its dubious
144 whether the *q* operation is any faster than the *r* operation.
150 Replace or insert file members. The *R*, *a*, *b*, *f*, and *u*
151 modifiers apply to this operation. This operation will replace existing
152 *files* or insert them at the end of the archive if they do not exist. If no
153 *files* are specified, the archive is not modified.
159 Print the table of contents. Without any modifiers, this operation just prints
160 the names of the members to the standard output. With the *v* modifier,
161 **llvm-ar** also prints out the file type (B=bitcode, S=symbol
162 table, blank=regular file), the permission mode, the owner and group, the
163 size, and the date. If any *files* are specified, the listing is only for
164 those files. If no *files* are specified, the table of contents for the
165 whole archive is printed.
171 Extract archive members back to files. The *o* modifier applies to this
172 operation. This operation retrieves the indicated *files* from the archive
173 and writes them back to the operating system's file system. If no
174 *files* are specified, the entire archive is extract.
179 Modifiers (operation specific)
180 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
183 The modifiers below are specific to certain operations. See the Operations
184 section (above) to determine which modifiers are applicable to which operations.
189 When inserting or moving member files, this option specifies the destination of
190 the new files as being after the *relpos* member. If *relpos* is not found,
191 the files are placed at the end of the archive.
197 When inserting or moving member files, this option specifies the destination of
198 the new files as being before the *relpos* member. If *relpos* is not
199 found, the files are placed at the end of the archive. This modifier is
200 identical to the *i* modifier.
206 Normally, **llvm-ar** stores the full path name to a file as presented to it on
207 the command line. With this option, truncated (15 characters max) names are
208 used. This ensures name compatibility with older versions of ``ar`` but may also
209 thwart correct extraction of the files (duplicates may overwrite). If used with
210 the *R* option, the directory recursion will be performed but the file names
211 will all be flattened to simple file names.
217 A synonym for the *b* option.
223 Normally, **llvm-ar** will not print the contents of bitcode files when the
224 *p* operation is used. This modifier defeats the default and allows the
225 bitcode members to be printed.
231 This option is ignored by **llvm-ar** but provided for compatibility.
237 When extracting files, this option will cause **llvm-ar** to preserve the
238 original modification times of the files it writes.
244 use full path names when matching
250 This modifier instructions the *r* option to recursively process directories.
251 Without *R*, directories are ignored and only those *files* that refer to
252 files will be added to the archive. When *R* is used, any directories specified
253 with *files* will be scanned (recursively) to find files to be added to the
254 archive. Any file whose name begins with a dot will not be added.
260 When replacing existing files in the archive, only replace those files that have
261 a time stamp than the time stamp of the member in the archive.
270 The modifiers below may be applied to any operation.
275 For all operations, **llvm-ar** will always create the archive if it doesn't
276 exist. Normally, **llvm-ar** will print a warning message indicating that the
277 archive is being created. Using this modifier turns off that warning.
283 This modifier requests that an archive index (or symbol table) be added to the
284 archive. This is the default mode of operation. The symbol table will contain
285 all the externally visible functions and global variables defined by all the
286 bitcode files in the archive.
292 This modifier is the opposite of the *s* modifier. It instructs **llvm-ar** to
293 not build the symbol table. If both *s* and *S* are used, the last modifier to
294 occur in the options will prevail.
300 This modifier instructs **llvm-ar** to be verbose about what it is doing. Each
301 editing operation taken against the archive will produce a line of output saying
312 The **llvm-ar** utility is intended to provide a superset of the IEEE Std 1003.2
313 (POSIX.2) functionality for ``ar``. **llvm-ar** can read both SVR4 and BSD4.4 (or
314 Mac OS X) archives. If the ``f`` modifier is given to the ``x`` or ``r`` operations
315 then **llvm-ar** will write SVR4 compatible archives. Without this modifier,
316 **llvm-ar** will write BSD4.4 compatible archives that have long names
317 immediately after the header and indicated using the "#1/ddd" notation for the
325 The file format for LLVM Archive files is similar to that of BSD 4.4 or Mac OSX
326 archive files. In fact, except for the symbol table, the ``ar`` commands on those
327 operating systems should be able to read LLVM archive files. The details of the
330 Each archive begins with the archive magic number which is the eight printable
331 characters "!<arch>\n" where \n represents the newline character (0x0A).
332 Following the magic number, the file is composed of even length members that
333 begin with an archive header and end with a \n padding character if necessary
334 (to make the length even). Each file member is composed of a header (defined
335 below), an optional newline-terminated "long file name" and the contents of
338 The fields of the header are described in the items below. All fields of the
339 header contain only ASCII characters, are left justified and are right padded
340 with space characters.
345 This field of the header provides the name of the archive member. If the name is
346 longer than 15 characters or contains a slash (/) character, then this field
347 contains ``#1/nnn`` where ``nnn`` provides the length of the name and the ``#1/``
348 is literal. In this case, the actual name of the file is provided in the ``nnn``
349 bytes immediately following the header. If the name is 15 characters or less, it
350 is contained directly in this field and terminated with a slash (/) character.
356 This field provides the date of modification of the file in the form of a
357 decimal encoded number that provides the number of seconds since the epoch
358 (since 00:00:00 Jan 1, 1970) per Posix specifications.
364 This field provides the user id of the file encoded as a decimal ASCII string.
365 This field might not make much sense on non-Unix systems. On Unix, it is the
366 same value as the st_uid field of the stat structure returned by the stat(2)
367 operating system call.
373 This field provides the group id of the file encoded as a decimal ASCII string.
374 This field might not make much sense on non-Unix systems. On Unix, it is the
375 same value as the st_gid field of the stat structure returned by the stat(2)
376 operating system call.
382 This field provides the access mode of the file encoded as an octal ASCII
383 string. This field might not make much sense on non-Unix systems. On Unix, it
384 is the same value as the st_mode field of the stat structure returned by the
385 stat(2) operating system call.
391 This field provides the size of the file, in bytes, encoded as a decimal ASCII
398 This field is the archive file member magic number. Its content is always the
399 two characters back tick (0x60) and newline (0x0A). This provides some measure
400 utility in identifying archive files that have been corrupted.
403 offset - vbr encoded 32-bit integer
405 The offset item provides the offset into the archive file where the bitcode
406 member is stored that is associated with the symbol. The offset value is 0
407 based at the start of the first "normal" file member. To derive the actual
408 file offset of the member, you must add the number of bytes occupied by the file
409 signature (8 bytes) and the symbol tables. The value of this item is encoded
410 using variable bit rate encoding to reduce the size of the symbol table.
411 Variable bit rate encoding uses the high bit (0x80) of each byte to indicate
412 if there are more bytes to follow. The remaining 7 bits in each byte carry bits
413 from the value. The final byte does not have the high bit set.
417 length - vbr encoded 32-bit integer
419 The length item provides the length of the symbol that follows. Like this
420 *offset* item, the length is variable bit rate encoded.
424 symbol - character array
426 The symbol item provides the text of the symbol that is associated with the
427 *offset*. The symbol is not terminated by any character. Its length is provided
428 by the *length* field. Note that is allowed (but unwise) to use non-printing
429 characters (even 0x00) in the symbol. This allows for multiple encodings of
439 If **llvm-ar** succeeds, it will exit with 0. A usage error, results
440 in an exit code of 1. A hard (file system typically) error results in an
441 exit code of 2. Miscellaneous or unknown errors result in an