Ubuntu Feisty 7.04 manual page repository

Ubuntu is a free computer operating system based on the Linux kernel. Many IT companies, like DeployIS is using it to provide an up-to-date, stable operating system.

Provided by: manpages-posix_2.16-1_all

 

NAME

        ar - create and maintain library archives
 

SYNOPSIS

        ar -d[-v] archive file ...
 
        ar -m [-v] archive file ...
 
        ar -m -a[-v] posname archive file ...
 
        ar -m -b[-v] posname archive file ...
 
        ar -m -i[-v] posname archive file ...
 
        ar -p[-v][-s]archive [file ...]
 
        ar -q[-cv] archive file ...
 
        ar -r[-cuv] archive file ...
 
        ar -r -a[-cuv] posname archive file ...
 
        ar -r -b[-cuv] posname archive file ...
 
        ar -r -i[-cuv] posname archive file ...
 
        ar -t[-v][-s]archive [file ...]
 
        ar -x[-v][-sCT]archive [file ...]
 

DESCRIPTION

        The ar utility is part of the Software Development Utilities option.
 
        The  ar utility can be used to create and maintain groups of files com‐
        bined into an archive. Once an archive has been created, new files  can
        be  added,  and existing files in an archive can be extracted, deleted,
        or replaced. When an archive consists entirely of valid  object  files,
        the  implementation  shall format the archive so that it is usable as a
        library for link editing  (see  c99  and  fort77).  When  some  of  the
        archived  files  are  not  valid  object  files, the suitability of the
        archive for  library  use  is  undefined.     If  an  archive  consists
        entirely of printable files, the entire archive shall be printable.
 
        When ar creates an archive, it creates administrative information indi‐
        cating whether a symbol table is present in the archive. When there  is
        at  least one object file that ar recognizes as such in the archive, an
        archive symbol table shall be created in the archive and maintained  by
        ar;  it  is used by the link editor to search the archive. Whenever the
        ar utility is used to create or update the contents of such an archive,
        the symbol table shall be rebuilt. The -s option shall force the symbol
        table to be rebuilt.
 
        All file operands can be  pathnames.  However,  files  within  archives
        shall  be named by a filename, which is the last component of the path‐
        name used when the file was entered into the archive. The comparison of
        file  operands  to the names of files in archives shall be performed by
        comparing the last component of the operand to the name of the file  in
        the archive.
 
        It  is unspecified whether multiple files in the archive may be identi‐
        cally named. In the case of such files, however, each file    and  pos‐
        name   operand  shall match only the first file in the archive having a
        name that is the same as the last component of the operand.
 

