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(5)                     FreeBSD File Formats Manual                    AR(5)

NAME
     ar - archive file format for ar(1) and ranlib(1)

SYNOPSIS
     #include <ar.h>

DESCRIPTION
     ar(1) archives are created and managed by the ar(1) and ranlib(1)
     utilities.  These archives are typically used during program development
     to hold libraries of program objects.  An ar(1) archive is contained in a
     single operating system file.

     This manual page documents two variants of the ar(1) archive format: the
     BSD archive format, and the SVR4/GNU archive format.

     In both variants the archive file starts with an identifying byte
     sequence of the seven ASCII characters `!<arch>' followed by a ASCII
     linefeed character (see the constant ``ARMAG'' in the header file
     <ar.h>).

     Archive members follow the initial identifying byte sequence.  Each
     archive member is prefixed by a fixed size header describing the file
     attributes associated with the member.

   Archive Headers
     An archive header describes the file attributes for the archive member
     that follows it.  The ar(5) format only supports a limited number of
     attributes: the file name, the file creation time stamp, the uid and gid
     of the creator, the file mode and the file size.

     Archive headers are placed at an even byte offset in the archive file.
     If the data for an archive member ends at an odd byte offset, then a
     padding byte with value 0x0A is used to position the next archive header
     on an even byte offset.

     An archive header comprises the following fixed sized fields:

     ar_name     (16 bytes) The file name of the archive member.  The format
                 of this field varies between the BSD and SVR4/GNU formats and
                 is described in more detail in the section Representing File
                 Names below.

     ar_date     (12 bytes) The file modification time for the member in
                 seconds since the epoch, encoded as a decimal number.

     ar_uid      (6 bytes) The uid associated with the archive member, encoded
                 as a decimal number.

     ar_gid      (6 bytes) The gid associated with the archive member, encoded
                 as a decimal number.

     ar_mode     (8 bytes) The file mode for the archive member, encoded as an
                 octal number.

     ar_size     (10 bytes) In the SVR4/GNU archive format this field holds
                 the size in bytes of the archive member, encoded as a decimal
                 number.  In the BSD archive format, for short file names,
                 this field holds the size in bytes of the archive member,
                 encoded as a decimal number.  For long file names (see
                 Representing File Names below), the field contains the
                 combined size of the archive member and its file name,
                 encoded as a decimal number.

     ar_fmag     (2 bytes) This field holds 2 bytes with values 0x96 and 0x0A
                 respectively, marking the end of the header.

     Unused bytes in the fields of an archive header are set to the value
     0x20.

   Representing File Names
     The BSD and SVR4/GNU variants use different schemes for encoding file
     names for members.

     BSD       File names that are up to 16 bytes long and which do not
               contain embedded spaces are stored directly in the ar_name
               field of the archive header.  File names that are either longer
               than 16 bytes or which contain embedded spaces are stored
               immediately after the archive header and the ar_name field of
               the archive header is set to the string ``#1/'' followed by a
               decimal representation of the number of bytes needed for the
               file name.  In addition, the ar_size field of the archive
               header is set to the decimal representation of the combined
               sizes of the archive member and the file name.  The file
               contents of the member follows the file name without further
               padding.

               As an example, if the file name for a member was ``A B'' and
               its contents was the string ``C D'', then the ar_name field of
               the header would contain ``#1/3'', the ar_size field of the
               header would contain ``6'', and the bytes immediately following
               the header would be 0x41, 0x20, 0x42, 0x43, 0x20 and 0x44
               (ASCII ``A BC D'').

     SVR4/GNU  File names that are up to 15 characters long are stored
               directly in the ar_name field of the header, terminated by a
               ``/'' character.

               If the file name is larger than would fit in space for the
               ar_name field, then the actual file name is kept in the archive
               string table (see Archive String Tables below), and the decimal
               offset of the file name in the string table is stored in the
               ar_name field, prefixed by a ``/'' character.

               As an example, if the real file name has been stored at offset
               768 in the archive string table, the ar_name field of the
               header will contain the string ``/768''.

   Special Archive Members
     The following archive members are special.

     ``/''   In the SVR4/GNU variant of the archive format, the archive member
             with name ``/'' denotes an archive symbol table.  If present,
             this member will be the very first member in the archive.

     ``//''  In the SVR4/GNU variant of the archive format, the archive member
             with name ``//'' denotes the archive string table.  This special
             member is used to hold filenames that do not fit in the file name
             field of the header (see Representing File Names above).  If
             present, this member immediately follows the archive symbol table
             if an archive symbol table is present, or is the first member
             otherwise.

     ``__.SYMDEF''
             This special member contains the archive symbol table in the BSD
             variant of the archive format.  If present, this member will be
             the very first member in the archive.

   Archive String Tables
     An archive string table is used in the SVR4/GNU archive format to hold
     file names that are too large to fit into the constraints of the ar_name
     field of the archive header.  An archive string table contains a sequence
     of file names.  Each file name in the archive string table is terminated
     by the byte sequence 0x2F, 0x0A (the ASCII string ``/\n'').  No padding
     is used to separate adjacent file names.

   Archive Symbol Tables
     Archive symbol tables are used to speed up link editing by providing a
     mapping between the program symbols defined in the archive and the
     corresponding archive members.  Archive symbol tables are managed by the
     ranlib(1) utility.

     The format of archive symbol tables is as follows:

     BSD       In the BSD archive format, the archive symbol table comprises
               of two parts: a part containing an array of struct ranlib
               descriptors, followed by a part containing a symbol string
               table.  The sizes and layout of the structures that make up a
               BSD format archive symbol table are machine dependent.

               The part containing struct ranlib descriptors begins with a
               field containing the size in bytes of the array of struct
               ranlib descriptors encoded as a C long value.

               The array of struct ranlib descriptors follows the size field.
               Each struct ranlib descriptor describes one symbol.

               A struct ranlib descriptor comprises two fields:
               ran_strx     (C long) This field contains the zero-based offset
                            of the symbol name in the symbol string table.
               ran_off      (C long) This field is the file offset to the
                            archive header for the archive member defining the
                            symbol.

               The part containing the symbol string table begins with a field
               containing the size in bytes of the string table, encoded as a
               C long value.  This string table follows the size field, and
               contains NUL-terminated strings for the symbols in the symbol
               table.

     SVR4/GNU  In the SVR4/GNU archive format, the archive symbol table starts
               with a 4-byte binary value containing the number of entries
               contained in the archive symbol table.  This count of entries
               is stored most significant byte first.

               Next, there are count 4-byte numbers, each stored most
               significant byte first.  Each number is a binary offset to the
               archive header for the member in the archive file for the
               corresponding symbol table entry.

               After the binary offset values, there are count NUL-terminated
               strings in sequence, holding the symbol names for the
               corresponding symbol table entries.

STANDARDS COMPLIANCE
     The ar(1) archive format is not currently specified by a standard.

     This manual page documents the ar(1) archive formats used by the 4.4BSD
     and UNIX SVR4 operating system releases.

SEE ALSO
     ar(1), ld(1), ranlib(1), elf(3), elf_getarsym(3), elf_rand(3)

FreeBSD 11.0-PRERELEASE        November 28, 2010       FreeBSD 11.0-PRERELEASE

NAME | SYNOPSIS | DESCRIPTION | STANDARDS COMPLIANCE | SEE ALSO

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

home | help