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.\" $Id: ar.5 3642 2018-10-14 14:24:28Z jkoshy $ 25.\" 26.Dd September 30, 2018 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.Xr ar 5 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. 87This field names a leaf file; absolute paths and relative paths containing 88directory names are not supported. 89The format of this field varies between the BSD and SVR4/GNU formats and 90is described in more detail in the section 91.Sx "Representing File Names" 92below. 93.It Ar ar_date 94(12 bytes) The file modification time for the member in seconds since the 95epoch, encoded as a decimal number. 96.It Ar ar_uid 97(6 bytes) The uid associated with the archive member, encoded as a 98decimal number. 99.It Ar ar_gid 100(6 bytes) The gid associated with the archive member, encoded as a 101decimal number. 102.It Ar ar_mode 103(8 bytes) The file mode for the archive member, encoded as an octal 104number. 105.It Ar ar_size 106(10 bytes) In the SVR4/GNU archive format this field holds the size in 107bytes of the archive member, encoded as a decimal number. 108In the BSD archive format, for short file names, this field 109holds the size in bytes of the archive member, encoded as a decimal 110number. 111For long file names 112.Po 113see 114.Sx "Representing File Names" 115below 116.Pc , 117the field contains the combined size of the 118archive member and its file name, encoded as a decimal number. 119.It Ar ar_fmag 120(2 bytes) This field holds 2 bytes with values 0x96 and 0x0A 121respectively, marking the end of the header. 122.El 123.Pp 124Unused bytes in the fields of an archive header are set to the value 1250x20. 126.Ss "Representing File Names" 127The BSD and SVR4/GNU variants use different schemes for encoding file 128names for members. 129.Bl -tag -width "SVR4/GNU" 130.It "BSD" 131File names that are up to 16 bytes long and which do not contain 132embedded spaces are stored directly in the 133.Ar ar_name 134field of the archive header. 135File names that are either longer than 16 bytes or which contain 136embedded spaces are stored immediately after the archive header 137and the 138.Ar ar_name 139field of the archive header is set to the string 140.Dq "#1/" 141followed by a decimal representation of the number of bytes needed for 142the file name. 143In addition, the 144.Ar ar_size 145field of the archive header is set to the decimal representation of 146the combined sizes of the archive member and the file name. 147The file contents of the member follows the file name without further 148padding. 149.Pp 150As an example, if the file name for a member was 151.Dq "A B" 152and its contents was the string 153.Dq "C D" , 154then the 155.Ar ar_name 156field of the header would contain 157.Dq Li "#1/3" , 158the 159.Ar ar_size 160field of the header would contain 161.Dq Li 6 , 162and the bytes immediately following the header would be 0x41, 0x20, 1630x42, 0x43, 0x20 and 0x44 164.Po 165ASCII 166.Dq "A BC D" 167.Pc . 168.It "SVR4/GNU" 169File names that are up to 15 characters long are stored directly in the 170.Ar ar_name 171field of the header, terminated by a 172.Dq Li / 173character. 174.Pp 175If the file name is larger than would fit in space for the 176.Ar ar_name 177field, then the actual file name is kept in the archive 178string table 179.Po 180see 181.Sx "Archive String Tables" 182below 183.Pc , 184and the decimal offset of the file name in the string table is stored 185in the 186.Ar ar_name 187field, prefixed by a 188.Dq Li / 189character. 190.Pp 191As an example, if the real file name has been stored at offset 768 in 192the archive string table, the 193.Ar ar_name 194field of the header will contain the string 195.Dq /768 . 196.El 197.Ss "Special Archive Members" 198The following archive members are special. 199.Bl -tag -width indent 200.It Dq Li / 201In the SVR4/GNU variant of the archive format, the archive member with 202name 203.Dq Li / 204denotes an archive symbol table. 205If present, this member will be the very first member in the 206archive. 207.It Dq Li // 208In the SVR4/GNU variant of the archive format, the archive member with 209name 210.Dq Li // 211denotes the archive string table. 212This special member is used to hold filenames that do not fit in the 213file name field of the header 214.Po 215see 216.Sx "Representing File Names" 217above 218.Pc . 219If present, this member immediately follows the archive symbol table 220if an archive symbol table is present, or is the first member otherwise. 221.It Dq Li "__.SYMDEF" 222This special member contains the archive symbol table in the BSD 223variant of the archive format. 224If present, this member will be the very first member in the 225archive. 226.El 227.Ss "Archive String Tables" 228An archive string table is used in the SVR4/GNU archive format to hold 229file names that are too large to fit into the constraints of the 230.Ar ar_name 231field of the archive header. 232An archive string table contains a sequence of file names. 233Each file name in the archive string table is terminated by the 234byte sequence 0x2F, 0x0A 235.Po 236the ASCII string 237.Dq "/\en" 238.Pc . 239No padding is used to separate adjacent file names. 240.Ss "Archive Symbol Tables" 241Archive symbol tables are used to speed up link editing by providing a 242mapping between the program symbols defined in the archive 243and the corresponding archive members. 244Archive symbol tables are managed by the 245.Xr ranlib 1 246utility. 247.Pp 248The format of archive symbol tables is as follows: 249.Bl -tag -width "SVR4/GNU" 250.It BSD 251In the BSD archive format, the archive symbol table comprises 252of two parts: a part containing an array of 253.Vt "struct ranlib" 254descriptors, followed by a part containing a symbol string table. 255The sizes and layout of the structures that make up a BSD format 256archive symbol table are machine dependent. 257.Pp 258The part containing 259.Vt "struct ranlib" 260descriptors begins with a field containing the size in bytes of the 261array of 262.Vt "struct ranlib" 263descriptors encoded as a C 264.Vt long 265value. 266.Pp 267The array of 268.Vt "struct ranlib" 269descriptors follows the size field. 270Each 271.Vt "struct ranlib" 272descriptor describes one symbol. 273.Pp 274A 275.Vt "struct ranlib" 276descriptor comprises two fields: 277.Bl -tag -width "Ar ran_strx" -compact 278.It Ar ran_strx 279.Pq C Vt long 280This field contains the zero-based offset of the symbol name in the 281symbol string table. 282.It Ar ran_off 283.Pq C Vt long 284This field is the file offset to the archive header for the archive 285member defining the symbol. 286.El 287.Pp 288The part containing the symbol string table begins with a field 289containing the size in bytes of the string table, encoded as a C 290.Vt long 291value. 292This string table follows the size field, and contains 293NUL-terminated strings for the symbols in the symbol table. 294.It SVR4/GNU 295In the SVR4/GNU archive format, the archive symbol table starts with a 2964-byte binary value containing the number of entries contained in the 297archive symbol table. 298This count of entries is stored most significant byte first. 299.Pp 300Next, there are 301.Ar count 3024-byte numbers, each stored most significant byte first. 303Each number is a binary offset to the archive header for the member in 304the archive file for the corresponding symbol table entry. 305.Pp 306After the binary offset values, there are 307.Ar count 308NUL-terminated strings in sequence, holding the symbol names for 309the corresponding symbol table entries. 310.El 311.Sh STANDARDS COMPLIANCE 312The 313.Xr ar 1 314archive format is not currently specified by a standard. 315.Pp 316This manual page documents the 317.Xr ar 1 318archive formats used by the 319.Bx 4.4 320and 321.Ux SVR4 322operating system releases. 323.Sh SEE ALSO 324.Xr ar 1 , 325.Xr ld 1 , 326.Xr ranlib 1 , 327.Xr elf 3 , 328.Xr elf_getarsym 3 , 329.Xr elf_rand 3 330