OPTIONS

        The ar  utility  shall  conform  to  the  Base  Definitions  volume  of
        IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
 
        The following options shall be supported:
 
        -a     Position  new  files  in the archive after the file named by the
               posname operand.
 
        -b     Position new files in the archive before the file named  by  the
               posname operand.
 
        -c     Suppress  the  diagnostic  message  that  is written to standard
               error by default when the archive archive is created.
 
        -C     Prevent extracted files from replacing like-named files  in  the
               file system. This option is useful when -T is also used, to pre‐
               vent truncated filenames from replacing files with the same pre‐
               fix.
 
        -d     Delete one or more files from archive.
 
        -i     Position new files in the archive before the file in the archive
               named by the posname operand (equivalent to -b).
 
        -m     Move the named files in the archive. The -a, -b, or  -i  options
               with  the posname operand indicate the position; otherwise, move
               the names files in the archive to the end of the archive.
 
        -p     Write the contents of the files in the  archive  named  by  file
               operands  from  archive  to  the  standard  output.   If no file
               operands are specified, the contents of all files in the archive
               shall be written in the order of the archive.
 
        -q     Append  the  named files to the end of the archive. In this case
               ar does not check whether the added files  are  already  in  the
               archive.  This  is useful to bypass the searching otherwise done
               when creating a large archive piece by piece.
 
        -r     Replace or add files to archive. If the archive named by archive
               does  not exist, a new archive shall be created and a diagnostic
               message shall be written to standard error (unless the -c option
               is specified). If no files are specified and the archive exists,
               the results are undefined.  Files that replace existing files in
               the  archive  shall  not  change the order of the archive. Files
               that do not replace existing  files  in  the  archive  shall  be
               appended  to the archive    unless a -a, -b, or -i option speci‐
               fies another position.
 
        -s     Force the regeneration of the archive symbol table even if ar is
               not  invoked  with an option that modifies the archive contents.
               This option is useful to restore the archive symbol table  after
               it has been stripped; see strip.
 
        -t     Write  a  table  of  contents of archive to the standard output.
               The files specified by the file operands shall  be  included  in
               the  written  list. If no file operands are specified, all files
               in archive shall be included in the order of the archive.
 
        -T     Allow filename truncation of extracted files whose archive names
               are  longer  than  the  file  system  can  support.  By default,
               extracting a file with a name that  is  too  long  shall  be  an
               error;  a diagnostic message shall be written and the file shall
               not be extracted.
 
        -u     Update older files in the archive. When used with the -r option,
               files in the archive shall be replaced only if the corresponding
               file has a modification time that is at least as new as the mod‐
               ification time of the file in the archive.
 
        -v     Give  verbose  output.  When used with the option characters -d,
               -r, or -x, write a  detailed  file-by-file  description  of  the
               archive  creation  and maintenance activity, as described in the
               STDOUT section.
 
        When used with -p, write the name of the file in  the  archive  to  the
        standard  output  before  writing the file in the archive itself to the
        standard output, as described in the STDOUT section.
 
        When used with -t, include a long  listing  of  information  about  the
        files in the archive, as described in the STDOUT section.
 
        -x     Extract the files in the archive named by the file operands from
               archive. The contents of the archive shall not be changed. If no
               file  operands  are  given,  all  files  in the archive shall be
               extracted. The modification time of each file extracted shall be
               set to the time the file is extracted from the archive.
 

OPERANDS

        The following operands shall be supported:
 
        archive
               A pathname of the archive.
 
        file   A pathname. Only the last component shall be used when comparing
               against the names of files in the archive. If two or  more  file
               operands  have  the same last pathname component (basename), the
               results are unspecified.  The  implementation’s  archive  format
               shall not truncate valid filenames of files added to or replaced
               in the archive.
 
        posname
               The name of a file in the archive, used for  relative  position‐
               ing; see options -m and -r.
 

STDIN

        Not used.
        The  archive  named by archive shall be a file in the format created by
        ar -r.
        The following environment variables shall affect the execution of ar:
 
        LANG   Provide a default value for the  internationalization  variables
               that  are  unset  or  null.  (See the Base Definitions volume of
               IEEE Std 1003.1-2001, Section  8.2,  Internationalization  Vari‐
               ables  for the precedence of internationalization variables used
               to determine the values of locale categories.)
 
        LC_ALL If set to a non-empty string value, override the values  of  all
               the other internationalization variables.
 
        LC_CTYPE
               Determine  the  locale  for  the  interpretation of sequences of
               bytes of text data as characters (for  example,  single-byte  as
               opposed  to multi-byte characters in arguments and input files).
 
        LC_MESSAGES
               Determine the locale that should be used to  affect  the  format
               and contents of diagnostic messages written to standard error.
 
        LC_TIME
               Determine the format and content for date and time strings writ‐
               ten by ar -tv.
 
        NLSPATH
               Determine the location of message catalogs for the processing of
               LC_MESSAGES .
 
        TMPDIR Determine  the pathname that overrides the default directory for
               temporary files, if any.
 
        TZ     Determine the timezone used to calculate date and  time  strings
               written  by  ar  -tv.  If  TZ  is  unset or null, an unspecified
               default timezone shall be used.
        Default.
 

