| .\" Copyright (c) 1991 Free Software Foundation |
| .\" See section COPYING for conditions for redistribution |
| .TH ar 1 "5 November 1991" "cygnus support" "GNU Development Tools" |
| .de BP |
| .sp |
| .ti \-.2i |
| \(** |
| .. |
| |
| .SH NAME |
| ar \- create, modify, and extract from archives. |
| |
| .SH SYNOPSIS |
| .hy 0 |
| .na |
| .BR ar " [\|" "-" "\|]"\c |
| .I {dmpqrtx}[abcilosSuvV] \c |
| [\|\c |
| .I membername\c |
| \&\|] \c |
| .I archive\c |
| \& \c |
| .I files\c |
| \&.\|.\|. |
| |
| .ad b |
| .hy 1 |
| .SH DESCRIPTION |
| The GNU \c |
| .B ar\c |
| \& program creates, modifies, and extracts from |
| archives. An \c |
| .I archive\c |
| \& is a single file holding a collection of |
| other files in a structure that makes it possible to retrieve |
| the original individual files (called \c |
| .I members\c |
| \& of the archive). |
| |
| The original files' contents, mode (permissions), timestamp, owner, and |
| group are preserved in the archive, and may be reconstituted on |
| extraction. |
| |
| GNU \c |
| .B ar\c |
| \& can maintain archives whose members have names of any |
| length; however, depending on how \c |
| .B ar\c |
| \& is configured on your |
| system, a limit on member-name length may be imposed (for compatibility |
| with archive formats maintained with other tools). If it exists, the |
| limit is often 15 characters (typical of formats related to a.out) or 16 |
| characters (typical of formats related to coff). |
| |
| \c |
| .B ar\c |
| \& is considered a binary utility because archives of this sort |
| are most often used as \c |
| .I libraries\c |
| \& holding commonly needed |
| subroutines. |
| |
| \c |
| .B ar\c |
| \& will create an index to the symbols defined in relocatable |
| object modules in the archive when you specify the modifier `\|\c |
| .B s\c |
| \|'. |
| Once created, this index is updated in the archive whenever \c |
| .B ar\c |
| \& |
| makes a change to its contents (save for the `\|\c |
| .B q\c |
| \|' update operation). |
| An archive with such an index speeds up linking to the library, and |
| allows routines in the library to call each other without regard to |
| their placement in the archive. |
| |
| You may use `\|\c |
| .B nm \-s\c |
| \|' or `\|\c |
| .B nm \-\-print\-armap\c |
| \|' to list this index |
| table. If an archive lacks the table, another form of \c |
| .B ar\c |
| \& called |
| \c |
| .B ranlib\c |
| \& can be used to add just the table. |
| |
| \c |
| .B ar\c |
| \& insists on at least two arguments to execute: one |
| keyletter specifying the \c |
| .I operation\c |
| \& (optionally accompanied by other |
| keyletters specifying \c |
| .I modifiers\c |
| \&), and the archive name to act on. |
| |
| Most operations can also accept further \c |
| .I files\c |
| \& arguments, |
| specifying particular files to operate on. |
| |
| .SH OPTIONS |
| GNU \c |
| .B ar\c |
| \& allows you to mix the operation code \c |
| .I p\c |
| \& and modifier |
| flags \c |
| .I mod\c |
| \& in any order, within the first command-line argument. |
| |
| If you wish, you may begin the first command-line argument with a |
| dash. |
| |
| The \c |
| .I p\c |
| \& keyletter specifies what operation to execute; it may be |
| any of the following, but you must specify only one of them: |
| |
| .TP |
| .B d |
| \c |
| .I Delete\c |
| \& modules from the archive. Specify the names of modules to |
| be deleted as \c |
| .I files\c |
| \&; the archive is untouched if you |
| specify no files to delete. |
| |
| If you specify the `\|\c |
| .B v\c |
| \|' modifier, \c |
| .B ar\c |
| \& will list each module |
| as it is deleted. |
| |
| .TP |
| .B m |
| Use this operation to \c |
| .I move\c |
| \& members in an archive. |
| |
| The ordering of members in an archive can make a difference in how |
| programs are linked using the library, if a symbol is defined in more |
| than one member. |
| |
| If no modifiers are used with \c |
| .B m\c |
| \&, any members you name in the |
| \c |
| .I files\c |
| \& arguments are moved to the \c |
| .I end\c |
| \& of the archive; |
| you can use the `\|\c |
| .B a\c |
| \|', `\|\c |
| .B b\c |
| \|', or `\|\c |
| .B i\c |
| \|' modifiers to move them to a |
| specified place instead. |
| |
| .TP |
| .B p |
| \c |
| .I Print\c |
| \& the specified members of the archive, to the standard |
| output file. If the `\|\c |
| .B v\c |
| \|' modifier is specified, show the member |
| name before copying its contents to standard output. |
| |
| If you specify no \c |
| .I files\c |
| \&, all the files in the archive are printed. |
| |
| .TP |
| .B q |
| \c |
| .I Quick append\c |
| \&; add \c |
| .I files\c |
| \& to the end of \c |
| .I archive\c |
| \&, |
| without checking for replacement. |
| |
| The modifiers `\|\c |
| .B a\c |
| \|', `\|\c |
| .B b\c |
| \|', and `\|\c |
| .B i\c |
| \|' do \c |
| .I not\c |
| \& affect this |
| operation; new members are always placed at the end of the archive. |
| |
| The modifier `\|\c |
| .B v\c |
| \|' makes \c |
| .B ar\c |
| \& list each file as it is appended. |
| |
| Since the point of this operation is speed, the archive's symbol table |
| index is not updated, even if it already existed; you can use `\|\c |
| .B ar s\c |
| \|' or |
| \c |
| .B ranlib\c |
| \& explicitly to update the symbol table index. |
| |
| However, too many different systems assume quick append rebuilds the |
| index, so GNU |
| .B ar |
| implements `\|\c |
| .B q\c |
| \|' as a synonym for `\|\c |
| .B r\c |
| \|'. |
| |
| .TP |
| .B r |
| Insert \c |
| .I files\c |
| \& into \c |
| .I archive\c |
| \& (with \c |
| .I replacement\c |
| \&). This |
| operation differs from `\|\c |
| .B q\c |
| \|' in that any previously existing members |
| are deleted if their names match those being added. |
| |
| If one of the files named in \c |
| .I files\c |
| \& doesn't exist, \c |
| .B ar\c |
| \& |
| displays an error message, and leaves undisturbed any existing members |
| of the archive matching that name. |
| |
| By default, new members are added at the end of the file; but you may |
| use one of the modifiers `\|\c |
| .B a\c |
| \|', `\|\c |
| .B b\c |
| \|', or `\|\c |
| .B i\c |
| \|' to request |
| placement relative to some existing member. |
| |
| The modifier `\|\c |
| .B v\c |
| \|' used with this operation elicits a line of |
| output for each file inserted, along with one of the letters `\|\c |
| .B a\c |
| \|' or |
| `\|\c |
| .B r\c |
| \|' to indicate whether the file was appended (no old member |
| deleted) or replaced. |
| |
| .TP |
| .B t |
| Display a \c |
| .I table\c |
| \& listing the contents of \c |
| .I archive\c |
| \&, or those |
| of the files listed in \c |
| .I files\c |
| \& that are present in the |
| archive. Normally only the member name is shown; if you also want to |
| see the modes (permissions), timestamp, owner, group, and size, you can |
| request that by also specifying the `\|\c |
| .B v\c |
| \|' modifier. |
| |
| If you do not specify any \c |
| .I files\c |
| \&, all files in the archive |
| are listed. |
| |
| If there is more than one file with the same name (say, `\|\c |
| .B fie\c |
| \|') in |
| an archive (say `\|\c |
| .B b.a\c |
| \|'), `\|\c |
| .B ar t b.a fie\c |
| \|' will list only the |
| first instance; to see them all, you must ask for a complete |
| listing\(em\&in our example, `\|\c |
| .B ar t b.a\c |
| \|'. |
| |
| .TP |
| .B x |
| \c |
| .I Extract\c |
| \& members (named \c |
| .I files\c |
| \&) from the archive. You can |
| use the `\|\c |
| .B v\c |
| \|' modifier with this operation, to request that |
| \c |
| .B ar\c |
| \& list each name as it extracts it. |
| |
| If you do not specify any \c |
| .I files\c |
| \&, all files in the archive |
| are extracted. |
| |
| .PP |
| |
| A number of modifiers (\c |
| .I mod\c |
| \&) may immediately follow the \c |
| .I p\c |
| \& |
| keyletter, to specify variations on an operation's behavior: |
| |
| .TP |
| .B a |
| Add new files \c |
| .I after\c |
| \& an existing member of the |
| archive. If you use the modifier \c |
| .B a\c |
| \&, the name of an existing archive |
| member must be present as the \c |
| .I membername\c |
| \& argument, before the |
| \c |
| .I archive\c |
| \& specification. |
| |
| .TP |
| .B b |
| Add new files \c |
| .I before\c |
| \& an existing member of the |
| archive. If you use the modifier \c |
| .B b\c |
| \&, the name of an existing archive |
| member must be present as the \c |
| .I membername\c |
| \& argument, before the |
| \c |
| .I archive\c |
| \& specification. (same as `\|\c |
| .B i\c |
| \|'). |
| |
| .TP |
| .B c |
| \c |
| .I Create\c |
| \& the archive. The specified \c |
| .I archive\c |
| \& is always |
| created if it didn't exist, when you request an update. But a warning is |
| issued unless you specify in advance that you expect to create it, by |
| using this modifier. |
| |
| .TP |
| .B f |
| Truncate names in the archive. |
| .B ar |
| will normally permit file names of any length. This will cause it to |
| create archives which are not compatible with the native |
| .B ar |
| program on some systems. If this is a concern, the |
| .B f |
| modifier may be used to truncate file names when putting them in the |
| archive. |
| |
| .TP |
| .B i |
| Insert new files \c |
| .I before\c |
| \& an existing member of the |
| archive. If you use the modifier \c |
| .B i\c |
| \&, the name of an existing archive |
| member must be present as the \c |
| .I membername\c |
| \& argument, before the |
| \c |
| .I archive\c |
| \& specification. (same as `\|\c |
| .B b\c |
| \|'). |
| |
| .TP |
| .B l |
| This modifier is accepted but not used. |
| |
| .TP |
| .B o |
| Preserve the \c |
| .I original\c |
| \& dates of members when extracting them. If |
| you do not specify this modifier, files extracted from the archive |
| will be stamped with the time of extraction. |
| |
| .TP |
| .B s |
| Write an object-file index into the archive, or update an existing one, |
| even if no other change is made to the archive. You may use this modifier |
| flag either with any operation, or alone. Running `\|\c |
| .B ar s\c |
| \|' on an |
| archive is equivalent to running `\|\c |
| .B ranlib\c |
| \|' on it. |
| |
| .TP |
| .B S |
| Do not generate an archive symbol table. This can speed up building a |
| large library in several steps. The resulting archive can not be used |
| with the linker. In order to build a symbol table, you must omit the |
| `\|\c |
| .B S\c |
| \|' modifier on the last execution of `\|\c |
| .B ar\c |
| \|', or you must run `\|\c |
| .B ranlib\c |
| \|' on the archive. |
| |
| .TP |
| .B u |
| Normally, \c |
| .B ar r\c |
| \&.\|.\|. inserts all files |
| listed into the archive. If you would like to insert \c |
| .I only\c |
| \& those |
| of the files you list that are newer than existing members of the same |
| names, use this modifier. The `\|\c |
| .B u\c |
| \|' modifier is allowed only for the |
| operation `\|\c |
| .B r\c |
| \|' (replace). In particular, the combination `\|\c |
| .B qu\c |
| \|' is |
| not allowed, since checking the timestamps would lose any speed |
| advantage from the operation `\|\c |
| .B q\c |
| \|'. |
| |
| .TP |
| .B v |
| This modifier requests the \c |
| .I verbose\c |
| \& version of an operation. Many |
| operations display additional information, such as filenames processed, |
| when the modifier `\|\c |
| .B v\c |
| \|' is appended. |
| |
| .TP |
| .B V |
| This modifier shows the version number of |
| .BR ar . |
| |
| .PP |
| |
| .SH "SEE ALSO" |
| .RB "`\|" binutils "\|'" |
| entry in |
| .B |
| info\c |
| \&; |
| .I |
| The GNU Binary Utilities\c |
| , Roland H. Pesch (October 1991). |
| .BR nm ( 1 )\c |
| \&, |
| .BR ranlib ( 1 )\c |
| \&. |
| |
| .SH COPYING |
| Copyright (c) 1991 Free Software Foundation, Inc. |
| .PP |
| Permission is granted to make and distribute verbatim copies of |
| this manual provided the copyright notice and this permission notice |
| are preserved on all copies. |
| .PP |
| Permission is granted to copy and distribute modified versions of this |
| manual under the conditions for verbatim copying, provided that the |
| entire resulting derived work is distributed under the terms of a |
| permission notice identical to this one. |
| .PP |
| Permission is granted to copy and distribute translations of this |
| manual into another language, under the above conditions for modified |
| versions, except that this permission notice may be included in |
| translations approved by the Free Software Foundation instead of in |
| the original English. |