d/freebsd-skq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

* Rewrite ar.5 mannual page to better document ar(1) archive format.

Browse Source 
* Use more standard BSD license.

Obtained from:	elftoolchain
This commit is contained in:
Kai Wang 2011-05-07 10:44:08 +00:00
parent ff98e4c515
commit 3860fcc7f0
1 changed files with 292 additions and 199 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

491
share/man/man5/ar.5
View File

@ -1,4 +1,4 @@
.\" Copyright (c) 2007 Joseph Koshy. All rights reserved. .\" Copyright (c) 2010 Joseph Koshy. All rights reserved.
.\" .\"
.\" Redistribution and use in source and binary forms, with or without .\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions .\" modification, are permitted provided that the following conditions
@ -9,226 +9,319 @@
.\" notice, this list of conditions and the following disclaimer in the .\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution. .\" documentation and/or other materials provided with the distribution.
.\" .\"
.\" This software is provided by Joseph Koshy ``as is'' and .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" any express or implied warranties, including, but not limited to, the .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" implied warranties of merchantability and fitness for a particular purpose .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" are disclaimed. in no event shall Joseph Koshy be liable .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" for any direct, indirect, incidental, special, exemplary, or consequential .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" damages (including, but not limited to, procurement of substitute goods .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" or services; loss of use, data, or profits; or business interruption) .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" however caused and on any theory of liability, whether in contract, strict .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" liability, or tort (including negligence or otherwise) arising in any way .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" out of the use of this software, even if advised of the possibility of .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" such damage. .\" SUCH DAMAGE.
.\" .\"
.\" $FreeBSD$ .\" $FreeBSD$
.\" .\"
.Dd September 7, 2007 .Dd November 28, 2010
.Dt AR 5
.Os .Os
.Dt AR 5
.Sh NAME .Sh NAME
.Nm ar .Nm ar
.Nd format of archives managed by ar(1) and ranlib(1) .Nd archive file format for
.Sh SYNOPSIS
.In ar.h
.Sh DESCRIPTION
An archive managed by the
.Xr ar 1 .Xr ar 1
and and
.Xr ranlib 1 .Xr ranlib 1
utilities is a single file that stores the individual members of the .Sh SYNOPSIS
archive along with metadata for each member.
There are two major variants of the
.Xr ar 1
archive format, the BSD variant and the SVR4/GNU variant.
Both variants are described by this manual page.
.Pp
The header file
.In ar.h .In ar.h
defines constants and structures used to describe the layout .Sh DESCRIPTION
of these archives.
.Ss Archive Layout
.Xr ar 1 .Xr ar 1
archives start with a string of magic bytes archives are created and managed by the
.Qq !<arch>\en .Xr ar 1
(constant and
.Dv ARMAG .Xr ranlib 1
in header utilities.
.In ar.h ) . These archives are typically used during program development to
The content of the archive follows the magic bytes. hold libraries of program objects.
Each member stored in the archive is preceded by a fixed size An
archive header that stores file permissions, last modification .Xr ar 1
time, the owner, and the group of the archived file. archive is contained in a single operating system file.
.Pp .Pp
Archive headers start at an even byte offset in the archive This manual page documents two variants of the
file. .Xr ar 1
If the length of the preceding archive member was odd, then an extra archive format: the BSD archive format, and the SVR4/GNU archive
newline character format.
.Dq "\en"
is used as padding.
.Pp .Pp
The archive header comprises six fixed-size ASCII strings followed In both variants the archive file starts with an identifying byte
by a two character trailer (see sequence of the seven ASCII characters
.Vt "struct ar_hdr" .Sq Li "!<arch>"
in header file followed by a ASCII linefeed character
.In ar.h Ns ): .Po
.Bd -literal see the constant
struct ar_hdr { .Dq ARMAG
char ar_name[16]; /* name */ in the header file
char ar_date[12]; /* modification time */ .In ar.h
char ar_uid[6]; /* user id */ .Pc .
char ar_gid[6]; /* group id */
char ar_mode[8]; /* octal file permissions */
char ar_size[10]; /* size in bytes */
char ar_fmag[2]; /* consistency check */
};
.Ed
.Pp .Pp
Unused characters in the header are filled with space (ASCII 20H) Archive members follow the initial identifying byte sequence.
characters. Each archive member is prefixed by a fixed size header describing the
Each field of the header abuts the next without additional padding. file attributes associated with the member.
.Pp .Ss "Archive Headers"
The members of the archive header are as follows: An archive header describes the file attributes for the archive member that
.Bl -tag -width "Va ar_name" -compact follows it.
.It Va ar_date
This field holds the decimal representation of the
modification time, in seconds since the epoch, of the archive
member.
.It Va ar_fmag
This trailer field holds the two characters
.Qq `\en
(constant
.Dv ARFMAG
defined in header file
.In ar.h Ns ),
and is used for consistency checks.
.It Va ar_gid
This field holds the decimal representation of the numeric
user id of the creator of the member.
.It Va ar_mode
This field holds octal representation of the file permissions
for the member.
.It Va ar_name
This field holds the name of an archive member.
The usage of this field depends on the format variant:
.Bl -tag -width "SVR4/GNU" -compact
.It BSD
In the BSD variant, names that are shorter than 16 characters and
without embedded spaces are stored directly in this field.
If a name has an embedded space, or if it is longer than 16
characters, then the string
.Qq "#1/"
followed by the decimal representation of the length of the file name
is placed in this field.
The actual file name is stored immediately after the archive header.
The content of the archive member follows the file name.
The The
.Va ar_size .Xr ar 5
field of the header (see below) will then hold the sum of the size of format only supports a limited number of attributes: the file name,
the file name and the size of the member. the file creation time stamp, the uid and gid of the creator, the file
.It SVR4/GNU mode and the file size.
In the SVR4/GNU variant, names up to 15 characters in length are
stored directly in this field, and are terminated by a
.Qq /
(ASCII 2FH) character.
Names larger than 15 characters in length are stored in a special
archive string table member (see
.Sx "Archive String Table"
below), and the
.Va ar_name
field holds the string
.Qq "/"
followed by the decimal representation of the offset in the archive
string table of the actual name.
.El
.It Va ar_size
In the SVR4/GNU variant, this field holds the decimal representation
of actual size in bytes of the archived file.
In the BSD variant, for member names that use the
.Va ar_name
field directly, this field holds the decimal representation of the
actual size in bytes of the archived member.
For member names that use the extension mechanism described above, the
field will hold the sum of the sizes, in bytes, of the filename and the
archive member.
.It Va ar_uid
This field holds the decimal representation of the numeric
group id of the creator of the member.
.El
.Ss Archive Symbol Table
An archive may additionally contain an archive symbol table
used by the link editor,
.Xr ld 1 .
This symbol table has the member name
.Qq __.SYMDEF
in the BSD variant of the archive format, and the name
.Qq /
in the SVR4/GNU variant.
.Pp .Pp
The format of the symbol table depends on the format variant: Archive headers are placed at an even byte offset in the archive file.
.Bl -tag -width "SVR4/GNU" -compact 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.
.Pp
An archive header comprises the following fixed sized fields:
.Bl -tag -width "Li ar_name"
.It Ar 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
.Sx "Representing File Names"
below.
.It Ar ar_date
(12 bytes) The file modification time for the member in seconds since the
epoch, encoded as a decimal number.
.It Ar ar_uid
(6 bytes) The uid associated with the archive member, encoded as a
decimal number.
.It Ar ar_gid
(6 bytes) The gid associated with the archive member, encoded as a
decimal number.
.It Ar ar_mode
(8 bytes) The file mode for the archive member, encoded as an octal
number.
.It Ar 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
.Po
see
.Sx "Representing File Names"
below
.Pc ,
the field contains the combined size of the
archive member and its file name, encoded as a decimal number.
.It Ar ar_fmag
(2 bytes) This field holds 2 bytes with values 0x96 and 0x0A
respectively, marking the end of the header.
.El
.Pp
Unused bytes in the fields of an archive header are set to the value
0x20.
.Ss "Representing File Names"
The BSD and SVR4/GNU variants use different schemes for encoding file
names for members.
.Bl -tag -width "SVR4/GNU"
.It "BSD"
File names that are upto 16 bytes long and which do not contain
embedded spaces are stored directly in the
.Ar 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 ar_name
field of the archive header is set to the string
.Dq "#1/"
followed by a decimal representation of the number of bytes needed for
the file name.
In addition, the
.Ar 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.
.Pp
As an example, if the file name for a member was
.Dq "A B"
and its contents was the string
.Dq "C D" ,
then the
.Ar ar_name
field of the header would contain
.Dq Li "#1/3" ,
the
.Ar ar_size
field of the header would contain
.Dq Li 6 ,
and the bytes immediately following the header would be 0x41, 0x20,
0x42, 0x43, 0x20 and 0x44
.Po
ASCII
.Dq "A BC D"
.Pc .
.It "SVR4/GNU"
File names that are upto 15 characters long are stored directly in the
.Ar ar_name
field of the header, terminated by a
.Dq Li /
character.
.Pp
If the file name is larger than would fit in space for the
.Ar ar_name
field, then the actual file name is kept in the archive
string table
.Po
see
.Sx "Archive String Tables"
below
.Pc ,
and the decimal offset of the file name in the string table is stored
in the
.Ar ar_name
field, prefixed by a
.Dq Li /
character.
.Pp
As an example, if the real file name has been stored at offset 768 in
the archive string table, the
.Ar ar_name
field of the header will contain the string
.Dq /768 .
.El
.Ss "Special Archive Members"
The following archive members are special.
.Bl -tag -width indent
.It Dq Li /
In the SVR4/GNU variant of the archive format, the archive member with
name
.Dq Li /
denotes an archive symbol table.
If present, this member will be the very first member in the
archive.
.It Dq Li //
In the SVR4/GNU variant of the archive format, the archive member with
name
.Dq Li //
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
.Po
see
.Sx "Representing File Names"
above
.Pc .
If present, this member immediately follows the archive symbol table
if an archive symbol table is present, or is the first member otherwise.
.It Dq Li "__.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.
.El
.Ss "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 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
.Po
the ASCII string
.Dq "/\en"
.Pc .
No padding is used to separate adjacent file names.
.Ss "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
.Xr ranlib 1
utility.
.Pp
The format of archive symbol tables is as follows:
.Bl -tag -width "SVR4/GNU"
.It BSD .It BSD
In the BSD variant, the symbol table has 4 parts encoded in In the BSD archive format, the archive symbol table comprises
a machine dependent manner: of two parts: a part containing an array of
.Bl -enum -compact .Vt "struct ranlib"
.It descriptors, followed by a part containing a symbol string table.
The first part is a binary value containing size in bytes of the The sizes and layout of the structures that make up a BSD format
second part encoded as a C archive symbol table are machine dependent.
.Dq long . .Pp
.It The part containing
The second part is a list of .Vt "struct ranlib"
.Vt struct ranlib descriptors begins with a field containing the size in bytes of the
structures (see array of
.In ranlib.h Ns ). .Vt "struct ranlib"
Each ranlib structure describes one symbol and comprises of descriptors encoded as a C
two C .Vt long
.Dq long value.
values. .Pp
The first The array of
.Dq long .Vt "struct ranlib"
is a zero-based offset into the string table in the fourth part descriptors follows the size field.
for the symbol's name. Each
The second .Vt "struct ranlib"
.Dq long descriptor describes one symbol.
is an offset from the beginning of the archive to the start .Pp
of the archive header for the member that defines the symbol. A
.It .Vt "struct ranlib"
The third part is a binary value denoting the length of the descriptor comprises two fields:
string table contained in the fourth part. .Bl -tag -width "Ar ran_strx" -compact
.It .It Ar ran_strx
The fourth part is a string table containing NUL-terminated .Pq C Vt long
strings. This field contains the zero-based offset of the symbol name in the
symbol string table.
.It Ar ran_off
.Pq C Vt long
This field is the file offset to the archive header for the archive
member defining the symbol.
.El .El
.Pp
The part containing the symbol string table begins with a field
containing the size in bytes of the string table, encoded as a C
.Vt long
value.
This string table follows the size field, and contains
NUL-terminated strings for the symbols in the symbol table.
.It SVR4/GNU .It SVR4/GNU
In the SVR4/GNU variant, the symbol table comprises of three parts In the SVR4/GNU archive format, the archive symbol table starts with a
which follow each other without padding: 4-byte binary value containing the number of entries contained in the
.Bl -enum -compact archive symbol table.
.It This count of entries is stored most significant byte first.
The first part comprises of a count of entries in the symbol table, .Pp
stored a 4 byte binary value in MSB first order. Next, there are
.It .Ar count
The next part is an array of 4 byte file offsets within the archive 4-byte numbers, each stored most significant byte first.
to archive header for members that define the symbol in question. Each number is a binary offset to the archive header for the member in
Each offset in stored in MSB first order. the archive file for the corresponding symbol table entry.
.It .Pp
The third part is a string table, that contains NUL-terminated After the binary offset values, there are
strings for the symbols in the symbol table. .Ar count
NUL-terminated strings in sequence, holding the symbol names for
the corresponding symbol table entries.
.El .El
.El .Sh STANDARDS COMPLIANCE
.Ss Archive String Table The
In the SVR4/GNU variant of the
.Xr ar 1 .Xr ar 1
archive format, long file names are stored in a separate archive format is not currently specified by a standard.
archive string table and referenced from the archive header .Pp
for each member. This manual page documents the
Each file name is terminated by the string .Xr ar 1
.Qq /\en . archive formats used by the
The string table itself has a name of .Bx 4.4
.Qq // . and
.Ux SVR4
operating system releases.
.Sh SEE ALSO .Sh SEE ALSO
.Xr ar 1 , .Xr ar 1 ,
.Xr ld 1 ,
.Xr ranlib 1 , .Xr ranlib 1 ,
.Xr archive 3 ,
.Xr elf 3 , .Xr elf 3 ,
.Xr gelf 3 , .Xr elf_getarsym 3 ,
.Xr elf 5 .Xr elf_rand 3