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) utili-
     ties.  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 ar-
     chive 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 pad-
     ding 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 sec-
		 onds 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	com-
		 bined 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	con-
	       tain 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 immedi-
	       ately after the archive header and the ar_name field of the ar-
	       chive 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 fol-
	       lows 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	corre-
     sponding 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 ta-
	       ble.  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 ar-
			    chive 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 signifi-
	       cant 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 corre-
	       sponding	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	9.2		       November	28, 2010		   FreeBSD 9.2

NAME | SYNOPSIS | DESCRIPTION | STANDARDS COMPLIANCE | SEE ALSO

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

home | help