1.\" Copyright (c) 2010 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 THE AUTHOR AND CONTRIBUTORS ``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 THE AUTHOR OR CONTRIBUTORS 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.Dd November 28, 2010 25.Dt AR 5 26.Os 27.Sh NAME 28.Nm ar 29.Nd archive file format for 30.Xr ar 1 31and 32.Xr ranlib 1 33.Sh SYNOPSIS 34.In ar.h 35.Sh DESCRIPTION 36.Xr ar 1 37archives are created and managed by the 38.Xr ar 1 39and 40.Xr ranlib 1 41utilities. 42These archives are typically used during program development to 43hold libraries of program objects. 44An 45.Xr ar 1 46archive is contained in a single operating system file. 47.Pp 48This manual page documents two variants of the 49.Xr ar 1 50archive format: the BSD archive format, and the SVR4/GNU archive 51format. 52.Pp 53In both variants the archive file starts with an identifying byte 54sequence of the seven ASCII characters 55.Sq Li "!<arch>" 56followed by a ASCII linefeed character 57.Po 58see the constant 59.Dq ARMAG 60in the header file 61.In ar.h 62.Pc . 63.Pp 64Archive members follow the initial identifying byte sequence. 65Each archive member is prefixed by a fixed size header describing the 66file attributes associated with the member. 67.Ss "Archive Headers" 68An archive header describes the file attributes for the archive member that 69follows it. 70The 71.Nm 72format only supports a limited number of attributes: the file name, 73the file creation time stamp, the uid and gid of the creator, the file 74mode and the file size. 75.Pp 76Archive headers are placed at an even byte offset in the archive file. 77If the data for an archive member ends at an odd byte offset, then a 78padding byte with value 0x0A is used to position the next archive 79header on an even byte offset. 80.Pp 81An archive header comprises the following fixed sized fields: 82.Bl -tag -width "Li ar_name" 83.It Ar ar_name 84(16 bytes) The file name of the archive member. 85The format of this field varies between the BSD and SVR4/GNU formats and 86is described in more detail in the section 87.Sx "Representing File Names" 88below. 89.It Ar ar_date 90(12 bytes) The file modification time for the member in seconds since the 91epoch, encoded as a decimal number. 92.It Ar ar_uid 93(6 bytes) The uid associated with the archive member, encoded as a 94decimal number. 95.It Ar ar_gid 96(6 bytes) The gid associated with the archive member, encoded as a 97decimal number. 98.It Ar ar_mode 99(8 bytes) The file mode for the archive member, encoded as an octal 100number. 101.It Ar ar_size 102(10 bytes) In the SVR4/GNU archive format this field holds the size in 103bytes of the archive member, encoded as a decimal number. 104In the BSD archive format, for short file names, this field 105holds the size in bytes of the archive member, encoded as a decimal 106number. 107For long file names 108.Po 109see 110.Sx "Representing File Names" 111below 112.Pc , 113the field contains the combined size of the 114archive member and its file name, encoded as a decimal number. 115.It Ar ar_fmag 116(2 bytes) This field holds 2 bytes with values 0x96 and 0x0A 117respectively, marking the end of the header. 118.El 119.Pp 120Unused bytes in the fields of an archive header are set to the value 1210x20. 122.Ss "Representing File Names" 123The BSD and SVR4/GNU variants use different schemes for encoding file 124names for members. 125.Bl -tag -width "SVR4/GNU" 126.It "BSD" 127File names that are up to 16 bytes long and which do not contain 128embedded spaces are stored directly in the 129.Ar ar_name 130field of the archive header. 131File names that are either longer than 16 bytes or which contain 132embedded spaces are stored immediately after the archive header 133and the 134.Ar ar_name 135field of the archive header is set to the string 136.Dq "#1/" 137followed by a decimal representation of the number of bytes needed for 138the file name. 139In addition, the 140.Ar ar_size 141field of the archive header is set to the decimal representation of 142the combined sizes of the archive member and the file name. 143The file contents of the member follows the file name without further 144padding. 145.Pp 146As an example, if the file name for a member was 147.Dq "A B" 148and its contents was the string 149.Dq "C D" , 150then the 151.Ar ar_name 152field of the header would contain 153.Dq Li "#1/3" , 154the 155.Ar ar_size 156field of the header would contain 157.Dq Li 6 , 158and the bytes immediately following the header would be 0x41, 0x20, 1590x42, 0x43, 0x20 and 0x44 160.Po 161ASCII 162.Dq "A BC D" 163.Pc . 164.It "SVR4/GNU" 165File names that are up to 15 characters long are stored directly in the 166.Ar ar_name 167field of the header, terminated by a 168.Dq Li / 169character. 170.Pp 171If the file name is larger than would fit in space for the 172.Ar ar_name 173field, then the actual file name is kept in the archive 174string table 175.Po 176see 177.Sx "Archive String Tables" 178below 179.Pc , 180and the decimal offset of the file name in the string table is stored 181in the 182.Ar ar_name 183field, prefixed by a 184.Dq Li / 185character. 186.Pp 187As an example, if the real file name has been stored at offset 768 in 188the archive string table, the 189.Ar ar_name 190field of the header will contain the string 191.Dq /768 . 192.El 193.Ss "Special Archive Members" 194The following archive members are special. 195.Bl -tag -width indent 196.It Dq Li / 197In the SVR4/GNU variant of the archive format, the archive member with 198name 199.Dq Li / 200denotes an archive symbol table. 201If present, this member will be the very first member in the 202archive. 203.It Dq Li // 204In the SVR4/GNU variant of the archive format, the archive member with 205name 206.Dq Li // 207denotes the archive string table. 208This special member is used to hold filenames that do not fit in the 209file name field of the header 210.Po 211see 212.Sx "Representing File Names" 213above 214.Pc . 215If present, this member immediately follows the archive symbol table 216if an archive symbol table is present, or is the first member otherwise. 217.It Dq Li "__.SYMDEF" 218This special member contains the archive symbol table in the BSD 219variant of the archive format. 220If present, this member will be the very first member in the 221archive. 222.El 223.Ss "Archive String Tables" 224An archive string table is used in the SVR4/GNU archive format to hold 225file names that are too large to fit into the constraints of the 226.Ar ar_name 227field of the archive header. 228An archive string table contains a sequence of file names. 229Each file name in the archive string table is terminated by the 230byte sequence 0x2F, 0x0A 231.Po 232the ASCII string 233.Dq "/\en" 234.Pc . 235No padding is used to separate adjacent file names. 236.Ss "Archive Symbol Tables" 237Archive symbol tables are used to speed up link editing by providing a 238mapping between the program symbols defined in the archive 239and the corresponding archive members. 240Archive symbol tables are managed by the 241.Xr ranlib 1 242utility. 243.Pp 244The format of archive symbol tables is as follows: 245.Bl -tag -width "SVR4/GNU" 246.It BSD 247In the BSD archive format, the archive symbol table comprises 248of two parts: a part containing an array of 249.Vt "struct ranlib" 250descriptors, followed by a part containing a symbol string table. 251The sizes and layout of the structures that make up a BSD format 252archive symbol table are machine dependent. 253.Pp 254The part containing 255.Vt "struct ranlib" 256descriptors begins with a field containing the size in bytes of the 257array of 258.Vt "struct ranlib" 259descriptors encoded as a C 260.Vt long 261value. 262.Pp 263The array of 264.Vt "struct ranlib" 265descriptors follows the size field. 266Each 267.Vt "struct ranlib" 268descriptor describes one symbol. 269.Pp 270A 271.Vt "struct ranlib" 272descriptor comprises two fields: 273.Bl -tag -width "Ar ran_strx" -compact 274.It Ar ran_strx 275.Pq C Vt long 276This field contains the zero-based offset of the symbol name in the 277symbol string table. 278.It Ar ran_off 279.Pq C Vt long 280This field is the file offset to the archive header for the archive 281member defining the symbol. 282.El 283.Pp 284The part containing the symbol string table begins with a field 285containing the size in bytes of the string table, encoded as a C 286.Vt long 287value. 288This string table follows the size field, and contains 289NUL-terminated strings for the symbols in the symbol table. 290.It SVR4/GNU 291In the SVR4/GNU archive format, the archive symbol table starts with a 2924-byte binary value containing the number of entries contained in the 293archive symbol table. 294This count of entries is stored most significant byte first. 295.Pp 296Next, there are 297.Ar count 2984-byte numbers, each stored most significant byte first. 299Each number is a binary offset to the archive header for the member in 300the archive file for the corresponding symbol table entry. 301.Pp 302After the binary offset values, there are 303.Ar count 304NUL-terminated strings in sequence, holding the symbol names for 305the corresponding symbol table entries. 306.El 307.Sh STANDARDS COMPLIANCE 308The 309.Xr ar 1 310archive format is not currently specified by a standard. 311.Pp 312This manual page documents the 313.Xr ar 1 314archive formats used by the 315.Bx 4.4 316and 317.Ux SVR4 318operating system releases. 319.Sh SEE ALSO 320.Xr ar 1 , 321.Xr ld 1 , 322.Xr ranlib 1 , 323.Xr elf 3 , 324.Xr elf_getarsym 3 , 325.Xr elf_rand 3 326