Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
AR(1)                   FreeBSD General Commands Manual                  AR(1)

NAME
     ar, ranlib - manage archives

SYNOPSIS
     ar -d [-T] [-f] [-j] [-v] [-z] archive file ...
     ar -m [-T] [-a position-after] [-b position-before] [-f]
        [-i position-before] [-j] [-s | -S] [-z] archive file ...
     ar -p [-T] [-f] [-v] archive [file ...]
     ar -q [-T] [-c] [-D] [-f] [-s | -S] [-v] [-z] archive file ...
     ar -r [-T] [-a position-after] [-b position-before] [-c] [-D] [-f]
        [-i position-before] [-j] [-s | -S] [-u] [-v] [-z] archive file ...
     ar -s [-j] [-z] archive
     ar -t [-f] [-T] [-v] archive [file ...]
     ar -x [-C] [-T] [-f] [-o] [-u] [-v] archive [file ...]
     ar -M
     ranlib [-D] archive ...

DESCRIPTION
     The ar utility creates and maintains groups of files combined into an
     archive.  Once an archive has been created, new files can be added to it,
     and existing files can be extracted, deleted or replaced.

     Files are named in the archive by their last file name component, so if a
     file referenced by a path containing a ``/'' is archived, it will be
     named by the last component of the path.  Similarly when matching paths
     listed on the command line against file names stored in the archive, only
     the last component of the path will be compared.

     The normal use of ar is for the creation and maintenance of libraries
     suitable for use with the link editor ld(1), although it is not
     restricted to this purpose.  The ar utility can create and manage an
     archive symbol table (see ar(5)) used to speed up link editing
     operations.  If a symbol table is present in an archive, it will be kept
     up-to-date by subsequent operations on the archive.

     The ranlib utility is used to add an archive symbol table to an existing
     archive.

