aa12cea2cc
Although groff_mdoc(7) gives another impression, this is the ordering most widely used and also required by mdocml/mandoc. Reviewed by: ru Approved by: philip, ed (mentors)
235 lines
7.4 KiB
Groff
235 lines
7.4 KiB
Groff
.\" Copyright (c) 2007 Joseph Koshy. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" This software is provided by Joseph Koshy ``as is'' and
|
|
.\" any express or implied warranties, including, but not limited to, the
|
|
.\" implied warranties of merchantability and fitness for a particular purpose
|
|
.\" are disclaimed. in no event shall Joseph Koshy be liable
|
|
.\" for any direct, indirect, incidental, special, exemplary, or consequential
|
|
.\" damages (including, but not limited to, procurement of substitute goods
|
|
.\" or services; loss of use, data, or profits; or business interruption)
|
|
.\" however caused and on any theory of liability, whether in contract, strict
|
|
.\" 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
|
|
.\" such damage.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd September 7, 2007
|
|
.Dt AR 5
|
|
.Os
|
|
.Sh NAME
|
|
.Nm ar
|
|
.Nd format of archives managed by ar(1) and ranlib(1)
|
|
.Sh SYNOPSIS
|
|
.In ar.h
|
|
.Sh DESCRIPTION
|
|
An archive managed by the
|
|
.Xr ar 1
|
|
and
|
|
.Xr ranlib 1
|
|
utilities is a single file that stores the individual members of the
|
|
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
|
|
defines constants and structures used to describe the layout
|
|
of these archives.
|
|
.Ss Archive Layout
|
|
.Xr ar 1
|
|
archives start with a string of magic bytes
|
|
.Qq !<arch>\en
|
|
(constant
|
|
.Dv ARMAG
|
|
in header
|
|
.In ar.h ) .
|
|
The content of the archive follows the magic bytes.
|
|
Each member stored in the archive is preceded by a fixed size
|
|
archive header that stores file permissions, last modification
|
|
time, the owner, and the group of the archived file.
|
|
.Pp
|
|
Archive headers start at an even byte offset in the archive
|
|
file.
|
|
If the length of the preceding archive member was odd, then an extra
|
|
newline character
|
|
.Dq "\en"
|
|
is used as padding.
|
|
.Pp
|
|
The archive header comprises six fixed-size ASCII strings followed
|
|
by a two character trailer (see
|
|
.Vt "struct ar_hdr"
|
|
in header file
|
|
.In ar.h Ns ):
|
|
.Bd -literal
|
|
struct ar_hdr {
|
|
char ar_name[16]; /* name */
|
|
char ar_date[12]; /* modification time */
|
|
char ar_uid[6]; /* user id */
|
|
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
|
|
Unused characters in the header are filled with space (ASCII 20H)
|
|
characters.
|
|
Each field of the header abuts the next without additional padding.
|
|
.Pp
|
|
The members of the archive header are as follows:
|
|
.Bl -tag -width "Va ar_name" -compact
|
|
.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
|
|
.Va ar_size
|
|
field of the header (see below) will then hold the sum of the size of
|
|
the file name and the size of the member.
|
|
.It SVR4/GNU
|
|
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
|
|
The format of the symbol table depends on the format variant:
|
|
.Bl -tag -width "SVR4/GNU" -compact
|
|
.It BSD
|
|
In the BSD variant, the symbol table has 4 parts encoded in
|
|
a machine dependent manner:
|
|
.Bl -enum -compact
|
|
.It
|
|
The first part is a binary value containing size in bytes of the
|
|
second part encoded as a C
|
|
.Dq long .
|
|
.It
|
|
The second part is a list of
|
|
.Vt struct ranlib
|
|
structures (see
|
|
.In ranlib.h Ns ).
|
|
Each ranlib structure describes one symbol and comprises of
|
|
two C
|
|
.Dq long
|
|
values.
|
|
The first
|
|
.Dq long
|
|
is a zero-based offset into the string table in the fourth part
|
|
for the symbol's name.
|
|
The second
|
|
.Dq long
|
|
is an offset from the beginning of the archive to the start
|
|
of the archive header for the member that defines the symbol.
|
|
.It
|
|
The third part is a binary value denoting the length of the
|
|
string table contained in the fourth part.
|
|
.It
|
|
The fourth part is a string table containing NUL-terminated
|
|
strings.
|
|
.El
|
|
.It SVR4/GNU
|
|
In the SVR4/GNU variant, the symbol table comprises of three parts
|
|
which follow each other without padding:
|
|
.Bl -enum -compact
|
|
.It
|
|
The first part comprises of a count of entries in the symbol table,
|
|
stored a 4 byte binary value in MSB first order.
|
|
.It
|
|
The next part is an array of 4 byte file offsets within the archive
|
|
to archive header for members that define the symbol in question.
|
|
Each offset in stored in MSB first order.
|
|
.It
|
|
The third part is a string table, that contains NUL-terminated
|
|
strings for the symbols in the symbol table.
|
|
.El
|
|
.El
|
|
.Ss Archive String Table
|
|
In the SVR4/GNU variant of the
|
|
.Xr ar 1
|
|
archive format, long file names are stored in a separate
|
|
archive string table and referenced from the archive header
|
|
for each member.
|
|
Each file name is terminated by the string
|
|
.Qq /\en .
|
|
The string table itself has a name of
|
|
.Qq // .
|
|
.Sh SEE ALSO
|
|
.Xr ar 1 ,
|
|
.Xr ranlib 1 ,
|
|
.Xr archive 3 ,
|
|
.Xr elf 3 ,
|
|
.Xr gelf 3 ,
|
|
.Xr elf 5
|