NAME

ar −  extended common archive file format

DESCRIPTION

The archive command ar(1) is used to combine several files into one.  Archives are used mainly as libraries to be searched by the link editor ld(1). 

Each archive begins with the archive magic string. 

 #define  ARMAG   "!<arch>\n"/∗ magic string ∗/
#define  SARMAG  8/∗ length of magic string ∗/
 

Each archive which contains common object files (see a.out(4)) includes an archive symbol table.  This symbol table is used by the link editor ld(1) to determine which archive members must be loaded during the link edit process.  The archive symbol table (if it exists) is always the first file in the archive (but is never listed) and is automatically created and/or updated by ar.  The archive file member name table (if it exists) is always the next file in the archive.  It is never listed and is automatically created and/or updated by ar. 

Following the archive magic string are the archive file members.  Each file member is preceded by a file member header which is of the following format:

 #define  ARFMAG    "’\n"/∗ header trailer string ∗/
 struct  ar_hdr/∗ file member header ∗/
{
    char    ar_name[16];/∗ file member name ∗/
    char    ar_date[12];/∗ file member date ∗/
    char    ar_uid[6];/∗ file member user identification ∗/
    char    ar_gid[6];/∗ file member group identification ∗/
    char    ar_mode[8];/∗ file member mode (octal) ∗/
    char    ar_size[10];/∗ file member size ∗/
    char    ar_fmag[2];/∗ header trailer string ∗/
};
 

All information in the file member headers is in printable ASCII.  The numeric information contained in the headers is stored as decimal numbers (except for ar_mode which is in octal).  Thus, if the archive contains printable files, the archive itself is printable. 

If the file member name is 14 characters or less, the ar_name field is blank-padded and slash (/) terminated.  Otherwise, the ar_name field begins with a slash (/) and contains an ascii string giving the offset of the long file member name in the file member name table.  The ar_date field is the modification date of the file at the time of its insertion into the archive.  Common format archives can be moved from system to system as long as the portable archive command ar(1) is used. 

Each archive file member begins on an even byte boundary; a newline is inserted between files if necessary.  Nevertheless the size given reflects the actual size of the file exclusive of padding. 

Notice there is no provision for empty areas in an archive file. 

If the archive symbol table exists, the first file in the archive has a zero-length name (i.e., ar_name[0] == ’/’).  The remaining 15 characters are blanks.  The contents of this file are as follows:

• The number of symbols.  Length: 4 bytes. 

• The array of offsets into the archive file.  Length: 4 bytes ∗ ”the number of symbols”. 

• The name string table.  Length: ar_size − (4 bytes ∗ (”the number of symbols” + 1)). 

The number of symbols and the array of offsets are managed with sgetl and sputl. The string table contains exactly as many null terminated strings as there are elements in the offsets array. Each offset from the array is associated with the corresponding name from the string table (in order). The names in the string table are all the defined global symbols found in the common object files in the archive. Each offset is the location of the archive header for the associated symbol.

If the archive file member name table exists, the next file in the archive has a name of slash (/) (i.e., ar_name[0] == ’/’ and ar_name[1] == ’/’).  The contents of this file are successive strings of long file names.  Each string is terminated with a slash (/) and a carriage return (\n).  The offset of a particular name within this string table appears as the ar_name field of the corresponding archive file member. 

When the size of the symbol table file is larger than its contents, the archive is a fast-updating archive.  When a fast-updating archive is created, (or anytime it becomes necessary to rewrite the whole archive), the symbol table file is made 20% plus 1 byte bigger than it needs to be to contain the symbol table.  This allows the addition of more entries without rewriting the whole archive.  When files are replaced, the old version is marked deleted and the new one as appended to the end of the archive.  Deleted entries have names beging with "///".  Whenever the symbol table fills up, the whole archive is rewritten (This also removes deleted files from it). 

SEE ALSO

sputl(3X), a.out(4). 
ar(1), ld(1), strip(1) in the CX/UX User’s Reference Manual. 

Strip(1) will remove all archive symbol entries from the header.  The archive symbol entries must be restored via the ts option of the ar(1) command before the archive can be used with the link editor ld(1). 

CX/UX Programmer’s Reference Manual