share/man/man5/ar.5

   1 .\" Copyright (c) 2007 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 Joseph Koshy ``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 Joseph Koshy 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 September 07, 2007
  27 .Os
  28 .Dt AR 5
  29 .Sh NAME
  30 .Nm ar
  31 .Nd format of archives managed by ar(1) and ranlib(1)
  32 .Sh SYNOPSIS
  33 .In ar.h
  34 .Sh DESCRIPTION
  35 An archive managed by the
  36 .Xr ar 1
  37 and
  38 .Xr ranlib 1
  39 utilities is a single file that stores the individual members of the
  40 archive along with metadata for each member.
  41 There are two major variants of the
  42 .Xr ar 1
  43 archive format, the BSD variant and the SVR4/GNU variant.
  44 Both variants are described by this manual page.
  45 .Pp
  46 The header file
  47 .In ar.h
  48 defines constants and structures used to describe the layout
  49 of these archives.
  50 .Ss Archive Layout
  51 .Xr ar 1
  52 archives start with a string of magic bytes
  53 .Qq !<arch>\en
  54 (constant
  55 .Dv ARMAG
  56 in header
  57 .In ar.h ) .
  58 The content of the archive follows the magic bytes.
  59 Each member stored in the archive is preceded by a fixed size
  60 archive header that stores file permissions, last modification
  61 time, the owner, and the group of the archived file.
  62 .Pp
  63 Archive headers start at an even byte offset in the archive
  64 file.
  65 If the length of the preceding archive member was odd, then an extra
  66 newline character
  67 .Dq "\en"
  68 is used as padding.
  69 .Pp
  70 The archive header comprises six fixed-size ASCII strings followed
  71 by a two character trailer (see
  72 .Vt "struct ar_hdr"
  73 in header file
  74 .In ar.h Ns ):
  75 .Bd -literal
  76 struct ar_hdr {
  77         char ar_name[16];               /* name */
  78         char ar_date[12];               /* modification time */
  79         char ar_uid[6];                 /* user id */
  80         char ar_gid[6];                 /* group id */
  81         char ar_mode[8];                /* octal file permissions */
  82         char ar_size[10];               /* size in bytes */
  83         char ar_fmag[2];                /* consistency check */
  84 };
  85 .Ed
  86 .Pp
  87 Unused characters in the header are filled with space (ASCII 20H)
  88 characters.
  89 Each field of the header abuts the next without additional padding.
  90 .Pp
  91 The members of the archive header are as follows:
  92 .Bl -tag -width "Va ar_name" -compact
  93 .It Va ar_date
  94 This field holds the decimal representation of the
  95 modification time, in seconds since the epoch, of the archive
  96 member.
  97 .It Va ar_fmag
  98 This trailer field holds the two characters
  99 .Qq `\en
 100 (constant
 101 .Dv ARFMAG
 102 defined in header file
 103 .In ar.h Ns ),
 104 and is used for consistency checks.
 105 .It Va ar_gid
 106 This field holds the decimal representation of the numeric
 107 user id of the creator of the member.
 108 .It Va ar_mode
 109 This field holds octal representation of the file permissions
 110 for the member.
 111 .It Va ar_name
 112 This field holds the name of an archive member.
 113 The usage of this field depends on the format variant:
 114 .Bl -tag -width "SVR4/GNU" -compact
 115 .It BSD
 116 In the BSD variant, names that are shorter than 16 characters and
 117 without embedded spaces are stored directly in this field.
 118 If a name has an embedded space, or if it is longer than 16
 119 characters, then the string
 120 .Qq "#1/"
 121 followed by the decimal representation of the length of the file name
 122 is placed in this field.
 123 The actual file name is stored immediately after the archive header.
 124 The content of the archive member follows the file name.
 125 The
 126 .Va ar_size
 127 field of the header (see below) will then hold the sum of the size of
 128 the file name and the size of the member.
 129 .It SVR4/GNU
 130 In the SVR4/GNU variant, names up to 15 characters in length are
 131 stored directly in this field, and are terminated by a
 132 .Qq /
 133 (ASCII 2FH) character.
 134 Names larger than 15 characters in length are stored in a special
 135 archive string table member (see
 136 .Sx "Archive String Table"
 137 below), and the
 138 .Va ar_name
 139 field holds the string
 140 .Qq "/"
 141 followed by the decimal representation of the offset in the archive
 142 string table of the actual name.
 143 .El
 144 .It Va ar_size
 145 In the SVR4/GNU variant, this field holds the decimal representation
 146 of actual size in bytes of the archived file.
 147 In the BSD variant, for member names that use the
 148 .Va ar_name
 149 field directly, this field holds the decimal representation of the
 150 actual size in bytes of the archived member.
 151 For member names that use the extension mechanism described above, the
 152 field will hold the sum of the sizes, in bytes, of the filename and the
 153 archive member.
 154 .It Va ar_uid
 155 This field holds the decimal representation of the numeric
 156 group id of the creator of the member.
 157 .El
 158 .Ss Archive Symbol Table
 159 An archive may additionally contain an archive symbol table
 160 used by the link editor,
 161 .Xr ld 1 .
 162 This symbol table has the member name
 163 .Qq __.SYMDEF
 164 in the BSD variant of the archive format, and the name
 165 .Qq /
 166 in the SVR4/GNU variant.
 167 .Pp
 168 The format of the symbol table depends on the format variant:
 169 .Bl -tag -width "SVR4/GNU" -compact
 170 .It BSD
 171 In the BSD variant, the symbol table has 4 parts encoded in
 172 a machine dependent manner:
 173 .Bl -enum -compact
 174 .It
 175 The first part is a binary value containing size in bytes of the
 176 second part encoded as a C
 177 .Dq long .
 178 .It
 179 The second part is a list of
 180 .Vt struct ranlib
 181 structures (see
 182 .In ranlib.h Ns ).
 183 Each ranlib structure describes one symbol and comprises of
 184 two C
 185 .Dq long
 186 values.
 187 The first
 188 .Dq long
 189 is a zero-based offset into the string table in the fourth part
 190 for the symbol's name.
 191 The second
 192 .Dq long
 193 is an offset from the beginning of the archive to the start
 194 of the archive header for the member that defines the symbol.
 195 .It
 196 The third part is a binary value denoting the length of the
 197 string table contained in the fourth part.
 198 .It
 199 The fourth part is a string table containing NUL-terminated
 200 strings.
 201 .El
 202 .It SVR4/GNU
 203 In the SVR4/GNU variant, the symbol table comprises of three parts
 204 which follow each other without padding:
 205 .Bl -enum -compact
 206 .It
 207 The first part comprises of a count of entries in the symbol table,
 208 stored a 4 byte binary value in MSB first order.
 209 .It
 210 The next part is an array of 4 byte file offsets within the archive
 211 to archive header for members that define the symbol in question.
 212 Each offset in stored in MSB first order.
 213 .It
 214 The third part is a string table, that contains NUL-terminated
 215 strings for the symbols in the symbol table.
 216 .El
 217 .El
 218 .Ss Archive String Table
 219 In the SVR4/GNU variant of the
 220 .Xr ar 1
 221 archive format, long file names are stored in a separate
 222 archive string table and referenced from the archive header
 223 for each member.
 224 Each file name is terminated by the string
 225 .Qq /\en .
 226 The string table itself has a name of
 227 .Qq // .
 228 .Sh SEE ALSO
 229 .Xr ar 1 ,
 230 .Xr ranlib 1 ,
 231 .Xr archive 3 ,
 232 .Xr elf 3 ,
 233 .Xr gelf 3 ,
 234 .Xr elf 5