OPTIONS
     The ar utility supports the following options:

     -a member-after
             When used with option -m this option specifies that the archive
             members specified by arguments file ... are moved to after the
             archive member named by argument member-after.  When used with
             option -r this option specifies that the files specified by
             arguments file ... are added after the archive member named by
             argument member-after.

     -b member-before
             When used with option -m this option specifies that the archive
             members specified by arguments file ... are moved to before the
             archive member named by argument member-before.  When used with
             option -r this option specifies that the files specified by
             arguments file ... are added before the archive member named by
             argument member-before.

     -c      Suppress the informational message printed when a new archive is
             created using the -r and -q options.

     -C      Prevent extracted files from replacing like-named files in the
             file system.

     -d      Delete the members named by arguments file ... from the archive
             specified by argument archive.  The archive's symbol table, if
             present, is updated to reflect the new contents of the archive.

     -D      When used in combination with the -r or -q option, insert 0's
             instead of the real mtime, uid and gid values and 0644 instead of
             file mode from the members named by arguments file ....  This
             ensures that checksums on the resulting archives are reproducible
             when member contents are identical.

     -f      Synonymous with option -T.

     -i member-before
             Synonymous with option -b.

     -j      This option is accepted but ignored.

     -l      This option is accepted for compatibility with GNU ar(1), but is
             ignored.

     -m      Move archive members specified by arguments file ... within the
             archive.  If a position has been specified by one of the -a, -b
             or -i options, the members are moved to before or after the
             specified position.  If no position has been specified, the
             specified members are moved to the end of the archive.  If the
             archive has a symbol table, it is updated to reflect the new
             contents of the archive.

     -M      Read and execute MRI librarian commands from standard input.  The
             commands understood by the ar utility are described in the
             section MRI Librarian Commands.

     -o      Preserve the original modification times of members when
             extracting them.

     -p      Write the contents of the specified archive members named by
             arguments file ... to standard output.  If no members were
             specified, the contents of all the files in the archive are
             written in the order they appear in the archive.

     -q      Append the files specified by arguments file ... to the archive
             specified by argument archive without checking if the files
             already exist in the archive.  The archive symbol table will be
             updated as needed.  If the file specified by the argument archive
             does not already exist, a new archive will be created.

     -r      Replace (add) the files specified by arguments file ... in the
             archive specified by argument archive, creating the archive if
             necessary.  Replacing existing members will not change the order
             of members within the archive.  If a file named in arguments file
             ... does not exist, existing members in the archive that match
             that name are not changed.  New files are added to the end of the
             archive unless one of the positioning options -a, -b or -i is
             specified.  The archive symbol table, if it exists, is updated to
             reflect the new state of the archive.

     -s      Add an archive symbol table (see ar(5)) to the archive specified
             by argument archive.  Invoking ar with the -s option alone is
             equivalent to invoking ranlib.

     -S      Do not generate an archive symbol table.

     -t      List the files specified by arguments file ... in the order in
             which they appear in the archive, one per line.  If no files are
             specified, all files in the archive are listed.

     -T      Use only the first fifteen characters of the archive member name
             or command line file name argument when naming archive members.

     -u      Conditionally update the archive or extract members.  When used
             with the -r option, files named by arguments file ... will be
             replaced in the archive if they are newer than their archived
             versions.  When used with the -x option, the members specified by
             arguments file ... will be extracted only if they are newer than
             the corresponding files in the file system.

     -v      Provide verbose output.  When used with the -d, -m, -q or -x
             options, ar gives a file-by-file description of the archive
             modification being performed, which consists of three white-space
             separated fields: the option letter, a dash ``-'', and the file
             name.  When used with the -r option, ar displays the description
             as above, but the initial letter is an ``a'' if the file is added
             to the archive, or an ``r'' if the file replaces a file already
             in the archive.  When used with the -p option, the name of the
             file enclosed in ``<'' and ``>'' characters is written to
             standard output preceded by a single newline character and
             followed by two newline characters.  The contents of the named
             file follow the file name.  When used with the -t option, ar
             displays eight whitespace separated fields: the file permissions
             as displayed by strmode(3), decimal user and group IDs separated
             by a slash ( ``/''),the file size in bytes, the file modification
             time in strftime(3) format ``%b %e %H:%M %Y'', and the name of
             the file.

     -V      Print a version string and exit.

     -x      Extract archive members specified by arguments file ... into the
             current directory.  If no members have been specified, extract
             all members of the archive.  If the file corresponding to an
             extracted member does not exist it will be created.  If the file
             corresponding to an extracted member does exist, its owner and
             group will not be changed while its contents will be overwritten
             and its permissions will set to that entered in the archive.  The
             file's access and modification time would be that of the time of
             extraction unless the -o option was specified.

     -z      This option is accepted but ignored.

   MRI Librarian Commands
     If the -M option is specified, the ar utility will read and execute
     commands from its standard input.  If standard input is a terminal, the
     ar utility will display the prompt ``AR >'' before reading a line, and
     will continue operation even if errors are encountered.  If standard
     input is not a terminal, the ar utility will not display a prompt and
     will terminate execution on encountering an error.

     Each input line contains a single command.  Words in an input line are
     separated by whitespace characters.  The first word of the line is the
     command, the remaining words are the arguments to the command.  The
     command word may be specified in either case.  Arguments may be separated
     by commas or blanks.

     Empty lines are allowed and are ignored.  Long lines are continued by
     ending them with the ``+'' character.

     The ``*'' and ``;'' characters start a comment.  Comments extend till the
     end of the line.

     When executing an MRI librarian script the ar utility works on a
     temporary copy of an archive.  Changes to the copy are made permanent
     using the save command.

     Commands understood by the ar utility are:

     addlib archive | addlib archive (member [, member]...)
             Add the contents of the archive named by argument archive to the
             current archive.  If specific members are named using the
             arguments member, then those members are added to the current
             archive.  If no members are specified, the entire contents of the
             archive are added to the current archive.

     addmod member [, member]...
             Add the files named by arguments member to the current archive.

     clear   Discard all the contents of the current archive.

     create archive
             Create a new archive named by the argument archive, and makes it
             the current archive.  If the named archive already exists, it
             will be overwritten when the save command is issued.

     delete module [, member]...
             Delete the modules named by the arguments member from the current
             archive.

     directory archive (member [, member]...) [outputfile]
             List each named module in the archive.  The format of the output
             depends on the verbosity setting set using the verbose command.
             Output is sent to standard output, or to the file specified by
             argument outputfile.

     end     Exit successfully from the ar utility.  Any unsaved changes to
             the current archive will be discarded.

     extract member [, member]...
             Extract the members named by the arguments member from the
             current archive.

     list    Display the contents of the current archive in verbose style.

     open archive
             Open the archive named by argument archive and make it the
             current archive.

     replace member [, member]...
             Replace named members in the current archive with the files
             specified by arguments member.  The files must be present in the
             current directory and the named modules must already exist in the
             current archive.

     save    Commit all changes to the current archive.

     verbose
             Toggle the verbosity of the directory command.

EXAMPLES
     To create a new archive ex.a containing three files ex1.o, ex2.o and
     ex3.o, use:
           ar -rc ex.a ex1.o ex2.o ex3.o

     To add an archive symbol table to an existing archive ex.a, use:
           ar -s ex.a

     To delete file ex1.o from archive ex.a, use:
           ar -d ex.a ex1.o

     To verbosely list the contents of archive ex.a, use:
           ar -tv ex.a

     To create a new archive ex.a containing the files ex1.o, and ex2.o, using
     MRI librarian commands, use the following script:

           create ex.a              * specify the output archive
           addmod ex1.o ex2.o       * add modules
           save                     * save pending changes
           end                      * exit the utility

DIAGNOSTICS
     The ar utility exits 0 on success, and >0 if an error occurs.

SEE ALSO
     ld(1), archive(3), elf(3), strftime(3), strmode(3), ar(5)

STANDARDS COMPLIANCE
     The ar utility's support for the -a, -b, -c, -i, -m, -p, -q, -r, -s, -t,
     -u, -v, -C and -T options is believed to be compliant with IEEE Std
     1003.2 (``POSIX.2'').

HISTORY
     An ar command first appeared in AT&T UNIX Version 1.  In FreeBSD 8.0, Kai
     Wang <kaiw@FreeBSD.org> reimplemented ar and ranlib using the Streaming
     Archive Library (libarchive, -larchive) and the ELF Access Library
     (libelf, -lelf).

FreeBSD 11.0-PRERELEASE        December 22, 2011       FreeBSD 11.0-PRERELEASE

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | DIAGNOSTICS | SEE ALSO | STANDARDS COMPLIANCE | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ar&sektion=1&manpath=FreeBSD+10.0-RELEASE>

home | help