STDOUT

        If the -d option is used with the -v option, the standard output format
        shall be:
 
               "d - %s\n", <file>
 
        where file is the operand specified on the command line.
 
        If  the -p option is used with the -v option, ar shall precede the con‐
        tents of each file with:
 
               "\n<%s>\n\n", <file>
 
        where file is the operand  specified  on  the  command  line,  if  file
        operands  were  specified,  and  the name of the file in the archive if
        they were not.
 
        If the -r option is used with the -v option:
 
         * If file is already in the archive, the standard output format  shall
           be:
 
           "r - %s\n", <file>
 
        where <file> is the operand specified on the command line.
 
         * If  file  is  not already in the archive, the standard output format
           shall be:
 
           "a - %s\n", <file>
 
        where <file> is the operand specified on the command line.
 
        If the -t option is used, ar shall write the names of the files in  the
        archive to the standard output in the format:
 
               "%s\n", <file>
 
        where  file  is  the  operand  specified  on  the command line, if file
        operands were specified, or the name of the file in the archive if they
        were not.
 
        If the -t option is used with the -v option, the standard output format
        shall be:
 
               "%s %u/%u %u %s %d %d:%d %d %s\n", <member mode>, <user ID>,
                   <group ID>, <number of bytes in member>,
                   <abbreviated month>, <day-of-month>, <hour>,
                   <minute>, <year>, <file>
 
        where:
 
        <file> Shall be the operand specified on  the  command  line,  if  file
               operands  were specified, or the name of the file in the archive
               if they were not.
 
        <member mode>
 
               Shall be formatted the same as the <file mode> string defined in
               the  STDOUT  section of ls, except that the first character, the
               <entry type>, is not used; the string represents the  file  mode
               of  the  file  in  the  archive  at  the time it was added to or
               replaced in the archive.
 
        The following represent the last-modification time of a  file  when  it
        was most recently added to or replaced in the archive:
 
        <abbreviated month>
 
               Equivalent to the format of the %b conversion specification for‐
               mat in date.
 
        <day-of-month>
 
               Equivalent to the format of the %e conversion specification for‐
               mat in date.
 
        <hour> Equivalent to the format of the %H conversion specification for‐
               mat in date.
 
        <minute>
               Equivalent to the format of the %M conversion specification for‐
               mat in date.
 
        <year> Equivalent to the format of the %Y conversion specification for‐
               mat in date.
 
        When LC_TIME does not specify the POSIX locale, a different format  and
        order  of  presentation  of  these fields relative to each other may be
        used in a format appropriate in the specified locale.
 
        If the -x option is used with the -v option, the standard output format
        shall be:
 
               "x - %s\n", <file>
 
        where  file  is  the  operand  specified  on  the command line, if file
        operands were specified, or the name of the file in the archive if they
        were not.
 

STDERR

        The  standard  error  shall  be  used only for diagnostic messages. The
        diagnostic message about creating a new archive when -c is  not  speci‐
        fied shall not modify the exit status.
        Archives are files with unspecified formats.
        None.
        The following exit values shall be returned:
 
         0     Successful completion.
 
        >0     An error occurred.
        Default.
 
        The following sections are informative.
        None.
 

EXAMPLES

        None.
 

