1LLVM-AR(1)                           LLVM                           LLVM-AR(1)
2
3
4

NAME

6       llvm-ar - LLVM archiver
7

SYNOPSIS

9       llvm-ar [-]{dmpqrtx}[Rabfikou] [relpos] [count] <archive> [files...]
10

DESCRIPTION

12       The  llvm-ar  command is similar to the common Unix utility, ar. It ar‐
13       chives several files together into a single file. The intent  for  this
14       is to produce archive libraries by LLVM bitcode that can be linked into
15       an LLVM program. However, the archive can contain any kind of file.  By
16       default, llvm-ar generates a symbol table that makes linking faster be‐
17       cause only the symbol table needs to be consulted, not each  individual
18       file member of the archive.
19
20       The llvm-ar command can be used to read SVR4, GNU and BSD style archive
21       files. However, right now it can only write in the GNU  format.  If  an
22       SVR4  or BSD style archive is used with the r (replace) or q (quick up‐
23       date) operations, the archive will be reconstructed in GNU format.
24
25       Here's where llvm-ar departs from previous ar implementations:
26
27       Symbol Table
28          Since llvm-ar supports bitcode files. The symbol table it creates is
29          in GNU format and includes both native and bitcode files.
30
31       Long Paths
32          Currently  llvm-ar  can  read  GNU and BSD long file names, but only
33          writes archives with the GNU format.
34

OPTIONS

36       The options to llvm-ar are compatible with  other  ar  implementations.
37       However,  there  are a few modifiers (R) that are not found in other ar
38       implementations. The options to llvm-ar specify a single  basic  opera‐
39       tion  to perform on the archive, a variety of modifiers for that opera‐
40       tion, the name of the archive file, and an optional list of file names.
41       These  options are used to determine how llvm-ar should process the ar‐
42       chive file.
43
44       The Operations and Modifiers are explained in the sections  below.  The
45       minimal set of options is at least one operator and the name of the ar‐
46       chive. Typically archive files end with a .a suffix, but  this  is  not
47       required.  Following  the archive-name comes a list of files that indi‐
48       cate the specific members of the archive to operate on.  If  the  files
49       option is not specified, it generally means either "none" or "all" mem‐
50       bers, depending on the operation.
51
52   Operations
53       d
54          Delete files from the archive. No modifiers are applicable  to  this
55          operation.   The  files  options specify which members should be re‐
56          moved from the archive. It is not an error if a specified file  does
57          not  appear  in the archive.  If no files are specified, the archive
58          is not modified.
59
60       m[abi]
61          Move files from one location in the archive to another.  The  a,  b,
62          and i modifiers apply to this operation. The files will all be moved
63          to the location given by the modifiers. If no  modifiers  are  used,
64          the  files  will be moved to the end of the archive. If no files are
65          specified, the archive is not modified.
66
67       p
68          Print files to the standard output. This operation simply prints the
69          files  indicated  to the standard output. If no files are specified,
70          the entire  archive is printed.  Printing bitcode files  is  ill-ad‐
71          vised  as they might confuse your terminal settings. The p operation
72          never modifies the archive.
73
74       q
75          Quickly append files to the end  of  the  archive.   This  operation
76          quickly  adds  the  files to the archive without checking for dupli‐
77          cates that should be removed first. If no files are  specified,  the
78          archive is not modified.  Because of the way that llvm-ar constructs
79          the archive file, its dubious whether the q operation is any  faster
80          than the r operation.
81
82       r[abu]
83          Replace  or insert file members. The a, b,  and u modifiers apply to
84          this operation. This operation will replace existing files or insert
85          them at the end of the archive if they do not exist. If no files are
86          specified, the archive is not modified.
87
88       t[v]
89          Print the table of contents. Without any modifiers,  this  operation
90          just  prints  the  names of the members to the standard output. With
91          the v modifier, llvm-ar also prints out the  file  type  (B=bitcode,
92          S=symbol  table, blank=regular file), the permission mode, the owner
93          and group, the size, and the date. If any files are  specified,  the
94          listing  is only for those files. If no files are specified, the ta‐
95          ble of contents for the whole archive is printed.
96
97       x[oP]
98          Extract archive members back to files. The  o  modifier  applies  to
99          this  operation.  This  operation retrieves the indicated files from
100          the archive and writes them back to the operating system's file sys‐
101          tem. If no files are specified, the entire archive is extract.
102
103   Modifiers (operation specific)
104       The  modifiers below are specific to certain operations. See the Opera‐
105       tions section (above) to determine which modifiers  are  applicable  to
106       which operations.
107
108       [a]
109          When  inserting  or  moving  member files, this option specifies the
110          destination of the new files as being after the  relpos  member.  If
111          relpos is not found, the files are placed at the end of the archive.
112
113       [b]
114          When  inserting  or  moving  member files, this option specifies the
115          destination of the new files as being before the relpos  member.  If
116          relpos is not found, the files are placed at the end of the archive.
117          This modifier is identical to the i modifier.
118
119       [i]
120          A synonym for the b option.
121
122       [o]
123          When extracting files, this option will cause  llvm-ar  to  preserve
124          the original modification times of the files it writes.
125
126       [u]
127          When  replacing  existing  files  in the archive, only replace those
128          files that have a time stamp than the time stamp of  the  member  in
129          the archive.
130
131   Modifiers (generic)
132       The modifiers below may be applied to any operation.
133
134       [c]
135          For  all  operations,  llvm-ar  will always create the archive if it
136          doesn't exist. Normally, llvm-ar will print a warning message  indi‐
137          cating  that the archive is being created. Using this modifier turns
138          off that warning.
139
140       [s]
141          This modifier requests that an archive index (or  symbol  table)  be
142          added  to  the  archive.  This is the default mode of operation. The
143          symbol table will contain all the externally visible  functions  and
144          global variables defined by all the bitcode files in the archive.
145
146       [S]
147          This  modifier  is  the  opposite  of  the  s modifier. It instructs
148          llvm-ar to not build the symbol table. If both s and S are used, the
149          last modifier to occur in the options will prevail.
150
151       [v]
152          This  modifier  instructs llvm-ar to be verbose about what it is do‐
153          ing. Each editing operation taken against the archive will produce a
154          line of output saying what is being done.
155

