An archive is a collection of files stored and treated as a single entity. They are used most commonly to implement libraries of relocatable objects. These libraries simplify linking in a program development environment by allowing the manipulation of one archive file instead of dozens or hundreds of object files.
This chapter covers the archive file format and usage. The archiver is the tool used to create and manage archives. See ar(1) for more information on its facilities.
New and Change Archive Features
Version 5.0 of Tru64 UNIX introduces archive support for extended user and group ids (see ar_uid and ar_gid in Section 8.1.2)
All declarations in this section are from the header file ar.h.
See Section 8.2.1 for more information on the organization of object file contents.
The archive magic string identifies a file as an archive.
#define ARMAG "!<arch>\n" #define SARMAG 8
struct ar_hdr {
char ar_name[16];
char ar_date[12];
char ar_uid[6];
char ar_gid[6];
char ar_mode[8];
char ar_size[10];
char ar_fmag[2];
} AR_HDR;
SIZE - 60 bytes, ALIGNMENT - 1 byte
Archive Header Fields
ar_name /offset where offset indicates the byte offset of the file name within the table. The offset is a decimal number.ARSYMPREF, defined as the 16-byte blank-terminated character string ________64ELEL_, is stored in this field for the special file member called the symbol definitions (symdef) file and is used to identify that file. The ar tool marks an out of date symdef file by changing the last L in the name to an X (________64ELEX_).// is stored in this field to identify the file member name table. ar_date ar_uid USHRT_MAX (65535U), this field will contain //value where value is a 4-byte unsigned integer. ar_gid USHRT_MAX (65535U), this field will contain //value where value is a 4-byte unsigned integer.ar_mode ar_size ar_size field indicates an odd length, it should be rounded up to the next even number.ar_fmag
|
|
|
|
|
|
|
|
|
General Note:
Archive header fields are stored as character strings and must be converted to numeric types.
This structure is found only inside the special file member called the "symdef file". See Section 8.2.2 for related information.
struct ranlib {
union {
int ran_strx;
} ran_un;
int ran_off;
};
SIZE - 8 bytes, ALIGNMENT - 4 bytes
Ranlib Structure Fields
ran_strx ran_off General Note :
The ran_un union of this structure has only one field, as shown, for historical reasons.
The first SARMAG (8) bytes in an archive file identify it as an archive. To verify that a file is an archive, these bytes should be compared with the archive magic string, defined as ARMAG in the header file ar.h.
An archive file consists of the magic string followed by multiple file members, each of which is preceded by an archive file member header. File members can be object files, compressed object files, text files, or files of any other type, and an archive can contain a mix of file types. A file member can also be one of two special file members: the symbol definition (or symdef file) or the file member name table. Figure 8-1 illustrates this file layout.
The symdef file, if present, is the first file member of an archive. See Section 8.2.2 for details on the symdef file.
The file member name table consists of file member names that are too long to fit into the 16-byte name field of the archive header. If no file member names are 16 characters or longer, this table is not created. If the table is needed, it is the first or second file member. If a symdef file is present, it is the first file member and the file member name table is the second. Otherwise, the file member name table is the first file member of the archive.
The member header for the file name table might look like this:
struct arhdr {
ar_name = "// ";
ar_date = "871488454 ";
ar_uid = "0 ";
ar_gid = "0 ";
ar_mode = "0 ";
ar_size = "54 ";
ar_fmag = "'\n";
}
Names in the file member name table are separated by a slash (/) and a linefeed (\n). For example, the contents of the file name table for an archive with three long object file names might look like this:
st_cmrlc_basic.o/ st_cmrlc_print.o/ st_object_type.o/
The file member header for a file member whose name is stored in the file name table (in this case, the object st_cmrlc_print.o) might look like this:
struct arhdr {
ar_name = "/18 ";
ar_date = "871414955 ";
ar_uid = "9442 ";
ar_gid = "0 ";
ar_mode = "100600 ";
ar_size = "47296 ";
ar_fmag = "'\n";
}
The symdef file contains external symbol information for all object file members within an archive. When present, the symdef file is the first file member of the archive. The member header for an up-to-date symdef file might look as follows:
struct arhdr {
ar_name = "_________64ELEL_ ";
ar_date = "871488454 ";
ar_uid = "0 ";
ar_gid = "0 ";
ar_mode = "0 ";
ar_size = "8238 ";
ar_fmag = "'\n";
}
The symdef file is typically present if at least one archive file member is an object file. The linker uses it when searching for symbol definitions, as long as the file is up to date. Whenever an archive is modified, either the symdef file must either be updated or its member name must be changed to reflect the fact that it is outdated (see Section 8.1.2).
The symdef file consists of a hash table and a string table. The contents of the symdef file are laid out as follows:
ranlib structures in the hash table
ranlib structures
At a minimum, the symdef file should contain the sizes of the hash and string tables, even if the tables are empty.
The hash table contains a ran_lib structure for each externally visible symbol defined in any of the archive file members. The total size of the hash table is two times the number of symbols rounded to the next highest power of two. Each symbol has a private hash chain that is used for symbol lookup, as shown in Figure 8-2.
The hash function produces two values for any name it is given: a hash value and a rehash value. The hash value is used for the first lookup. If the symbol found is not the right one, the rehash value is used for chaining. The chain is followed until the correct symbol is found or until the search returns to the symbol where it began.
The linker uses the hash structure field ran_off to locate a symbol's definition in the archive. This field contains the byte offset from the beginning of the archive file to the file member header of the member containing the symbol's definition.
Note that symbols appear only once in the symdef file hash table, regardless of how many file members define them.
One important use of archives is to serve as static libraries that programs can link against. Such archives contain a collection of relocatable object files that can be selectively included in an executable image as required. Archive libraries are the only libraries used in creating static executables. They can also be used in conjunction with shared libraries in dynamic executables.
The linker searches archive libraries during symbol resolution. See the Programmer's Guide or ld(1) for more information.
The archive file format is designed to meet current UNIX standards in order to assure portability with other UNIX systems.
The format of compressed object files within archives is specific to Tru64 UNIX. See Section 1.4.3 for details.