1 .\" Man page generated from reStructuredText.

     2 .

     3 .TH "LLVM-AR" "1" "2016-07-10" "3.8" "LLVM"

     4 .SH NAME

     5 llvm-ar \- LLVM archiver

     6 .

     7 .nr rst2man-indent-level 0

     8 .

     9 .de1 rstReportMargin

    10 \\$1 \\n[an-margin]

    11 level \\n[rst2man-indent-level]

    12 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]

    13 -

    14 \\n[rst2man-indent0]

    15 \\n[rst2man-indent1]

    16 \\n[rst2man-indent2]

    17 ..

    18 .de1 INDENT

    19 .\" .rstReportMargin pre:

    20 . RS \\$1

    21 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]

    22 . nr rst2man-indent-level +1

    23 .\" .rstReportMargin post:

    24 ..

    25 .de UNINDENT

    26 . RE

    27 .\" indent \\n[an-margin]

    28 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]

    29 .nr rst2man-indent-level -1

    30 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]

    31 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u

    32 ..

    33 .SH SYNOPSIS

    34 .sp

    35 \fBllvm\-ar\fP [\-]{dmpqrtx}[Rabfikou] [relpos] [count] <archive> [files...]

    36 .SH DESCRIPTION

    37 .sp

    38 The \fBllvm\-ar\fP command is similar to the common Unix utility, \fBar\fP\&. It

    39 archives several files together into a single file. The intent for this is

    40 to produce archive libraries by LLVM bitcode that can be linked into an

    41 LLVM program. However, the archive can contain any kind of file. By default,

    42 \fBllvm\-ar\fP generates a symbol table that makes linking faster because

    43 only the symbol table needs to be consulted, not each individual file member

    44 of the archive.

    45 .sp

    46 The \fBllvm\-ar\fP command can be used to \fIread\fP SVR4, GNU and BSD style archive

    47 files. However, right now it can only write in the GNU format. If an

    48 SVR4 or BSD style archive is used with the \fBr\fP (replace) or \fBq\fP (quick

    49 update) operations, the archive will be reconstructed in GNU format.

    50 .sp

    51 Here\(aqs where \fBllvm\-ar\fP departs from previous \fBar\fP implementations:

    52 .sp

    53 \fISymbol Table\fP

    54 .INDENT 0.0

    55 .INDENT 3.5

    56 Since \fBllvm\-ar\fP supports bitcode files. The symbol table it creates

    57 is in GNU format and includes both native and bitcode files.

    58 .UNINDENT

    59 .UNINDENT

    60 .sp

    61 \fILong Paths\fP

    62 .INDENT 0.0

    63 .INDENT 3.5

    64 Currently \fBllvm\-ar\fP can read GNU and BSD long file names, but only writes

    65 archives with the GNU format.

    66 .UNINDENT

    67 .UNINDENT

    68 .SH OPTIONS

    69 .sp

    70 The options to \fBllvm\-ar\fP are compatible with other \fBar\fP implementations.

    71 However, there are a few modifiers (\fIR\fP) that are not found in other \fBar\fP

    72 implementations. The options to \fBllvm\-ar\fP specify a single basic operation to

    73 perform on the archive, a variety of modifiers for that operation, the name of

    74 the archive file, and an optional list of file names. These options are used to

    75 determine how \fBllvm\-ar\fP should process the archive file.

    76 .sp

    77 The Operations and Modifiers are explained in the sections below. The minimal

    78 set of options is at least one operator and the name of the archive. Typically

    79 archive files end with a \fB\&.a\fP suffix, but this is not required. Following

    80 the \fIarchive\-name\fP comes a list of \fIfiles\fP that indicate the specific members

    81 of the archive to operate on. If the \fIfiles\fP option is not specified, it

    82 generally means either "none" or "all" members, depending on the operation.

    83 .SS Operations

    84 .sp

    85 d

    86 .INDENT 0.0

    87 .INDENT 3.5

    88 Delete files from the archive. No modifiers are applicable to this operation.

    89 The \fIfiles\fP options specify which members should be removed from the

    90 archive. It is not an error if a specified file does not appear in the archive.

    91 If no \fIfiles\fP are specified, the archive is not modified.

    92 .UNINDENT

    93 .UNINDENT

    94 .sp

    95 m[abi]

    96 .INDENT 0.0

    97 .INDENT 3.5

    98 Move files from one location in the archive to another. The \fIa\fP, \fIb\fP, and

    99 \fIi\fP modifiers apply to this operation. The \fIfiles\fP will all be moved

   100 to the location given by the modifiers. If no modifiers are used, the files

   101 will be moved to the end of the archive. If no \fIfiles\fP are specified, the

   102 archive is not modified.

   103 .UNINDENT

   104 .UNINDENT

   105 .sp

   106 p

   107 .INDENT 0.0

   108 .INDENT 3.5

   109 Print files to the standard output. This operation simply prints the

   110 \fIfiles\fP indicated to the standard output. If no \fIfiles\fP are

   111 specified, the entire  archive is printed.  Printing bitcode files is

   112 ill\-advised as they might confuse your terminal settings. The \fIp\fP

   113 operation never modifies the archive.

   114 .UNINDENT

   115 .UNINDENT

   116 .sp

   117 q

   118 .INDENT 0.0

   119 .INDENT 3.5

   120 Quickly append files to the end of the archive.  This operation quickly adds the

   121 \fIfiles\fP to the archive without checking for duplicates that should be

   122 removed first. If no \fIfiles\fP are specified, the archive is not modified.

   123 Because of the way that \fBllvm\-ar\fP constructs the archive file, its dubious

   124 whether the \fIq\fP operation is any faster than the \fIr\fP operation.

   125 .UNINDENT

   126 .UNINDENT

   127 .sp

   128 r[abu]

   129 .INDENT 0.0

   130 .INDENT 3.5

   131 Replace or insert file members. The \fIa\fP, \fIb\fP,  and \fIu\fP

   132 modifiers apply to this operation. This operation will replace existing

   133 \fIfiles\fP or insert them at the end of the archive if they do not exist. If no

   134 \fIfiles\fP are specified, the archive is not modified.

   135 .UNINDENT

   136 .UNINDENT

   137 .sp

   138 t[v]

   139 .INDENT 0.0

   140 .INDENT 3.5

   141 Print the table of contents. Without any modifiers, this operation just prints

   142 the names of the members to the standard output. With the \fIv\fP modifier,

   143 \fBllvm\-ar\fP also prints out the file type (B=bitcode, S=symbol

   144 table, blank=regular file), the permission mode, the owner and group, the

   145 size, and the date. If any \fIfiles\fP are specified, the listing is only for

   146 those files. If no \fIfiles\fP are specified, the table of contents for the

   147 whole archive is printed.

   148 .UNINDENT

   149 .UNINDENT

   150 .sp

   151 x[oP]

   152 .INDENT 0.0

   153 .INDENT 3.5

   154 Extract archive members back to files. The \fIo\fP modifier applies to this

   155 operation. This operation retrieves the indicated \fIfiles\fP from the archive

   156 and writes them back to the operating system\(aqs file system. If no

   157 \fIfiles\fP are specified, the entire archive is extract.

   158 .UNINDENT

   159 .UNINDENT

   160 .SS Modifiers (operation specific)

   161 .sp

   162 The modifiers below are specific to certain operations. See the Operations

   163 section (above) to determine which modifiers are applicable to which operations.

   164 .sp

   165 [a]

   166 .INDENT 0.0

   167 .INDENT 3.5

   168 When inserting or moving member files, this option specifies the destination of

   169 the new files as being after the \fIrelpos\fP member. If \fIrelpos\fP is not found,

   170 the files are placed at the end of the archive.

   171 .UNINDENT

   172 .UNINDENT

   173 .sp

   174 [b]

   175 .INDENT 0.0

   176 .INDENT 3.5

   177 When inserting or moving member files, this option specifies the destination of

   178 the new files as being before the \fIrelpos\fP member. If \fIrelpos\fP is not

   179 found, the files are placed at the end of the archive. This modifier is

   180 identical to the \fIi\fP modifier.

   181 .UNINDENT

   182 .UNINDENT

   183 .sp

   184 [i]

   185 .INDENT 0.0

   186 .INDENT 3.5

   187 A synonym for the \fIb\fP option.

   188 .UNINDENT

   189 .UNINDENT

   190 .sp

   191 [o]

   192 .INDENT 0.0

   193 .INDENT 3.5

   194 When extracting files, this option will cause \fBllvm\-ar\fP to preserve the

   195 original modification times of the files it writes.

   196 .UNINDENT

   197 .UNINDENT

   198 .sp

   199 [u]

   200 .INDENT 0.0

   201 .INDENT 3.5

   202 When replacing existing files in the archive, only replace those files that have

   203 a time stamp than the time stamp of the member in the archive.

   204 .UNINDENT

   205 .UNINDENT

   206 .SS Modifiers (generic)

   207 .sp

   208 The modifiers below may be applied to any operation.

   209 .sp

   210 [c]

   211 .INDENT 0.0

   212 .INDENT 3.5

   213 For all operations, \fBllvm\-ar\fP will always create the archive if it doesn\(aqt

   214 exist. Normally, \fBllvm\-ar\fP will print a warning message indicating that the

   215 archive is being created. Using this modifier turns off that warning.

   216 .UNINDENT

   217 .UNINDENT

   218 .sp

   219 [s]

   220 .INDENT 0.0

   221 .INDENT 3.5

   222 This modifier requests that an archive index (or symbol table) be added to the

   223 archive. This is the default mode of operation. The symbol table will contain

   224 all the externally visible functions and global variables defined by all the

   225 bitcode files in the archive.

   226 .UNINDENT

   227 .UNINDENT

   228 .sp

   229 [S]

   230 .INDENT 0.0

   231 .INDENT 3.5

   232 This modifier is the opposite of the \fIs\fP modifier. It instructs \fBllvm\-ar\fP to

   233 not build the symbol table. If both \fIs\fP and \fIS\fP are used, the last modifier to

   234 occur in the options will prevail.

   235 .UNINDENT

   236 .UNINDENT

   237 .sp

   238 [v]

   239 .INDENT 0.0

   240 .INDENT 3.5

   241 This modifier instructs \fBllvm\-ar\fP to be verbose about what it is doing. Each

   242 editing operation taken against the archive will produce a line of output saying

   243 what is being done.

   244 .UNINDENT

   245 .UNINDENT

   246 .SH STANDARDS

   247 .sp

   248 The \fBllvm\-ar\fP utility is intended to provide a superset of the IEEE Std 1003.2

   249 (POSIX.2) functionality for \fBar\fP\&. \fBllvm\-ar\fP can read both SVR4 and BSD4.4 (or

   250 Mac OS X) archives. If the \fBf\fP modifier is given to the \fBx\fP or \fBr\fP operations

   251 then \fBllvm\-ar\fP will write SVR4 compatible archives. Without this modifier,

   252 \fBllvm\-ar\fP will write BSD4.4 compatible archives that have long names

   253 immediately after the header and indicated using the "#1/ddd" notation for the

   254 name in the header.

   255 .SH FILE FORMAT

   256 .sp

   257 The file format for LLVM Archive files is similar to that of BSD 4.4 or Mac OSX

   258 archive files. In fact, except for the symbol table, the \fBar\fP commands on those

   259 operating systems should be able to read LLVM archive files. The details of the

   260 file format follow.

   261 .sp

   262 Each archive begins with the archive magic number which is the eight printable

   263 characters "!<arch>n" where n represents the newline character (0x0A).

   264 Following the magic number, the file is composed of even length members that

   265 begin with an archive header and end with a n padding character if necessary

   266 (to make the length even). Each file member is composed of a header (defined

   267 below), an optional newline\-terminated "long file name" and the contents of

   268 the file.

   269 .sp

   270 The fields of the header are described in the items below. All fields of the

   271 header contain only ASCII characters, are left justified and are right padded

   272 with space characters.

   273 .sp

   274 name \- char[16]

   275 .INDENT 0.0

   276 .INDENT 3.5

   277 This field of the header provides the name of the archive member. If the name is

   278 longer than 15 characters or contains a slash (/) character, then this field

   279 contains \fB#1/nnn\fP where \fBnnn\fP provides the length of the name and the \fB#1/\fP

   280 is literal.  In this case, the actual name of the file is provided in the \fBnnn\fP

   281 bytes immediately following the header. If the name is 15 characters or less, it

   282 is contained directly in this field and terminated with a slash (/) character.

   283 .UNINDENT

   284 .UNINDENT

   285 .sp

   286 date \- char[12]

   287 .INDENT 0.0

   288 .INDENT 3.5

   289 This field provides the date of modification of the file in the form of a

   290 decimal encoded number that provides the number of seconds since the epoch

   291 (since 00:00:00 Jan 1, 1970) per Posix specifications.

   292 .UNINDENT

   293 .UNINDENT

   294 .sp

   295 uid \- char[6]

   296 .INDENT 0.0

   297 .INDENT 3.5

   298 This field provides the user id of the file encoded as a decimal ASCII string.

   299 This field might not make much sense on non\-Unix systems. On Unix, it is the

   300 same value as the st_uid field of the stat structure returned by the stat(2)

   301 operating system call.

   302 .UNINDENT

   303 .UNINDENT

   304 .sp

   305 gid \- char[6]

   306 .INDENT 0.0

   307 .INDENT 3.5

   308 This field provides the group id of the file encoded as a decimal ASCII string.

   309 This field might not make much sense on non\-Unix systems. On Unix, it is the

   310 same value as the st_gid field of the stat structure returned by the stat(2)

   311 operating system call.

   312 .UNINDENT

   313 .UNINDENT

   314 .sp

   315 mode \- char[8]

   316 .INDENT 0.0

   317 .INDENT 3.5

   318 This field provides the access mode of the file encoded as an octal ASCII

   319 string. This field might not make much sense on non\-Unix systems. On Unix, it

   320 is the same value as the st_mode field of the stat structure returned by the

   321 stat(2) operating system call.

   322 .UNINDENT

   323 .UNINDENT

   324 .sp

   325 size \- char[10]

   326 .INDENT 0.0

   327 .INDENT 3.5

   328 This field provides the size of the file, in bytes, encoded as a decimal ASCII

   329 string.

   330 .UNINDENT

   331 .UNINDENT

   332 .sp

   333 fmag \- char[2]

   334 .INDENT 0.0

   335 .INDENT 3.5

   336 This field is the archive file member magic number. Its content is always the

   337 two characters back tick (0x60) and newline (0x0A). This provides some measure

   338 utility in identifying archive files that have been corrupted.

   339 .UNINDENT

   340 .UNINDENT

   341 .sp

   342 offset \- vbr encoded 32\-bit integer

   343 .INDENT 0.0

   344 .INDENT 3.5

   345 The offset item provides the offset into the archive file where the bitcode

   346 member is stored that is associated with the symbol. The offset value is 0

   347 based at the start of the first "normal" file member. To derive the actual

   348 file offset of the member, you must add the number of bytes occupied by the file

   349 signature (8 bytes) and the symbol tables. The value of this item is encoded

   350 using variable bit rate encoding to reduce the size of the symbol table.

   351 Variable bit rate encoding uses the high bit (0x80) of each byte to indicate

   352 if there are more bytes to follow. The remaining 7 bits in each byte carry bits

   353 from the value. The final byte does not have the high bit set.

   354 .UNINDENT

   355 .UNINDENT

   356 .sp

   357 length \- vbr encoded 32\-bit integer

   358 .INDENT 0.0

   359 .INDENT 3.5

   360 The length item provides the length of the symbol that follows. Like this

   361 \fIoffset\fP item, the length is variable bit rate encoded.

   362 .UNINDENT

   363 .UNINDENT

   364 .sp

   365 symbol \- character array

   366 .INDENT 0.0

   367 .INDENT 3.5

   368 The symbol item provides the text of the symbol that is associated with the

   369 \fIoffset\fP\&. The symbol is not terminated by any character. Its length is provided

   370 by the \fIlength\fP field. Note that is allowed (but unwise) to use non\-printing

   371 characters (even 0x00) in the symbol. This allows for multiple encodings of

   372 symbol names.

   373 .UNINDENT

   374 .UNINDENT

   375 .SH EXIT STATUS

   376 .sp

   377 If \fBllvm\-ar\fP succeeds, it will exit with 0.  A usage error, results

   378 in an exit code of 1. A hard (file system typically) error results in an

   379 exit code of 2. Miscellaneous or unknown errors result in an

   380 exit code of 3.

   381 .SH SEE ALSO

   382 .sp

   383 ar(1)

   384 .SH AUTHOR

   385 Maintained by The LLVM Team (http://llvm.org/).

   386 .SH COPYRIGHT

   387 2003-2016, LLVM Project

   388 .\" Generated by docutils manpage writer.

   389 .