STANDARDS

157       The  llvm-ar  utility is intended to provide a superset of the IEEE Std
158       1003.2 (POSIX.2) functionality for ar. llvm-ar can read both  SVR4  and
159       BSD4.4 (or Mac OS X) archives. If the f modifier is given to the x or r
160       operations then llvm-ar will write SVR4  compatible  archives.  Without
161       this  modifier, llvm-ar will write BSD4.4 compatible archives that have
162       long names  immediately  after  the  header  and  indicated  using  the
163       "#1/ddd" notation for the name in the header.
164

FILE FORMAT

166       The file format for LLVM Archive files is similar to that of BSD 4.4 or
167       Mac OSX archive files. In fact, except for the  symbol  table,  the  ar
168       commands on those operating systems should be able to read LLVM archive
169       files. The details of the file format follow.
170
171       Each archive begins with the archive magic number which  is  the  eight
172       printable  characters "!<arch>n" where n represents the newline charac‐
173       ter (0x0A).  Following the magic number, the file is composed  of  even
174       length  members that begin with an archive header and end with a n pad‐
175       ding character if necessary (to make the length even). Each file member
176       is composed of a header (defined below), an optional newline-terminated
177       "long file name" and the contents of the file.
178
179       The fields of the header are described in the items below.  All  fields
180       of the header contain only ASCII characters, are left justified and are
181       right padded with space characters.
182
183       name - char[16]
184          This field of the header provides the name of the archive member. If
185          the  name is longer than 15 characters or contains a slash (/) char‐
186          acter, then this field contains #1/nnn where nnn provides the length
187          of  the  name and the #1/ is literal.  In this case, the actual name
188          of the file is provided in the nnn bytes immediately  following  the
189          header.  If  the  name is 15 characters or less, it is contained di‐
190          rectly in this field and terminated with a slash (/) character.
191
192       date - char[12]
193          This field provides the date of modification of the file in the form
194          of  a  decimal  encoded  number  that provides the number of seconds
195          since the epoch (since 00:00:00 Jan 1, 1970)  per  Posix  specifica‐
196          tions.
197
198       uid - char[6]
199          This  field  provides  the  user id of the file encoded as a decimal
200          ASCII string.  This field might not make much sense on non-Unix sys‐
201          tems.  On Unix, it is the same value as the st_uid field of the stat
202          structure returned by the stat(2) operating system call.
203
204       gid - char[6]
205          This field provides the group id of the file encoded  as  a  decimal
206          ASCII string.  This field might not make much sense on non-Unix sys‐
207          tems. On Unix, it is the same value as the st_gid field of the  stat
208          structure returned by the stat(2) operating system call.
209
210       mode - char[8]
211          This  field provides the access mode of the file encoded as an octal
212          ASCII string. This field might not make much sense on non-Unix  sys‐
213          tems. On Unix, it is the same value as the st_mode field of the stat
214          structure returned by the stat(2) operating system call.
215
216       size - char[10]
217          This field provides the size of the file, in  bytes,  encoded  as  a
218          decimal ASCII string.
219
220       fmag - char[2]
221          This  field  is the archive file member magic number. Its content is
222          always the two characters back tick (0x60) and newline (0x0A).  This
223          provides some measure utility in identifying archive files that have
224          been corrupted.
225
226       offset - vbr encoded 32-bit integer
227          The offset item provides the offset into the archive file where  the
228          bitcode  member  is  stored  that is associated with the symbol. The
229          offset value is 0 based at the start of the first "normal" file mem‐
230          ber.  To  derive  the actual file offset of the member, you must add
231          the number of bytes occupied by the file signature (8 bytes) and the
232          symbol  tables. The value of this item is encoded using variable bit
233          rate encoding to reduce the size of the symbol table.  Variable  bit
234          rate  encoding  uses the high bit (0x80) of each byte to indicate if
235          there are more bytes to follow. The remaining 7 bits  in  each  byte
236          carry bits from the value. The final byte does not have the high bit
237          set.
238
239       length - vbr encoded 32-bit integer
240          The length item provides the length of the symbol that follows. Like
241          this offset item, the length is variable bit rate encoded.
242
243       symbol - character array
244          The  symbol  item provides the text of the symbol that is associated
245          with the offset. The symbol is not terminated by any character.  Its
246          length  is  provided  by the length field. Note that is allowed (but
247          unwise) to use non-printing characters (even 0x00)  in  the  symbol.
248          This allows for multiple encodings of symbol names.
249

EXIT STATUS

251       If llvm-ar succeeds, it will exit with 0.  A usage error, results in an
252       exit code of 1. A hard (file system typically) error results in an exit
253       code of 2. Miscellaneous or unknown errors result in an exit code of 3.
254

SEE ALSO

256       ar(1)
257

AUTHOR

259       Maintained by The LLVM Team (http://llvm.org/).
260
262       2003-2023, LLVM Project
263
264
265
266
2677                                 2023-07-20                        LLVM-AR(1)
Impressum