binutils: ar cmdline
1
1 1.1 Controlling 'ar' on the Command Line
1 ========================================
1
1 ar [-X32_64] [-]P[MOD] [--plugin NAME] [--target BFDNAME] [RELPOS] [COUNT] ARCHIVE [MEMBER...]
1
1 When you use 'ar' in the Unix style, 'ar' insists on at least two
1 arguments to execute: one keyletter specifying the _operation_
1 (optionally accompanied by other keyletters specifying _modifiers_), and
1 the archive name to act on.
1
1 Most operations can also accept further MEMBER arguments, specifying
1 particular files to operate on.
1
1 GNU 'ar' allows you to mix the operation code P and modifier flags
1 MOD in any order, within the first command-line argument.
1
1 If you wish, you may begin the first command-line argument with a
1 dash.
1
1 The P keyletter specifies what operation to execute; it may be any of
1 the following, but you must specify only one of them:
1
1 'd'
1 _Delete_ modules from the archive. Specify the names of modules to
1 be deleted as MEMBER...; the archive is untouched if you specify no
1 files to delete.
1
1 If you specify the 'v' modifier, 'ar' lists each module as it is
1 deleted.
1
1 'm'
1 Use this operation to _move_ members in an archive.
1
1 The ordering of members in an archive can make a difference in how
1 programs are linked using the library, if a symbol is defined in
1 more than one member.
1
1 If no modifiers are used with 'm', any members you name in the
1 MEMBER arguments are moved to the _end_ of the archive; you can use
1 the 'a', 'b', or 'i' modifiers to move them to a specified place
1 instead.
1
1 'p'
1 _Print_ the specified members of the archive, to the standard
1 output file. If the 'v' modifier is specified, show the member
1 name before copying its contents to standard output.
1
1 If you specify no MEMBER arguments, all the files in the archive
1 are printed.
1
1 'q'
1 _Quick append_; Historically, add the files MEMBER... to the end of
1 ARCHIVE, without checking for replacement.
1
1 The modifiers 'a', 'b', and 'i' do _not_ affect this operation; new
1 members are always placed at the end of the archive.
1
1 The modifier 'v' makes 'ar' list each file as it is appended.
1
1 Since the point of this operation is speed, implementations of 'ar'
1 have the option of not updating the archive's symbol table if one
1 exists. Too many different systems however assume that symbol
1 tables are always up-to-date, so GNU 'ar' will rebuild the table
1 even with a quick append.
1
1 Note - GNU 'ar' treats the command 'qs' as a synonym for 'r' -
1 replacing already existing files in the archive and appending new
1 ones at the end.
1
1 'r'
1 Insert the files MEMBER... into ARCHIVE (with _replacement_). This
1 operation differs from 'q' in that any previously existing members
1 are deleted if their names match those being added.
1
1 If one of the files named in MEMBER... does not exist, 'ar'
1 displays an error message, and leaves undisturbed any existing
1 members of the archive matching that name.
1
1 By default, new members are added at the end of the file; but you
1 may use one of the modifiers 'a', 'b', or 'i' to request placement
1 relative to some existing member.
1
1 The modifier 'v' used with this operation elicits a line of output
1 for each file inserted, along with one of the letters 'a' or 'r' to
1 indicate whether the file was appended (no old member deleted) or
1 replaced.
1
1 's'
1 Add an index to the archive, or update it if it already exists.
1 Note this command is an exception to the rule that there can only
1 be one command letter, as it is possible to use it as either a
1 command or a modifier. In either case it does the same thing.
1
1 't'
1 Display a _table_ listing the contents of ARCHIVE, or those of the
1 files listed in MEMBER... that are present in the archive.
1 Normally only the member name is shown; if you also want to see the
1 modes (permissions), timestamp, owner, group, and size, you can
1 request that by also specifying the 'v' modifier.
1
1 If you do not specify a MEMBER, all files in the archive are
1 listed.
1
1 If there is more than one file with the same name (say, 'fie') in
1 an archive (say 'b.a'), 'ar t b.a fie' lists only the first
1 instance; to see them all, you must ask for a complete listing--in
1 our example, 'ar t b.a'.
1
1 'x'
1 _Extract_ members (named MEMBER) from the archive. You can use the
1 'v' modifier with this operation, to request that 'ar' list each
1 name as it extracts it.
1
1 If you do not specify a MEMBER, all files in the archive are
1 extracted.
1
1 Files cannot be extracted from a thin archive.
1
1 A number of modifiers (MOD) may immediately follow the P keyletter,
1 to specify variations on an operation's behavior:
1
1 'a'
1 Add new files _after_ an existing member of the archive. If you
1 use the modifier 'a', the name of an existing archive member must
1 be present as the RELPOS argument, before the ARCHIVE
1 specification.
1
1 'b'
1 Add new files _before_ an existing member of the archive. If you
1 use the modifier 'b', the name of an existing archive member must
1 be present as the RELPOS argument, before the ARCHIVE
1 specification. (same as 'i').
1
1 'c'
1 _Create_ the archive. The specified ARCHIVE is always created if
1 it did not exist, when you request an update. But a warning is
1 issued unless you specify in advance that you expect to create it,
1 by using this modifier.
1
1 'D'
1 Operate in _deterministic_ mode. When adding files and the archive
1 index use zero for UIDs, GIDs, timestamps, and use consistent file
1 modes for all files. When this option is used, if 'ar' is used
1 with identical options and identical input files, multiple runs
1 will create identical output files regardless of the input files'
1 owners, groups, file modes, or modification times.
1
1 If 'binutils' was configured with
1 '--enable-deterministic-archives', then this mode is on by default.
1 It can be disabled with the 'U' modifier, below.
1
1 'f'
1 Truncate names in the archive. GNU 'ar' will normally permit file
1 names of any length. This will cause it to create archives which
1 are not compatible with the native 'ar' program on some systems.
1 If this is a concern, the 'f' modifier may be used to truncate file
1 names when putting them in the archive.
1
1 'i'
1 Insert new files _before_ an existing member of the archive. If
1 you use the modifier 'i', the name of an existing archive member
1 must be present as the RELPOS argument, before the ARCHIVE
1 specification. (same as 'b').
1
1 'l'
1 This modifier is accepted but not used.
1
1 'N'
1 Uses the COUNT parameter. This is used if there are multiple
1 entries in the archive with the same name. Extract or delete
1 instance COUNT of the given name from the archive.
1
1 'o'
1 Preserve the _original_ dates of members when extracting them. If
1 you do not specify this modifier, files extracted from the archive
1 are stamped with the time of extraction.
1
1 'P'
1 Use the full path name when matching names in the archive. GNU
1 'ar' can not create an archive with a full path name (such archives
1 are not POSIX complaint), but other archive creators can. This
1 option will cause GNU 'ar' to match file names using a complete
1 path name, which can be convenient when extracting a single file
1 from an archive created by another tool.
1
1 's'
1 Write an object-file index into the archive, or update an existing
1 one, even if no other change is made to the archive. You may use
1 this modifier flag either with any operation, or alone. Running
1 'ar s' on an archive is equivalent to running 'ranlib' on it.
1
1 'S'
1 Do not generate an archive symbol table. This can speed up
1 building a large library in several steps. The resulting archive
1 can not be used with the linker. In order to build a symbol table,
1 you must omit the 'S' modifier on the last execution of 'ar', or
1 you must run 'ranlib' on the archive.
1
1 'T'
1 Make the specified ARCHIVE a _thin_ archive. If it already exists
1 and is a regular archive, the existing members must be present in
1 the same directory as ARCHIVE.
1
1 'u'
1 Normally, 'ar r'... inserts all files listed into the archive. If
1 you would like to insert _only_ those of the files you list that
1 are newer than existing members of the same names, use this
1 modifier. The 'u' modifier is allowed only for the operation 'r'
1 (replace). In particular, the combination 'qu' is not allowed,
1 since checking the timestamps would lose any speed advantage from
1 the operation 'q'.
1
1 'U'
1 Do _not_ operate in _deterministic_ mode. This is the inverse of
1 the 'D' modifier, above: added files and the archive index will get
1 their actual UID, GID, timestamp, and file mode values.
1
1 This is the default unless 'binutils' was configured with
1 '--enable-deterministic-archives'.
1
1 'v'
1 This modifier requests the _verbose_ version of an operation. Many
1 operations display additional information, such as filenames
1 processed, when the modifier 'v' is appended.
1
1 'V'
1 This modifier shows the version number of 'ar'.
1
1 The 'ar' program also supports some command line options which are
1 neither modifiers nor actions, but which do change its behaviour in
1 specific ways:
1
1 '--help'
1 Displays the list of command line options supported by 'ar' and
1 then exits.
1
1 '--version'
1 Displays the version information of 'ar' and then exits.
1
1 '-X32_64'
1 'ar' ignores an initial option spelt '-X32_64', for compatibility
1 with AIX. The behaviour produced by this option is the default for
1 GNU 'ar'. 'ar' does not support any of the other '-X' options; in
1 particular, it does not support '-X32' which is the default for AIX
1 'ar'.
1
1 '--plugin NAME'
1 The optional command line switch '--plugin NAME' causes 'ar' to
1 load the plugin called NAME which adds support for more file
1 formats, including object files with link-time optimization
1 information.
1
1 This option is only available if the toolchain has been built with
1 plugin support enabled.
1
1 If '--plugin' is not provided, but plugin support has been enabled
1 then 'ar' iterates over the files in '${libdir}/bfd-plugins' in
1 alphabetic order and the first plugin that claims the object in
1 question is used.
1
1 Please note that this plugin search directory is _not_ the one used
1 by 'ld''s '-plugin' option. In order to make 'ar' use the linker
1 plugin it must be copied into the '${libdir}/bfd-plugins'
1 directory. For GCC based compilations the linker plugin is called
1 'liblto_plugin.so.0.0.0'. For Clang based compilations it is
1 called 'LLVMgold.so'. The GCC plugin is always backwards
1 compatible with earlier versions, so it is sufficient to just copy
1 the newest one.
1
1 '--target TARGET'
1 The optional command line switch '--target BFDNAME' specifies that
1 the archive members are in an object code format different from
1 your system's default format. See ⇒Target Selection, for
1 more information.
1