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