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