ar -- Command

The librarian/archiver
ar option [modifier][position] archive [member ...]

The librarian  ar edits and examines libraries.   It combines several files
into  a file  called an  archive or  library. Archives  reduce the  size of
directories  and allow  many files  to be  handled as  a single  unit.  The
principal use of archives is for  libraries of object files.  The linker ld
understands the archive format, and can search libraries of object files to
resolve undefined references in a program.

Options and Modifiers

The  mandatory option  argument consists  of one  of the  following command
keys:

d  Delete each  given member from archive. The ranlib  header is updated if
   present.

m  Move each  given member  within archive. If  no modifier is  given, move
   each member to the end.  The ranlib header is modified if present.

p  Print each member. This is useful only with archives of text files.

q  Quick append: append each  member to the end of archive unconditionally.
   The ranlib header is not updated.

r  Replace each  member of archive.  If archive does not  exist, create it.
   The  optional modifier  specifies  how to  perform  the replacement,  as
   described below.  The ranlib header is modified if present.

t  Print a table of contents that  lists each member specified.  If none is
   given,  list  all in  archive.  The  modifier v  tells  ar  to give  you
   additional information.

x  Extract each  given member and place it into  the current directory.  If
   none is specified, extract all members.  archive is not changed.

The modifier may be one of the following.  The modifiers a, b, i, and u may
be used only with the m and r options.

a  If member does not exist in archive, insert it after the member named by
   the given position.

b  If member does  not exist in archive, insert it  before the member named
   by the given position.

c  Suppress the message normally printed when ar creates an archive.

i  If member does  not exist in archive, insert it  before the member named
   by the  given position. This  is the same  as the b  modifier, described
   above.

k  Preserve the modify  time of a file.  This modifier  is useful only with
   the r, q, and x options.

s  Modify an  archive's ranlib header, or  create it if it  does not exist.
   This must be used for archives read by the linker ld.

u  Update archive only if member is newer than the version in the archive.

v  Generate verbose messages.

Note that  because ar was  created before UNIX established  the standard of
introducing an  option with a hyphen.  Therefore, the  syntax of options to
ar differs  from most other  COHERENT commands: ar expects  all options and
modifiers  to  be  clumped  together  as  its first  argument,  without  an
introductory hyphen.  For example, to use the option r with the modifiers c
and s  on library libname.a  and objects file1.o through  file3.o, type the
following command:

    # RIGHT!
    ar rcs libname.a file1.o file2.o file3.o

The syntax

    # WRONG!
    ar r -s libname.a file1.o file2.o file3.o

creates an archive named -s, which you may have some trouble removing.

ar reads the environmental variables ARHEAD and ARTAIL and appends them to,
respectively, the  beginning and end of its command  line.  For example, to
ensure that ar is always executed with the c modifier, insert the following
into your .profile:

    export ARHEAD=c

Library Structure

All  archives are  written into  a specialized  file format.   Each archive
starts with  a ``magic string'' called ARMAG, which  identifies the file as
an archive.   The members of the  archive follow the magic  number; each is
preceded by  an ar_hdr structure.   For information on  this structure, see
ar.h. The  structure is  followed the  data of the  file, which  occupy the
number of bytes specified by the variable ar_size.

See Also

ar.h,
commands,
ld,
nm,
ranlib

Notes

Each library  that you create should  have a name that  begins with ``lib''
and ends with  ``.a''.  The prefix ``lib'' lets you  call that library with
the -l option  to the command cc; and the  linker ld ignores archives whose
names do not end in .a.

© 2012 by Stephen A. Ness