1AR(1)                        GNU Development Tools                       AR(1)
2
3
4

NAME

6       ar - create, modify, and extract from archives
7

SYNOPSIS

9       ar [--plugin name] [-X32_64] [-]p[mod [relpos] [count]] archive
10       [member...]
11

DESCRIPTION

13       The GNU ar program creates, modifies, and extracts from archives.  An
14       archive is a single file holding a collection of other files in a
15       structure that makes it possible to retrieve the original individual
16       files (called members of the archive).
17
18       The original files' contents, mode (permissions), timestamp, owner, and
19       group are preserved in the archive, and can be restored on extraction.
20
21       GNU ar can maintain archives whose members have names of any length;
22       however, depending on how ar is configured on your system, a limit on
23       member-name length may be imposed for compatibility with archive
24       formats maintained with other tools.  If it exists, the limit is often
25       15 characters (typical of formats related to a.out) or 16 characters
26       (typical of formats related to coff).
27
28       ar is considered a binary utility because archives of this sort are
29       most often used as libraries holding commonly needed subroutines.
30
31       ar creates an index to the symbols defined in relocatable object
32       modules in the archive when you specify the modifier s.  Once created,
33       this index is updated in the archive whenever ar makes a change to its
34       contents (save for the q update operation).  An archive with such an
35       index speeds up linking to the library, and allows routines in the
36       library to call each other without regard to their placement in the
37       archive.
38
39       You may use nm -s or nm --print-armap to list this index table.  If an
40       archive lacks the table, another form of ar called ranlib can be used
41       to add just the table.
42
43       GNU ar can optionally create a thin archive, which contains a symbol
44       index and references to the original copies of the member files of the
45       archives.  Such an archive is useful for building libraries for use
46       within a local build, where the relocatable objects are expected to
47       remain available, and copying the contents of each object would only
48       waste time and space.  Thin archives are also flattened, so that adding
49       one or more archives to a thin archive will add the elements of the
50       nested archive individually.  The paths to the elements of the archive
51       are stored relative to the archive itself.
52
53       GNU ar is designed to be compatible with two different facilities.  You
54       can control its activity using command-line options, like the different
55       varieties of ar on Unix systems; or, if you specify the single command-
56       line option -M, you can control it with a script supplied via standard
57       input, like the MRI "librarian" program.
58

OPTIONS

