FreeBSD 4.11 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}[abcfilNoPsSuvV] [membername] [count] 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.
 
        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 will be stamped with the time of extraction.
 
        P      Use the full path name when matching names in the  archive.   ar
               can  not  create an archive with a full path name (such archives
               are not POSIX complaint), but other archive creators can.   This
               option  will  cause ar to match file names using a complete path
               name, which can be convenient when extracting a single file from
               an archive created by another tool.
 
        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, 1992, 1993, 1995, 1998, 1999,  2000  Free  Software
        Foundation, Inc.
 
        This document is distributed under the terms of the GNU Free Documenta‐
        tion License, version 1.1.  That license is described  in  the  sources
        for  this  manual  page,  but it is not displayed here in order to make
        this manual more consise.  Copies of this license can also be  obtained
        from: http://www.gnu.org/copyleft/.
 

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.