aarr -- Command

The librarian/archiver
aarr _o_p_t_i_o_n [_m_o_d_i_f_i_e_r][_p_o_s_i_t_i_o_n] _a_r_c_h_i_v_e [_m_e_m_b_e_r ...]

The librarian  aarr edits and examines libraries.   It combines several files
into  a file  called an  _a_r_c_h_i_v_e or  _l_i_b_r_a_r_y. 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 lldd
understands the archive format, and can search libraries of object files to
resolve undefined references in a program.

_O_p_t_i_o_n_s _a_n_d _M_o_d_i_f_i_e_r_s
The  mandatory _o_p_t_i_o_n  argument consists  of one  of the  following command
keys:

dd  Delete each  given _m_e_m_b_e_r from _a_r_c_h_i_v_e. The rraannlliibb  header is updated if
   present.

mm  Move each  given _m_e_m_b_e_r  within _a_r_c_h_i_v_e. If  no _m_o_d_i_f_i_e_r is  given, move
   each _m_e_m_b_e_r to the end.  The ranlib header is modified if present.

pp  Print each _m_e_m_b_e_r. This is useful only with archives of text files.

qq  Quick append: append each  _m_e_m_b_e_r to the end of _a_r_c_h_i_v_e unconditionally.
   The ranlib header is not updated.

rr  Replace each  _m_e_m_b_e_r of _a_r_c_h_i_v_e.  If _a_r_c_h_i_v_e does not  exist, create it.
   The  optional _m_o_d_i_f_i_e_r  specifies  how to  perform  the replacement,  as
   described below.  The ranlib header is modified if present.

tt  Print a table of contents that  lists each _m_e_m_b_e_r specified.  If none is
   given,  list  all in  _a_r_c_h_i_v_e.  The  modifier vv  tells  aarr  to give  you
   additional information.

xx  Extract each  given _m_e_m_b_e_r and place it into  the current directory.  If
   none is specified, extract all members.  _a_r_c_h_i_v_e is not changed.

The _m_o_d_i_f_i_e_r may be one of the following.  The modifiers aa, bb, ii, and uu may
be used only with the mm and rr options.

aa  If _m_e_m_b_e_r does not exist in _a_r_c_h_i_v_e, insert it after the member named by
   the given _p_o_s_i_t_i_o_n.

bb  If _m_e_m_b_e_r does  not exist in _a_r_c_h_i_v_e, insert it  before the member named
   by the given _p_o_s_i_t_i_o_n.

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

ii  If _m_e_m_b_e_r does  not exist in _a_r_c_h_i_v_e, insert it  before the member named
   by the  given _p_o_s_i_t_i_o_n. This  is the same  as the bb  modifier, described
   above.

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

s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 lldd.

uu  Update _a_r_c_h_i_v_e only if _m_e_m_b_e_r is newer than the version in the _a_r_c_h_i_v_e.

vv  Generate verbose messages.

Note that  because aarr was  created before UNIX established  the standard of
introducing an  option with a hyphen.  Therefore, the  syntax of options to
aarr differs  from most other  COHERENT commands: aarr expects  all options and
modifiers  to  be  clumped  together  as  its first  argument,  without  an
introductory hyphen.  For example, to use the option rr with the modifiers cc
and ss  on library lliibbnnaammee.aa  and objects ffiillee11.oo through  ffiillee33.o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s, which you may have some trouble removing.

aarr reads the environmental variables AARRHHEEAADD and AARRTTAAIILL and appends them to,
respectively, the  beginning and end of its command  line.  For example, to
ensure that aarr is always executed with the cc modifier, insert the following
into your .pprrooffiillee:

    export ARHEAD=c

_L_i_b_r_a_r_y _S_t_r_u_c_t_u_r_e
All  archives are  written into  a specialized  file format.   Each archive
starts with  a ``magic string'' called AARRMMAAGG, which  identifies the file as
an archive.   The members of the  archive follow the magic  number; each is
preceded by  an aarr_hhddrr structure.   For information on  this structure, see
aarr.hh. The  structure is  followed the  data of the  file, which  occupy the
number of bytes specified by the variable aarr_ssiizzee.

_S_e_e _A_l_s_o
aarr.hh, ccoommmmaannddss, lldd, nnmm, rraannlliibb

_N_o_t_e_s
It is recommended  that each object-file library you create  with aarr have a
name that begins with the string lliibb and ends with the string .aa. Using the
prefix lliibb will allow you to call that library with the -ll option to the cccc
command.  lldd will not recognize an archive whose name does not end in .aa.
