← Back to branch summary

~ubuntu-branches/ubuntu/quantal/llvm-3.1/quantal

« back to all changes in this revision

Viewing changes to docs/CommandGuide/llvm-ar.pod

  • Committer: Package Import Robot
  • Author(s): Sylvestre Ledru
  • Date: 2012-03-29 19:09:51 UTC
  • Revision ID: package-import@ubuntu.com-20120329190951-aq83ivog4cg8bxun
Tags: upstream-3.1~svn153643
Import upstream version 3.1~svn153643

Show diffs side-by-side

added added

removed removed

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