## SYNOPSIS

           ar  [-X32_64]  [-]p[mod  [relpos]  [count]]  archive [mem
           ber...]

## DESCRIPTION

           The GNU ar program creates, modifies,  and  extracts  from
           archives.   An  archive is a single file holding a collec
           tion of other files in a structure that makes it  possible
           to  retrieve the original individual files (called members
           of the archive).

           The original files' contents, mode  (permissions),  times
           tamp,  owner,  and group are preserved in the archive, and
           can be restored on extraction.

           GNU ar can maintain archives whose members have  names  of
           any  length; however, depending on how ar 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  charac
           ters  (typical  of formats related to a.out) or 16 charac
           ters (typical of formats related to coff).

           ar is considered a binary utility because archives of this
           sort  are  most  often  used as libraries holding commonly
           needed subroutines.

           ar creates an index to the symbols defined in  relocatable
           object  modules  in the archive when you specify the modi
           fier s.  Once  created,  this  index  is  updated  in  the
           archive  whenever  ar makes a change to its contents (save
           for the q update operation).   An  archive  with  such  an
           index  speeds  up  linking to the library, and allows rou
           tines in the library to call each other without regard  to
           their placement in the archive.

           You  may  use nm -s or nm --print-armap to list this index
           table.  If an archive lacks the table, another form of  ar
           called ranlib can be used to add just the table.

           GNU  ar  is  designed  to be compatible with two different
           facilities.  You can control its activity  using  command-
           line  options,  like the different varieties of ar on Unix
           systems; or, if you specify the single command-line option
           -M, you can control it with a script supplied via standard
           input, like the MRI ``librarian'' program.

## OPTIONS

           GNU ar allows you to mix the operation code p and modifier
           flags  mod  in  any  order,  within the first command-line
           argument.

           m   Use this operation to move members in an archive.

               The ordering of members in an archive can make a  dif
               ference  in how programs are linked using the library,
               if a symbol is defined in more than one member.

               If no modifiers are used with  "m",  any  members  you
               name  in  the member arguments are moved to the end of
               the archive; you can use the a, b, or i  modifiers  to
               move them to a specified place instead.

           p   Print  the  specified  members  of the archive, to the
               standard output file.  If the v modifier is specified,
               show  the  member  name before copying its contents to
               standard output.

               If you specify no member arguments, all the  files  in
               the archive are printed.

           q   Quick append; Historically, add the files member... to
               the end of archive, without checking for  replacement.

               The  modifiers  a,  b, and i do not affect this opera
               tion; new members are always placed at the end of  the
               archive.

               The  modifier  v  makes  ar  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 ar s or ranlib explic
               itly to update the symbol table index.

               However,  too  many  different  systems  assume  quick
               append rebuilds the index, so GNU ar implements "q" as
               a synonym for "r".

           r   Insert the files member... into archive (with replace
               ment). This operation differs from q in that any  pre
               viously  existing  members  are deleted if their names
               match those being added.

               If one of the files named in member... does not exist,
               ar  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 a, b, or  i
               to request placement relative to some existing member.

               If  there  is  more  than  one file with the same name
               (say, fie) in an archive (say b.a), ar t b.a fie lists
               only the first instance; to see them all, you must ask
               for a complete listing---in our example, ar t b.a.

           x   Extract members (named member) from the archive.   You
               can use the v modifier with this operation, to request
               that ar list each name as it extracts it.

               If you do not specify  a  member,  all  files  in  the
               archive are extracted.

           A  number  of modifiers (mod) may immediately follow the p
           keyletter, to specify variations on an operation's  behav
           ior:

           a   Add new files after an existing member of the archive.
               If you use the modifier a, the  name  of  an  existing
               archive member must be present as the relpos argument,
               before the archive specification.

           b   Add  new  files  before  an  existing  member  of  the
               archive.   If  you  use the modifier b, the name of an
               existing archive member must be present as the  relpos
               argument,  before the archive specification.  (same as
               i).

           c   Create the archive.  The specified archive  is  always
               created  if  it  did  not  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.

           f   Truncate names in the archive.  GNU ar  will  normally
               permit  file  names of any length.  This will cause it
               to create archives which are not compatible  with  the
               native  ar program on some systems.  If this is a con
               cern, the f modifier may  be  used  to  truncate  file
               names when putting them in the archive.

           i   Insert  new  files  before  an  existing member of the
               archive.  If you use the modifier i, the  name  of  an
               existing  archive member must be present as the relpos
               argument, before the archive specification.  (same  as
               b).

           l   This modifier is accepted but not used.

           N   Uses  the  count parameter.  This is used if there are
               multiple entries in the archive with  the  same  name.
               Extract  or  delete  instance  count of the given name

           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  ar  s  on  an
               archive is equivalent to running ranlib on it.

           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  S
               modifier  on the last execution of ar, or you must run
               ranlib on the archive.

           u   Normally, ar r... inserts all files  listed  into  the
               archive.   If  you  would like to insert only those of
               the files you list that are newer than  existing  mem
               bers of the same names, use this modifier.  The u mod
               ifier is allowed only for the operation  r  (replace).
               In  particular,  the  combination  qu  is not allowed,
               since checking the timestamps  would  lose  any  speed
               advantage from the operation q.

           v   This modifier requests the verbose version of an oper
               ation.  Many operations  display  additional  informa
               tion, such as filenames processed, when the modifier v
               is appended.

           V   This modifier shows the version number of ar.

           ar ignores an initial option spelt -X32_64,  for  compati
           bility with AIX.  The behaviour produced by this option is
           the default for GNU ar.  ar does not support  any  of  the
           other  -X options; in particular, it does not support -X32
           which is the default for AIX ar.

## SEE ALSO

           nm(1), ranlib(1), and the Info entries for binutils.

## COPYRIGHT

           Copyright (c) 1991, 92, 93, 94, 95, 96, 97, 98, 99,  2000,
           2001, 2002 Free Software Foundation, Inc.

           Permission  is  granted  to copy, distribute and/or modify
           this document under the terms of the GNU  Free  Documenta
           tion  License,  Version 1.1 or any later version published
           by the Free Software Foundation; with  no  Invariant  Sec
           tions,  with  no Front-Cover Texts, and with no Back-Cover
           Texts.  A copy of the license is included in  the  section
           entitled "GNU Free Documentation License".