turns printfs back on

[freebsd-src/fkvm-freebsd.git] / share / man / man5 / ar.5

.\" 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 07, 2007
.Os
.Dt AR 5
.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