sys/man/6/ar

   1 .TH AR 6
   2 .SH NAME
   3 ar \- archive (library) file format
   4 .SH SYNOPSIS
   5 .B #include <ar.h>
   6 .SH DESCRIPTION
   7 The archive command
   8 .IR ar (1)
   9 is used to combine several files into
  10 one.
  11 Archives are used mainly as libraries to be searched
  12 by the loaders
  13 .IR 2l (1)
  14 .I et al.
  15 .PP
  16 A file produced by
  17 .I ar
  18 has a magic string at the start,
  19 followed by the constituent files, each preceded by a file header.
  20 The magic number and header layout as described in the
  21 include file are:
  22 .IP
  23 .EX
  24 .ta \w'#define 'u +\w'SAR_HDR 'u
  25 .ec %
  26 #define ARMAG   "!<arch>\n"
  27 #define SARMAG  8
  28
  29 #define ARFMAG  "`\n"
  30
  31 struct ar_hdr {
  32         char    name[16];
  33         char    date[12];
  34         char    uid[6];
  35         char    gid[6];
  36         char    mode[8];
  37         char    size[10];
  38         char    fmag[2];
  39 };
  40 #define SAR_HDR 60
  41 .ec \
  42 .EE
  43 .LP
  44 The
  45 .B name
  46 is a blank-padded string.
  47 The
  48 .L fmag
  49 field contains
  50 .L ARFMAG
  51 to help verify the presence of a header.
  52 The other fields are left-adjusted, blank-padded numbers.
  53 They are decimal except for
  54 .LR mode ,
  55 which is octal.
  56 The date is the modification date of the file (see
  57 .IR stat (2))
  58 at the time of its insertion into the archive.
  59 The mode is the low 9 bits of the file permission mode.
  60 The length of the header is
  61 .LR SAR_HDR .
  62 Because the
  63 .L ar_hdr
  64 structure is padded in an architecture-dependent manner,
  65 the structure should never be read or written as a unit;
  66 instead, each field should be read or written independently.
  67 .PP
  68 Each file begins on an even (0 mod 2) boundary;
  69 a newline is inserted between files if necessary.
  70 Nevertheless
  71 .B size
  72 reflects the
  73 actual size of the file exclusive of padding.
  74 .PP
  75 When all members of an archive are object files of
  76 the same architecture,
  77 .B ar
  78 automatically adds an extra file, named
  79 .BR __.SYMDEF ,
  80 as the first member of the archive.  This file
  81 contains an index used by the loaders to locate all
  82 externally defined text and data symbols in the archive.
  83 .PP
  84 There is no provision for empty areas in an archive
  85 file.
  86 .SH "SEE ALSO"
  87 .IR ar (1),
  88 .IR 2l (1),
  89 .IR nm (1),
  90 .IR stat (2)
  91 .SH BUGS
  92 The
  93 .B uid
  94 and
  95 .B gid
  96 fields are unused in Plan 9.
  97 They provide compatibility with Unix
  98 .I ar
  99 format.