FreeBSD 4.0 manual page repository

FreeBSD is a free computer operating system based on BSD UNIX originally. Many IT companies, like DeployIS is using it to provide an up-to-date, stable operating system.

ar - create, modify, and extract from archives.

 

NAME

        ar - create, modify, and extract from archives.
 

SYNOPSIS

        ar [-]{dmpqrtx}[abcilosSuvV] [membername] archive files...
 

DESCRIPTION

        The  GNU  ar program creates, modifies, and extracts from archives.  An
        archive is a single file holding a  collection  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), timestamp, owner, and
        group are preserved in the archive, and may be reconstituted on extrac‐
        tion.
 
        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  for‐
        mats maintained with other tools).  If it exists, the limit is often 15
        characters (typical of formats related to a.out) or 16 characters (typ‐
        ical 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 will create an index to the symbols defined  in  relocatable  object
        modules  in the archive when you specify the modifier ‘s’.  Once creat‐
        ed, 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 routines  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.
 
        ar insists on at least two arguments to execute: one keyletter specify‐
        ing  the operation (optionally accompanied by other keyletters specify‐
        ing modifiers), and the archive name to act on.
 
        Most operations can also accept  further  files  arguments,  specifying
        particular files to operate on.
 

OPTIONS

        GNU ar allows you to mix the operation code p and modifier flags mod in
        any order, within the first command-line argument.
 
        If you wish, you may begin 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 files; the archive is untouched if you specify
               no files to delete.
 
               If you specify the ‘v’ modifier, ar will list 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 difference in
               how programs are linked using the library, if a  symbol  is  de‐
               fined in more than one member.
 
               If  no  modifiers  are  used with m, any members you name in the
               files 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 out‐
               put  file.   If  the  ‘v’ modifier is specified, show the member
               name before copying its contents to standard output.
 
               If you specify no files, all the files in the archive are print‐
               ed.
 
        q      Quick  append; add files to the end of archive, without checking
               for replacement.
 
               The modifiers ‘a’, ‘b’, and ‘i’ do not  affect  this  operation;
               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 in‐
               dex.
 
               However, too many different systems assume quick append rebuilds
               the index, so GNU ar implements ‘q’ as a synonym for ‘r’.
 
        r      Insert  files  into  archive  (with replacement). This operation
               differs from ‘q’ in that any  previously  existing  members  are
               deleted if their names match those being added.
 
               If one of the files named in files doesn’t 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 out‐
               put 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 files 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 re‐
               quest that by also specifying the ‘v’ modifier.
 
               If you do not specify any files, 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’  will  list  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 files) 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 any files, 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 behavior:
 
        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 membername argument, before the archive speci‐
               fication.
 
        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 membername argument, before the archive speci‐
               fication.  (same as ‘i’).
 
        c      Create the archive.  The specified archive 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.
 
        f      Truncate  names  in  the  archive.  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 sys‐
               tems.  If this is a concern, the f modifier may be used to trun‐
               cate 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 membername argument, before the archive
               specification.  (same as ‘b’).
 
        l      This modifier is accepted but not used.
 
        o      Preserve the original 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.
 
        s      Write an object-file index into the archive, or update an exist‐
               ing  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 execu‐
               tion 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 members of the same names, use this mod‐
               ifier.   The  ‘u’ modifier 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  operation.
               Many  operations  display  additional information, such as file‐
               names processed, when the modifier ‘v’ is appended.
 
        V      This modifier shows the version number of ar.
        ‘binutils’ entry in info; The GNU Binary  Utilities,  Roland  H.  Pesch
        (October 1991).  nm(1), ranlib(1).
 

COPYING

        Copyright (c) 1991 Free Software Foundation, Inc.
 
        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.
 
        Permission  is granted to copy and distribute modified versions of this
        manual under the conditions for verbatim copying, provided that the en‐
        tire resulting derived work is distributed under the terms of a permis‐
        sion notice identical to this one.
 
        Permission is granted to copy and distribute translations of this manu‐
        al  into another language, under the above conditions for modified ver‐
        sions, except that this permission notice may be included  in  transla‐
        tions approved by the Free Software Foundation instead of in the origi‐
        nal English.
 

Sections

Based on BSD UNIX
FreeBSD is an advanced operating system for x86 compatible (including Pentium and Athlon), amd64 compatible (including Opteron, Athlon64, and EM64T), UltraSPARC, IA-64, PC-98 and ARM architectures. It is derived from BSD, the version of UNIX developed at the University of California, Berkeley. It is developed and maintained by a large team of individuals. Additional platforms are in various stages of development.