60       GNU ar allows you to mix the operation code p and modifier flags mod in
61       any order, within the first command-line argument.
62
63       If you wish, you may begin the first command-line argument with a dash.
64
65       The p keyletter specifies what operation to execute; it may be any of
66       the following, but you must specify only one of them:
67
68       d   Delete modules from the archive.  Specify the names of modules to
69           be deleted as member...; the archive is untouched if you specify no
70           files to delete.
71
72           If you specify the v modifier, ar lists each module as it is
73           deleted.
74
75       m   Use this operation to move members in an archive.
76
77           The ordering of members in an archive can make a difference in how
78           programs are linked using the library, if a symbol is defined in
79           more than one member.
80
81           If no modifiers are used with "m", any members you name in the
82           member arguments are moved to the end of the archive; you can use
83           the a, b, or i modifiers to move them to a specified place instead.
84
85       p   Print the specified members of the archive, to the standard output
86           file.  If the v modifier is specified, show the member name before
87           copying its contents to standard output.
88
89           If you specify no member arguments, all the files in the archive
90           are printed.
91
92       q   Quick append; Historically, add the files member... to the end of
93           archive, without checking for replacement.
94
95           The modifiers a, b, and i do not affect this operation; new members
96           are always placed at the end of the archive.
97
98           The modifier v makes ar list each file as it is appended.
99
100           Since the point of this operation is speed, the archive's symbol
101           table index is not updated, even if it already existed; you can use
102           ar s or ranlib explicitly to update the symbol table index.
103
104           However, too many different systems assume quick append rebuilds
105           the index, so GNU ar implements q as a synonym for r.
106
107       r   Insert the files member... into archive (with replacement). This
108           operation differs from q in that any previously existing members
109           are deleted if their names match those being added.
110
111           If one of the files named in member... does not exist, ar displays
112           an error message, and leaves undisturbed any existing members of
113           the archive matching that name.
114
115           By default, new members are added at the end of the file; but you
116           may use one of the modifiers a, b, or i to request placement
117           relative to some existing member.
118
119           The modifier v used with this operation elicits a line of output
120           for each file inserted, along with one of the letters a or r to
121           indicate whether the file was appended (no old member deleted) or
122           replaced.
123
124       t   Display a table listing the contents of archive, or those of the
125           files listed in member... that are present in the archive.
126           Normally only the member name is shown; if you also want to see the
127           modes (permissions), timestamp, owner, group, and size, you can
128           request that by also specifying the v modifier.
129
130           If you do not specify a member, all files in the archive are
131           listed.
132
133           If there is more than one file with the same name (say, fie) in an
134           archive (say b.a), ar t b.a fie lists only the first instance; to
135           see them all, you must ask for a complete listing---in our example,
136           ar t b.a.
137
138       x   Extract members (named member) from the archive.  You can use the v
139           modifier with this operation, to request that ar list each name as
140           it extracts it.
141
142           If you do not specify a member, all files in the archive are
143           extracted.
144
145           Files cannot be extracted from a thin archive.
146
147       A number of modifiers (mod) may immediately follow the p keyletter, to
148       specify variations on an operation's behavior:
149
150       a   Add new files after an existing member of the archive.  If you use
151           the modifier a, the name of an existing archive member must be
152           present as the relpos argument, before the archive specification.
153
154       b   Add new files before an existing member of the archive.  If you use
155           the modifier b, the name of an existing archive member must be
156           present as the relpos argument, before the archive specification.
157           (same as i).
158
159       c   Create the archive.  The specified archive is always created if it
160           did not exist, when you request an update.  But a warning is issued
161           unless you specify in advance that you expect to create it, by
162           using this modifier.
163
164       D   Operate in deterministic mode.  When adding files and the archive
165           index use zero for UIDs, GIDs, timestamps, and use consistent file
166           modes for all files.  When this option is used, if ar is used with
167           identical options and identical input files, multiple runs will
168           create identical output files regardless of the input files'
169           owners, groups, file modes, or modification times.
170
171       f   Truncate names in the archive.  GNU ar will normally permit file
172           names of any length.  This will cause it to create archives which
173           are not compatible with the native ar program on some systems.  If
174           this is a concern, the f modifier may be used to truncate file
175           names when putting them in the archive.
176
177       i   Insert new files before an existing member of the archive.  If you
178           use the modifier i, the name of an existing archive member must be
179           present as the relpos argument, before the archive specification.
180           (same as b).
181
182       l   This modifier is accepted but not used.
183
184       N   Uses the count parameter.  This is used if there are multiple
185           entries in the archive with the same name.  Extract or delete
186           instance count of the given name from the archive.
187
188       o   Preserve the original dates of members when extracting them.  If
189           you do not specify this modifier, files extracted from the archive
190           are stamped with the time of extraction.
191
192       P   Use the full path name when matching names in the archive.  GNU ar
193           can not create an archive with a full path name (such archives are
194           not POSIX complaint), but other archive creators can.  This option
195           will cause GNU ar to match file names using a complete path name,
196           which can be convenient when extracting a single file from an
197           archive created by another tool.
198
199       s   Write an object-file index into the archive, or update an existing
200           one, even if no other change is made to the archive.  You may use
201           this modifier flag either with any operation, or alone.  Running ar
202           s on an archive is equivalent to running ranlib on it.
203
204       S   Do not generate an archive symbol table.  This can speed up
205           building a large library in several steps.  The resulting archive
206           can not be used with the linker.  In order to build a symbol table,
207           you must omit the S modifier on the last execution of ar, or you
208           must run ranlib on the archive.
209
210       T   Make the specified archive a thin archive.  If it already exists
211           and is a regular archive, the existing members must be present in
212           the same directory as archive.
213
214       u   Normally, ar r... inserts all files listed into the archive.  If
215           you would like to insert only those of the files you list that are
216           newer than existing members of the same names, use this modifier.
217           The u modifier is allowed only for the operation r (replace).  In
218           particular, the combination qu is not allowed, since checking the
219           timestamps would lose any speed advantage from the operation q.
220
221       v   This modifier requests the verbose version of an operation.  Many
222           operations display additional information, such as filenames
223           processed, when the modifier v is appended.
224
225       V   This modifier shows the version number of ar.
226
227       ar ignores an initial option spelt -X32_64, for compatibility with AIX.
228       The behaviour produced by this option is the default for GNU ar.  ar
229       does not support any of the other -X options; in particular, it does
230       not support -X32 which is the default for AIX ar.
231
232       The optional command line switch --plugin name causes ar to load the
233       plugin called name which adds support for more file formats.  This
234       option is only available if the toolchain has been built with plugin
235       support enabled.
236
237       @file
238           Read command-line options from file.  The options read are inserted
239           in place of the original @file option.  If file does not exist, or
240           cannot be read, then the option will be treated literally, and not
241           removed.
242
243           Options in file are separated by whitespace.  A whitespace
244           character may be included in an option by surrounding the entire
245           option in either single or double quotes.  Any character (including
246           a backslash) may be included by prefixing the character to be
247           included with a backslash.  The file may itself contain additional
248           @file options; any such options will be processed recursively.
249

SEE ALSO

251       nm(1), ranlib(1), and the Info entries for binutils.
252
254       Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
255       2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free
256       Software Foundation, Inc.
257
258       Permission is granted to copy, distribute and/or modify this document
259       under the terms of the GNU Free Documentation License, Version 1.3 or
260       any later version published by the Free Software Foundation; with no
261       Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
262       Texts.  A copy of the license is included in the section entitled "GNU
263       Free Documentation License".
264
265
266
267binutils-2.20                     2009-10-16                             AR(1)
Impressum