ar - create, modify, and extract from archives


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
       characters  (typical  of  formats  related to a.out) or 16
       characters (typical of formats related to coff).

       `ar' is considered a binary utility  because  archives  of
       this  sort  are  most often used as libraries holding com­
       monly needed subroutines.

       `ar' creates an index to the symbols defined  in  relocat­
       able  object  modules  in the archive when you specify the
       modifier 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  modi­
       fier flags mod in any order, within the first command-line
       argument.

       with a dash.

       The  p  keyletter  specifies what operation to execute; it
       may be any of the following, but you must specify only one
       of them:

       `d' Delete modules from the archive.  Specify the names of
           modules to be deleted as  member...;  the  archive  is
           untouched if you specify no files to delete.

           If  you specify the v modifier, `ar' lists each module
           as it is deleted.

       `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'
           explicitly 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

           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.

           The modifier v used with this operation elicits a line
           of  output  for  each file inserted, along with one of
           the letters a or r to indicate whether  the  file  was
           appended (no old member deleted) or replaced.

       `t' Display  a  table  listing the contents of archive, or
           those of the files listed in member... that  are  pre­
           sent in the archive.  Normally only the member name is
           shown; if you also want  to  see  the  modes  (permis­
           sions),  timestamp,  owner,  group,  and size, you can
           request that by also specifying the v modifier.

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

           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).

           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
           concern, 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
           from the archive.

       `o' Preserve the original dates of members when extracting
           them.   If  you  do  not  specify this modifier, files
           extracted from the archive are stamped with  the  time
           of extraction.

       `P' Use  the  full  path  name  when matching names in the
           archive.  GNU `ar' can not create an  archive  with  a
           full  path  name  (such  archives  are  not POSIX com­
           plaint), but other archive creators can.  This  option
           will  cause  GNU `ar' to match file names using a com­
           plete path name, which can be convenient when extract­
           ing  a  single file from an archive created by another
           tool.

       `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.

           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 com­
       patibility 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 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".


Man(1) output converted with man2html