diff options
Diffstat (limited to 'share/man')
| -rw-r--r-- | share/man/man5/Makefile | 1 | ||||
| -rw-r--r-- | share/man/man5/ar.5 | 234 |
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 |
