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 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 41 will be retained. 42 43 Here's where **llvm-ar** departs from previous ``ar`` implementations: 44 45 46 *Symbol Table* 47 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 52 string. 53 54 55 56 *Long Paths* 57 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 62 slash (/) character. 63 64 65 66 *Directory Recursion* 67 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. 72 73 74 75 *TOC Verbose Output* 76 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. 81 82 83 84 85 OPTIONS 86 ------- 87 88 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. 95 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. 102 103 Operations 104 ~~~~~~~~~~ 105 106 107 108 d 109 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. 114 115 116 117 m[abi] 118 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. 124 125 126 127 p[k] 128 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. 134 135 136 137 q[Rf] 138 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. 145 146 147 148 r[Rabfu] 149 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. 154 155 156 157 t[v] 158 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. 166 167 168 169 x[oP] 170 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. 175 176 177 178 179 Modifiers (operation specific) 180 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 181 182 183 The modifiers below are specific to certain operations. See the Operations 184 section (above) to determine which modifiers are applicable to which operations. 185 186 187 [a] 188 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. 192 193 194 195 [b] 196 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. 201 202 203 204 [f] 205 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. 212 213 214 215 [i] 216 217 A synonym for the *b* option. 218 219 220 221 [k] 222 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. 226 227 228 229 [N] 230 231 This option is ignored by **llvm-ar** but provided for compatibility. 232 233 234 235 [o] 236 237 When extracting files, this option will cause **llvm-ar** to preserve the 238 original modification times of the files it writes. 239 240 241 242 [P] 243 244 use full path names when matching 245 246 247 248 [R] 249 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. 255 256 257 258 [u] 259 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. 262 263 264 265 266 Modifiers (generic) 267 ~~~~~~~~~~~~~~~~~~~ 268 269 270 The modifiers below may be applied to any operation. 271 272 273 [c] 274 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. 278 279 280 281 [s] 282 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. Using this modifier is more efficient that using 287 llvm-ranlib|llvm-ranlib which also creates the symbol table. 288 289 290 291 [S] 292 293 This modifier is the opposite of the *s* modifier. It instructs **llvm-ar** to 294 not build the symbol table. If both *s* and *S* are used, the last modifier to 295 occur in the options will prevail. 296 297 298 299 [v] 300 301 This modifier instructs **llvm-ar** to be verbose about what it is doing. Each 302 editing operation taken against the archive will produce a line of output saying 303 what is being done. 304 305 306 307 308 309 STANDARDS 310 --------- 311 312 313 The **llvm-ar** utility is intended to provide a superset of the IEEE Std 1003.2 314 (POSIX.2) functionality for ``ar``. **llvm-ar** can read both SVR4 and BSD4.4 (or 315 Mac OS X) archives. If the ``f`` modifier is given to the ``x`` or ``r`` operations 316 then **llvm-ar** will write SVR4 compatible archives. Without this modifier, 317 **llvm-ar** will write BSD4.4 compatible archives that have long names 318 immediately after the header and indicated using the "#1/ddd" notation for the 319 name in the header. 320 321 322 FILE FORMAT 323 ----------- 324 325 326 The file format for LLVM Archive files is similar to that of BSD 4.4 or Mac OSX 327 archive files. In fact, except for the symbol table, the ``ar`` commands on those 328 operating systems should be able to read LLVM archive files. The details of the 329 file format follow. 330 331 Each archive begins with the archive magic number which is the eight printable 332 characters "!<arch>\n" where \n represents the newline character (0x0A). 333 Following the magic number, the file is composed of even length members that 334 begin with an archive header and end with a \n padding character if necessary 335 (to make the length even). Each file member is composed of a header (defined 336 below), an optional newline-terminated "long file name" and the contents of 337 the file. 338 339 The fields of the header are described in the items below. All fields of the 340 header contain only ASCII characters, are left justified and are right padded 341 with space characters. 342 343 344 name - char[16] 345 346 This field of the header provides the name of the archive member. If the name is 347 longer than 15 characters or contains a slash (/) character, then this field 348 contains ``#1/nnn`` where ``nnn`` provides the length of the name and the ``#1/`` 349 is literal. In this case, the actual name of the file is provided in the ``nnn`` 350 bytes immediately following the header. If the name is 15 characters or less, it 351 is contained directly in this field and terminated with a slash (/) character. 352 353 354 355 date - char[12] 356 357 This field provides the date of modification of the file in the form of a 358 decimal encoded number that provides the number of seconds since the epoch 359 (since 00:00:00 Jan 1, 1970) per Posix specifications. 360 361 362 363 uid - char[6] 364 365 This field provides the user id of the file encoded as a decimal ASCII string. 366 This field might not make much sense on non-Unix systems. On Unix, it is the 367 same value as the st_uid field of the stat structure returned by the stat(2) 368 operating system call. 369 370 371 372 gid - char[6] 373 374 This field provides the group id of the file encoded as a decimal ASCII string. 375 This field might not make much sense on non-Unix systems. On Unix, it is the 376 same value as the st_gid field of the stat structure returned by the stat(2) 377 operating system call. 378 379 380 381 mode - char[8] 382 383 This field provides the access mode of the file encoded as an octal ASCII 384 string. This field might not make much sense on non-Unix systems. On Unix, it 385 is the same value as the st_mode field of the stat structure returned by the 386 stat(2) operating system call. 387 388 389 390 size - char[10] 391 392 This field provides the size of the file, in bytes, encoded as a decimal ASCII 393 string. 394 395 396 397 fmag - char[2] 398 399 This field is the archive file member magic number. Its content is always the 400 two characters back tick (0x60) and newline (0x0A). This provides some measure 401 utility in identifying archive files that have been corrupted. 402 403 404 405 The LLVM symbol table has the special name "#_LLVM_SYM_TAB_#". It is presumed 406 that no regular archive member file will want this name. The LLVM symbol table 407 is simply composed of a sequence of triplets: byte offset, length of symbol, 408 and the symbol itself. Symbols are not null or newline terminated. Here are 409 the details on each of these items: 410 411 412 offset - vbr encoded 32-bit integer 413 414 The offset item provides the offset into the archive file where the bitcode 415 member is stored that is associated with the symbol. The offset value is 0 416 based at the start of the first "normal" file member. To derive the actual 417 file offset of the member, you must add the number of bytes occupied by the file 418 signature (8 bytes) and the symbol tables. The value of this item is encoded 419 using variable bit rate encoding to reduce the size of the symbol table. 420 Variable bit rate encoding uses the high bit (0x80) of each byte to indicate 421 if there are more bytes to follow. The remaining 7 bits in each byte carry bits 422 from the value. The final byte does not have the high bit set. 423 424 425 426 length - vbr encoded 32-bit integer 427 428 The length item provides the length of the symbol that follows. Like this 429 *offset* item, the length is variable bit rate encoded. 430 431 432 433 symbol - character array 434 435 The symbol item provides the text of the symbol that is associated with the 436 *offset*. The symbol is not terminated by any character. Its length is provided 437 by the *length* field. Note that is allowed (but unwise) to use non-printing 438 characters (even 0x00) in the symbol. This allows for multiple encodings of 439 symbol names. 440 441 442 443 444 EXIT STATUS 445 ----------- 446 447 448 If **llvm-ar** succeeds, it will exit with 0. A usage error, results 449 in an exit code of 1. A hard (file system typically) error results in an 450 exit code of 2. Miscellaneous or unknown errors result in an 451 exit code of 3. 452 453 454 SEE ALSO 455 -------- 456 457 458 llvm-ranlib|llvm-ranlib, ar(1) 459
