share/man/man5/ar.5

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