1AR(1) GNU Development Tools AR(1)
2
6 ar - create, modify, and extract from archives
7
9 ar [-X32_64] [-]p[mod [relpos] [count]] archive [member...]
10
12 The GNU ar program creates, modifies, and extracts from archives. An
13 archive is a single file holding a collection of other files in a
14 structure that makes it possible to retrieve the original individual
15 files (called members of the archive).
16 The original files' contents, mode (permissions), timestamp, owner, and
18 group are preserved in the archive, and can be restored on extraction.
19 GNU ar can maintain archives whose members have names of any length;
21 however, depending on how ar is configured on your system, a limit on
22 member-name length may be imposed for compatibility with archive for‐
23 mats maintained with other tools. If it exists, the limit is often 15
24 characters (typical of formats related to a.out) or 16 characters (typ‐
25 ical of formats related to coff).
26 ar is considered a binary utility because archives of this sort are
28 most often used as libraries holding commonly needed subroutines.
29 ar creates an index to the symbols defined in relocatable object mod‐
31 ules in the archive when you specify the modifier s. Once created,
32 this index is updated in the archive whenever ar makes a change to its
33 contents (save for the q update operation). An archive with such an
34 index speeds up linking to the library, and allows routines in the
35 library to call each other without regard to their placement in the ar‐
36 chive.
37 You may use nm -s or nm --print-armap to list this index table. If an
39 archive lacks the table, another form of ar called ranlib can be used
40 to add just the table.
41 GNU ar can optionally create a thin archive, which contains a symbol
43 index and references to the original copies of the member files of the
44 archives. Such an archive is useful for building libraries for use
45 within a local build, where the relocatable objects are expected to
46 remain available, and copying the contents of each object would only
47 waste time and space. Thin archives are also flattened, so that adding
48 one or more archives to a thin archive will add the elements of the
49 nested archive individually. The paths to the elements of the archive
50 are stored relative to the archive itself.
51 GNU ar is designed to be compatible with two different facilities. You
53 can control its activity using command-line options, like the different
54 varieties of ar on Unix systems; or, if you specify the single command-
55 line option -M, you can control it with a script supplied via standard
56 input, like the MRI "librarian" program.
57
59 GNU ar allows you to mix the operation code p and modifier flags mod in
60 any order, within the first command-line argument.
61 If you wish, you may begin the first command-line argument with a dash.
63 The p keyletter specifies what operation to execute; it may be any of
65 the following, but you must specify only one of them:
66 d Delete modules from the archive. Specify the names of modules to
68 be deleted as member...; the archive is untouched if you specify no
69 files to delete.
70 If you specify the v modifier, ar lists each module as it is
72 deleted.
73 m Use this operation to move members in an archive.
75 The ordering of members in an archive can make a difference in how
77 programs are linked using the library, if a symbol is defined in
78 more than one member.
79 If no modifiers are used with "m", any members you name in the mem‐
81 ber arguments are moved to the end of the archive; you can use the
82 a, b, or i modifiers to move them to a specified place instead.
83 p Print the specified members of the archive, to the standard output
85 file. If the v modifier is specified, show the member name before
86 copying its contents to standard output.
87 If you specify no member arguments, all the files in the archive
89 are printed.
90 q Quick append; Historically, add the files member... to the end of
92 archive, without checking for replacement.
93 The modifiers a, b, and i do not affect this operation; new members
95 are always placed at the end of the archive.
96 The modifier v makes ar list each file as it is appended.
98 Since the point of this operation is speed, the archive's symbol
100 table index is not updated, even if it already existed; you can use
101 ar s or ranlib explicitly to update the symbol table index.
102 However, too many different systems assume quick append rebuilds
104 the index, so GNU ar implements q as a synonym for r.
105 r Insert the files member... into archive (with replacement). This
107 operation differs from q in that any previously existing members
108 are deleted if their names match those being added.
109 If one of the files named in member... does not exist, ar displays
111 an error message, and leaves undisturbed any existing members of
112 the archive matching that name.
113 By default, new members are added at the end of the file; but you
115 may use one of the modifiers a, b, or i to request placement rela‐
116 tive to some existing member.
117 The modifier v used with this operation elicits a line of output
119 for each file inserted, along with one of the letters a or r to
120 indicate whether the file was appended (no old member deleted) or
121 replaced.
122 t Display a table listing the contents of archive, or those of the
124 files listed in member... that are present in the archive. Nor‐
125 mally only the member name is shown; if you also want to see the
126 modes (permissions), timestamp, owner, group, and size, you can
127 request that by also specifying the v modifier.
128 If you do not specify a member, all files in the archive are
130 listed.
131 If there is more than one file with the same name (say, fie) in an
133 archive (say b.a), ar t b.a fie lists only the first instance; to
134 see them all, you must ask for a complete listing---in our example,
135 ar t b.a.
136 x Extract members (named member) from the archive. You can use the v
138 modifier with this operation, to request that ar list each name as
139 it extracts it.
140 If you do not specify a member, all files in the archive are
142 extracted.
143 Files cannot be extracted from a thin archive.
145 A number of modifiers (mod) may immediately follow the p keyletter, to
147 specify variations on an operation's behavior:
148 a Add new files after an existing member of the archive. If you use
150 the modifier a, the name of an existing archive member must be
151 present as the relpos argument, before the archive specification.
152 b Add new files before an existing member of the archive. If you use
154 the modifier b, the name of an existing archive member must be
155 present as the relpos argument, before the archive specification.
156 (same as i).
157 c Create the archive. The specified archive is always created if it
159 did not exist, when you request an update. But a warning is issued
160 unless you specify in advance that you expect to create it, by
161 using this modifier.
162 f Truncate names in the archive. GNU ar will normally permit file
164 names of any length. This will cause it to create archives which
165 are not compatible with the native ar program on some systems. If
166 this is a concern, the f modifier may be used to truncate file
167 names when putting them in the archive.
168 i Insert new files before an existing member of the archive. If you
170 use the modifier i, the name of an existing archive member must be
171 present as the relpos argument, before the archive specification.
172 (same as b).
173 l This modifier is accepted but not used.
175 N Uses the count parameter. This is used if there are multiple
177 entries in the archive with the same name. Extract or delete
178 instance count of the given name from the archive.
179 o Preserve the original dates of members when extracting them. If
181 you do not specify this modifier, files extracted from the archive
182 are stamped with the time of extraction.
183 P Use the full path name when matching names in the archive. GNU ar
185 can not create an archive with a full path name (such archives are
186 not POSIX complaint), but other archive creators can. This option
187 will cause GNU ar to match file names using a complete path name,
188 which can be convenient when extracting a single file from an ar‐
189 chive created by another tool.
190 s Write an object-file index into the archive, or update an existing
192 one, even if no other change is made to the archive. You may use
193 this modifier flag either with any operation, or alone. Running ar
194 s on an archive is equivalent to running ranlib on it.
195 S Do not generate an archive symbol table. This can speed up build‐
197 ing a large library in several steps. The resulting archive can
198 not be used with the linker. In order to build a symbol table, you
199 must omit the S modifier on the last execution of ar, or you must
200 run ranlib on the archive.
201 T Make the specified archive a thin archive. If it already exists
203 and is a regular archive, the existing members must be present in
204 the same directory as archive.
205 u Normally, ar r... inserts all files listed into the archive. If
207 you would like to insert only those of the files you list that are
208 newer than existing members of the same names, use this modifier.
209 The u modifier is allowed only for the operation r (replace). In
210 particular, the combination qu is not allowed, since checking the
211 timestamps would lose any speed advantage from the operation q.
212 v This modifier requests the verbose version of an operation. Many
214 operations display additional information, such as filenames pro‐
215 cessed, when the modifier v is appended.
216 V This modifier shows the version number of ar.
218 ar ignores an initial option spelt -X32_64, for compatibility with AIX.
220 The behaviour produced by this option is the default for GNU ar. ar
221 does not support any of the other -X options; in particular, it does
222 not support -X32 which is the default for AIX ar.
223 @file
225 Read command-line options from file. The options read are inserted
226 in place of the original @file option. If file does not exist, or
227 cannot be read, then the option will be treated literally, and not
228 removed.
229 Options in file are separated by whitespace. A whitespace charac‐
231 ter may be included in an option by surrounding the entire option
232 in either single or double quotes. Any character (including a
233 backslash) may be included by prefixing the character to be
234 included with a backslash. The file may itself contain additional
235 @file options; any such options will be processed recursively.
236
238 nm(1), ranlib(1), and the Info entries for binutils.
239
241 Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
242 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software
243 Foundation, Inc.
244 Permission is granted to copy, distribute and/or modify this document
246 under the terms of the GNU Free Documentation License, Version 1.2 or
247 any later version published by the Free Software Foundation; with no
248 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
249 Texts. A copy of the license is included in the section entitled "GNU
250 Free Documentation License".
251binutils-2.18.90 2008-09-10 AR(1)