Add a manual page documenting the format of `ar' archives.

Reviewed by:	Kai Wang <kaiw27 at gmail dot com>
Approved by:	re (bmah)

2 files changed, 235 insertions, 0 deletions

diff --git a/share/man/man5/Makefile b/share/man/man5/Makefile
index 52a1aec..3e1d832 100644
--- a/share/man/man5/Makefile
+++ b/share/man/man5/Makefile
@@ -5,6 +5,7 @@
 
 #MISSING: dump.5 plot.5
 MAN=	acct.5 \
+	ar.5 \
 	a.out.5 \
 	bluetooth.device.conf.5 \
 	bluetooth.hosts.5 \
diff --git a/share/man/man5/ar.5 b/share/man/man5/ar.5
new file mode 100644
index 0000000..1796795
--- /dev/null
+++ b/share/man/man5/ar.5
@@ -0,0 +1,234 @@
+.\" 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