1.\" Copyright (c) 2007 Joseph Koshy. All rights reserved. 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 6.\" 1. Redistributions of source code must retain the above copyright 7.\" notice, this list of conditions and the following disclaimer. 8.\" 2. Redistributions in binary form must reproduce the above copyright 9.\" notice, this list of conditions and the following disclaimer in the 10.\" documentation and/or other materials provided with the distribution. 11.\" 12.\" This software is provided by Joseph Koshy ``as is'' and 13.\" any express or implied warranties, including, but not limited to, the 14.\" implied warranties of merchantability and fitness for a particular purpose 15.\" are disclaimed. in no event shall Joseph Koshy be liable 16.\" for any direct, indirect, incidental, special, exemplary, or consequential 17.\" damages (including, but not limited to, procurement of substitute goods 18.\" or services; loss of use, data, or profits; or business interruption) 19.\" however caused and on any theory of liability, whether in contract, strict 20.\" liability, or tort (including negligence or otherwise) arising in any way 21.\" out of the use of this software, even if advised of the possibility of 22.\" such damage. 23.\" 24.\" $FreeBSD$ 25.\" 26.Dd September 07, 2007 27.Os 28.Dt AR 5 29.Sh NAME 30.Nm ar 31.Nd format of archives managed by ar(1) and ranlib(1) 32.Sh SYNOPSIS 33.In ar.h 34.Sh DESCRIPTION 35An archive managed by the 36.Xr ar 1 37and 38.Xr ranlib 1 39utilities is a single file that stores the individual members of the 40archive along with metadata for each member. 41There are two major variants of the 42.Xr ar 1 43archive format, the BSD variant and the SVR4/GNU variant. 44Both variants are described by this manual page. 45.Pp 46The header file 47.In ar.h 48defines constants and structures used to describe the layout 49of these archives. 50.Ss Archive Layout 51.Xr ar 1 52archives start with a string of magic bytes 53.Qq !<arch>\en 54(constant 55.Dv ARMAG 56in header 57.In ar.h ) . 58The content of the archive follows the magic bytes. 59Each member stored in the archive is preceded by a fixed size 60archive header that stores file permissions, last modification 61time, the owner, and the group of the archived file. 62.Pp 63Archive headers start at an even byte offset in the archive 64file. 65If the length of the preceding archive member was odd, then an extra 66newline character 67.Dq "\en" 68is used as padding. 69.Pp 70The archive header comprises six fixed-size ASCII strings followed 71by a two character trailer (see 72.Vt "struct ar_hdr" 73in header file 74.In ar.h Ns ): 75.Bd -literal 76struct ar_hdr { 77 char ar_name[16]; /* name */ 78 char ar_date[12]; /* modification time */ 79 char ar_uid[6]; /* user id */ 80 char ar_gid[6]; /* group id */ 81 char ar_mode[8]; /* octal file permissions */ 82 char ar_size[10]; /* size in bytes */ 83 char ar_fmag[2]; /* consistency check */ 84}; 85.Ed 86.Pp 87Unused characters in the header are filled with space (ASCII 20H) 88characters. 89Each field of the header abuts the next without additional padding. 90.Pp 91The members of the archive header are as follows: 92.Bl -tag -width "Va ar_name" -compact 93.It Va ar_date 94This field holds the decimal representation of the 95modification time, in seconds since the epoch, of the archive 96member. 97.It Va ar_fmag 98This trailer field holds the two characters 99.Qq `\en 100(constant 101.Dv ARFMAG 102defined in header file 103.In ar.h Ns ), 104and is used for consistency checks. 105.It Va ar_gid 106This field holds the decimal representation of the numeric 107user id of the creator of the member. 108.It Va ar_mode 109This field holds octal representation of the file permissions 110for the member. 111.It Va ar_name 112This field holds the name of an archive member. 113The usage of this field depends on the format variant: 114.Bl -tag -width "SVR4/GNU" -compact 115.It BSD 116In the BSD variant, names that are shorter than 16 characters and 117without embedded spaces are stored directly in this field. 118If a name has an embedded space, or if it is longer than 16 119characters, then the string 120.Qq "#1/" 121followed by the decimal representation of the length of the file name 122is placed in this field. 123The actual file name is stored immediately after the archive header. 124The content of the archive member follows the file name. 125The 126.Va ar_size 127field of the header (see below) will then hold the sum of the size of 128the file name and the size of the member. 129.It SVR4/GNU 130In the SVR4/GNU variant, names up to 15 characters in length are 131stored directly in this field, and are terminated by a 132.Qq / 133(ASCII 2FH) character. 134Names larger than 15 characters in length are stored in a special 135archive string table member (see 136.Sx "Archive String Table" 137below), and the 138.Va ar_name 139field holds the string 140.Qq "/" 141followed by the decimal representation of the offset in the archive 142string table of the actual name. 143.El 144.It Va ar_size 145In the SVR4/GNU variant, this field holds the decimal representation 146of actual size in bytes of the archived file. 147In the BSD variant, for member names that use the 148.Va ar_name 149field directly, this field holds the decimal representation of the 150actual size in bytes of the archived member. 151For member names that use the extension mechanism described above, the 152field will hold the sum of the sizes, in bytes, of the filename and the 153archive member. 154.It Va ar_uid 155This field holds the decimal representation of the numeric 156group id of the creator of the member. 157.El 158.Ss Archive Symbol Table 159An archive may additionally contain an archive symbol table 160used by the link editor, 161.Xr ld 1 . 162This symbol table has the member name 163.Qq __.SYMDEF 164in the BSD variant of the archive format, and the name 165.Qq / 166in the SVR4/GNU variant. 167.Pp 168The format of the symbol table depends on the format variant: 169.Bl -tag -width "SVR4/GNU" -compact 170.It BSD 171In the BSD variant, the symbol table has 4 parts encoded in 172a machine dependent manner: 173.Bl -enum -compact 174.It 175The first part is a binary value containing size in bytes of the 176second part encoded as a C 177.Dq long . 178.It 179The second part is a list of 180.Vt struct ranlib 181structures (see 182.In ranlib.h Ns ). 183Each ranlib structure describes one symbol and comprises of 184two C 185.Dq long 186values. 187The first 188.Dq long 189is a zero-based offset into the string table in the fourth part 190for the symbol's name. 191The second 192.Dq long 193is an offset from the beginning of the archive to the start 194of the archive header for the member that defines the symbol. 195.It 196The third part is a binary value denoting the length of the 197string table contained in the fourth part. 198.It 199The fourth part is a string table containing NUL-terminated 200strings. 201.El 202.It SVR4/GNU 203In the SVR4/GNU variant, the symbol table comprises of three parts 204which follow each other without padding: 205.Bl -enum -compact 206.It 207The first part comprises of a count of entries in the symbol table, 208stored a 4 byte binary value in MSB first order. 209.It 210The next part is an array of 4 byte file offsets within the archive 211to archive header for members that define the symbol in question. 212Each offset in stored in MSB first order. 213.It 214The third part is a string table, that contains NUL-terminated 215strings for the symbols in the symbol table. 216.El 217.El 218.Ss Archive String Table 219In the SVR4/GNU variant of the 220.Xr ar 1 221archive format, long file names are stored in a separate 222archive string table and referenced from the archive header 223for each member. 224Each file name is terminated by the string 225.Qq /\en . 226The string table itself has a name of 227.Qq // . 228.Sh SEE ALSO 229.Xr ar 1 , 230.Xr ranlib 1 , 231.Xr archive 3 , 232.Xr elf 3 , 233.Xr gelf 3 , 234.Xr elf 5 235