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