RATIONALE

        The  archive  format  is not described. It is recognized that there are
        several known ar formats, which are not compatible.  The ar utility  is
        included,  however, to allow creation of archives that are intended for
        use only on one machine. The archive is specified as a file, and it can
        be  moved  as  a  file. This does allow an archive to be moved from one
        machine to another machine that uses the same implementation of ar.
 
        Utilities such as pax (and its forebears tar  and  cpio)  also  provide
        portable  "archives".  This  is  a not a duplication; the ar utility is
        included to provide an interface primarily for make and the  compilers,
        based on a historical model.
 
        In historical implementations, the -q option (available on XSI-conform‐
        ing systems) is known to execute quickly because ar does not  check  on
        whether the added members are already in the archive. This is useful to
        bypass the searching otherwise  done  when  creating  a  large  archive
        piece-by-piece.  These remarks may but need not remain true for a brand
        new implementation of this utility;  hence,  these  remarks  have  been
        moved into the RATIONALE.
 
        BSD  implementations  historically required applications to provide the
        -s option whenever the archive was supposed to contain a symbol  table.
        As  in  this volume of IEEE Std 1003.1-2001, System V historically cre‐
        ates or updates an archive symbol table  whenever  an  object  file  is
        removed from, added to, or updated in the archive.
 
        The OPERANDS section requires what might seem to be true without speci‐
        fying it: the archive cannot truncate the filenames  below  {NAME_MAX}.
        Some  historical  implementations  do  so,  however, causing unexpected
        results   for   the   application.   Therefore,    this    volume    of
        IEEE Std 1003.1-2001  makes the requirement explicit to avoid misunder‐
        standings.
 
        According to the System V documentation, the options -dmpqrtx  are  not
        required   to   begin   with   a  hyphen  (       -       ).   This  volume  of
        IEEE Std 1003.1-2001 requires that a  conforming  application  use  the
        leading hyphen.
 
        The  archive format used by the 4.4 BSD implementation is documented in
        this RATIONALE as an example: A file created  by  ar  begins  with  the
        "magic"  string  "!<arch>\n"  .  The  rest of the archive is made up of
        objects, each of which is composed of a header for a file,  a  possible
        filename, and the file contents. The header is portable between machine
        architectures, and, if the file contents are printable, the archive  is
        itself printable.
 
        The  header is made up of six ASCII fields, followed by a two-character
        trailer. The fields are the object name (16 characters), the file  last
        modification time (12 characters), the user and group IDs (each 6 char‐
        acters), the file mode (8 characters), and the file  size  (10  charac‐
        ters).  All  numeric  fields  are in decimal, except for the file mode,
        which is in octal.
 
        The modification time is the file st_mtime field. The  user  and  group
        IDs  are  the  file st_uid and st_gid fields. The file mode is the file
        st_mode field. The file size is the file st_size  field.  The  two-byte
        trailer is the string "     <newline>" .
 
        Only  the name field has any provision for overflow. If any filename is
        more than 16 characters in length or contains an  embedded  space,  the
        string "#1/" followed by the ASCII length of the name is written in the
        name field. The file size (stored in the archive header) is incremented
        by the length of the name. The name is then written immediately follow‐
        ing the archive header.
 
        Any unused characters in any of these fields are written  as  <space>s.
        If  any  fields  are  their  particular maximum number of characters in
        length, there is no separation between the fields.
 
        Objects in the archive are always an even number of bytes  long;  files
        that  are  an  odd  number  of  bytes long are padded with a <newline>,
        although the size in the header does not reflect this.
 
        The ar utility description requires that  (when  all  its  members  are
        valid  object files) ar produce an object code library, which the link‐
        age editor can use to extract object modules.  If  the  linkage  editor
        needs  a  symbol  table to permit random access to the archive, ar must
        provide it; however, ar does not require a symbol table.
 
        The BSD -o option was omitted. It is a rare conforming application that
        uses ar to extract object code from a library with concern for its mod‐
        ification time, since this can only be of importance  to  make.  Hence,
        since  this  functionality  is  not  deemed  important for applications
        portability, the modification time of the extracted files is set to the
        current time.
 
        There  is at least one known implementation (for a small computer) that
        can accommodate only object files for that  system,  disallowing  mixed
        object  and  other files. The ability to handle any type of file is not
        only historical practice for most implementations, but is also  a  rea‐
        sonable expectation.
 
        Consideration  was given to changing the output format of ar -tv to the
        same format as the output of ls -l. This would have  made  parsing  the
        output  of ar the same as that of ls. This was rejected in part because
        the current ar format is commonly used and changes would break histori‐
        cal  usage. Second, ar gives the user ID and group ID in numeric format
        separated by a slash. Changing this to be the user name and group  name
        would  not  be correct if the archive were moved to a machine that con‐
        tained a different user database. Since  ar  cannot  know  whether  the
        archive  was  generated  on  the  same  machine, it cannot tell what to
        report.
 
        The text on the -ur option combination is historical practice-since one
        filename  can easily represent two different files (for example, /a/foo
        and /b/foo), it is reasonable to replace the file in the  archive  even
        when  the  modification time in the archive is identical to that in the
        file system.
        None.
        c99 , date , fort77 , pax  ,  strip  the  Base  Definitions  volume  of
        IEEE Std 1003.1-2001,  Chapter  13,  Headers, <unistd.h> description of
        {POSIX_NO_TRUNC}
 

COPYRIGHT

        Portions of this text are reprinted and reproduced in  electronic  form
        from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
        -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
        Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
        Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
        event of any discrepancy between this version and the original IEEE and
        The Open Group Standard, the original IEEE and The Open Group  Standard
        is  the  referee document. The original Standard can be obtained online
http://www.opengroup.org/unix/online.html .
 

Sections

What does Ubuntu mean?
Ubuntu is an African word meaning 'Humanity to others', or 'I am what I am because of who we all are'. The Ubuntu distribution brings the spirit of Ubuntu to the software world.