xref: /netbsd-src/share/man/man5/ar.5 (revision 01869ca4d24a86379a68731bf9706a9f0820fe4e)
1*01869ca4Swiz.\"	$NetBSD: ar.5,v 1.9 2017/07/03 21:30:59 wiz Exp $
2e69dff61Stv.\"
3e69dff61Stv.\" Copyright (c) 1990, 1991, 1993
4e69dff61Stv.\"	The Regents of the University of California.  All rights reserved.
5e69dff61Stv.\"
6e69dff61Stv.\" Redistribution and use in source and binary forms, with or without
7e69dff61Stv.\" modification, are permitted provided that the following conditions
8e69dff61Stv.\" are met:
9e69dff61Stv.\" 1. Redistributions of source code must retain the above copyright
10e69dff61Stv.\"    notice, this list of conditions and the following disclaimer.
11e69dff61Stv.\" 2. Redistributions in binary form must reproduce the above copyright
12e69dff61Stv.\"    notice, this list of conditions and the following disclaimer in the
13e69dff61Stv.\"    documentation and/or other materials provided with the distribution.
14075022b3Sagc.\" 3. Neither the name of the University nor the names of its contributors
15e69dff61Stv.\"    may be used to endorse or promote products derived from this software
16e69dff61Stv.\"    without specific prior written permission.
17e69dff61Stv.\"
18e69dff61Stv.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19e69dff61Stv.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20e69dff61Stv.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21e69dff61Stv.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22e69dff61Stv.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23e69dff61Stv.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24e69dff61Stv.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25e69dff61Stv.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26e69dff61Stv.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27e69dff61Stv.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28e69dff61Stv.\" SUCH DAMAGE.
29e69dff61Stv.\"
30e69dff61Stv.\"     @(#)ar.5.5	8.2 (Berkeley) 6/1/94
31e69dff61Stv.\"
32e69dff61Stv.Dd June 1, 1994
33e69dff61Stv.Dt AR 5
34e69dff61Stv.Os
35e69dff61Stv.Sh NAME
36e69dff61Stv.Nm ar
37e69dff61Stv.Nd a.out archive (library) file format
38e69dff61Stv.Sh SYNOPSIS
39472351e1Swiz.In ar.h
40e69dff61Stv.Sh DESCRIPTION
41e69dff61StvThe archive command
42e69dff61Stv.Nm
43e69dff61Stvcombines several files into one.
44e69dff61StvArchives are mainly used as libraries of object files intended to be
45e69dff61Stvloaded using the link-editor
46e69dff61Stv.Xr ld 1 .
47e69dff61Stv.Pp
48e69dff61StvA file created with
49e69dff61Stv.Nm
5071e62d7dSlukembegins with the
5171e62d7dSlukem.Dq magic
5271e62d7dSlukemstring
53*01869ca4Swiz.Dq Li "!<arch>\en" .
54e69dff61StvThe rest of the archive is made up of objects, each of which is composed
55e69dff61Stvof a header for a file, a possible file name, and the file contents.
56e69dff61StvThe header is portable between machine architectures, and, if the file
57e69dff61Stvcontents are printable, the archive is itself printable.
58e69dff61Stv.Pp
59e69dff61StvThe header is made up of six variable length
60e69dff61Stv.Tn ASCII
61e69dff61Stvfields, followed by a
62e69dff61Stvtwo character trailer.
63e69dff61StvThe fields are the object name (16 characters), the file last modification
64e69dff61Stvtime (12 characters), the user and group id's (each 6 characters), the file
65e69dff61Stvmode (8 characters) and the file size (10 characters).
66e69dff61StvAll numeric fields are in decimal, except for the file mode which is in
67e69dff61Stvoctal.
68e69dff61Stv.Pp
69e69dff61StvThe modification time is the file
70e69dff61Stv.Fa st_mtime
71e69dff61Stvfield, i.e.,
72e69dff61Stv.Dv CUT
73e69dff61Stvseconds since
74e69dff61Stvthe epoch.
75e69dff61StvThe user and group id's are the file
76e69dff61Stv.Fa st_uid
77e69dff61Stvand
78e69dff61Stv.Fa st_gid
79e69dff61Stvfields.
80e69dff61StvThe file mode is the file
81e69dff61Stv.Fa st_mode
82e69dff61Stvfield.
83e69dff61StvThe file size is the file
84e69dff61Stv.Fa st_size
85e69dff61Stvfield.
86e69dff61StvThe two-byte trailer is the string "\`\en".
87e69dff61Stv.Pp
88e69dff61StvOnly the name field has any provision for overflow.
89e69dff61StvIf any file name is more than 16 characters in length or contains an
90e69dff61Stvembedded space, the string "#1/" followed by the
91e69dff61Stv.Tn ASCII
92e69dff61Stvlength of the
93e69dff61Stvname is written in the name field.
94e69dff61StvThe file size (stored in the archive header) is incremented by the length
95e69dff61Stvof the name.
96e69dff61StvThe name is then written immediately following the archive header.
97e69dff61Stv.Pp
98e69dff61StvAny unused characters in any of these fields are written as space
99e69dff61Stvcharacters.
100e69dff61StvIf any fields are their particular maximum number of characters in
101e69dff61Stvlength, there will be no separation between the fields.
102e69dff61Stv.Pp
103e69dff61StvObjects in the archive are always an even number of bytes long; files
10471e62d7dSlukemwhich are an odd number of bytes long are padded with a newline
10571e62d7dSlukem.Pq Dq \en
106e69dff61Stvcharacter, although the size in the header does not reflect this.
1072a65137fSwiz.Sh COMPATIBILITY
1082a65137fSwizThe current a.out archive format is not specified by any standard.
1092a65137fSwiz.Pp
1102a65137fSwizELF systems use the
1112a65137fSwiz.Nm
1122a65137fSwizformat specified by the
1132a65137fSwiz.At V.4
1142a65137fSwizABI, with the same headers but different long file name handling.
115e69dff61Stv.Sh SEE ALSO
116e69dff61Stv.Xr ar 1 ,
117e69dff61Stv.Xr stat 2
118e69dff61Stv.Sh HISTORY
119e69dff61StvThere have been at least four
120e69dff61Stv.Nm
121e69dff61Stvformats.
12271e62d7dSlukemThe first was denoted by the leading
12371e62d7dSlukem.Dq magic
12471e62d7dSlukemnumber 0177555 (stored as type int).
125e69dff61StvThese archives were almost certainly created on a 16-bit machine, and
126e69dff61Stvcontain headers made up of five fields.
127e69dff61StvThe fields are the object name (8 characters), the file last modification
128e69dff61Stvtime (type long), the user id (type char), the file mode (type char) and
129e69dff61Stvthe file size (type unsigned int).
130e69dff61StvFiles were padded to an even number of bytes.
131e69dff61Stv.Pp
13271e62d7dSlukemThe second was denoted by the leading
13371e62d7dSlukem.Dq magic
13471e62d7dSlukemnumber 0177545 (stored as type int).
135e69dff61StvThese archives may have been created on either 16 or 32-bit machines, and
136e69dff61Stvcontain headers made up of six fields.
137e69dff61StvThe fields are the object name (14 characters), the file last modification
138e69dff61Stvtime (type long), the user and group id's (each type char), the file mode
139e69dff61Stv(type int), and the file size (type long).
140e69dff61StvFiles were padded to an even number of bytes.
141e69dff61Stv.Pp
142e69dff61StvBoth of these historical formats may be read with
143e69dff61Stv.Xr ar 1 .
144e69dff61Stv.Pp
145e69dff61StvThe current archive format (without support for long character names and
146e69dff61Stvnames with embedded spaces) was introduced in
147e69dff61Stv.Bx 4.0 .
148e69dff61StvThe headers were the same as the current format, with the exception that
149e69dff61Stvnames longer than 16 characters were truncated, and names with embedded
150e69dff61Stvspaces (and often trailing spaces) were not supported.
151e69dff61StvIt has been extended for these reasons,
152e69dff61Stvas described above.
153e69dff61StvThis format first appeared in
154e69dff61Stv.Bx 4.4 .
155e69dff61Stv.Sh BUGS
156e69dff61StvThe
157*01869ca4Swiz.Tn <ar.h>
158e69dff61Stvheader file, and the
1596ad1c679Swiz.Nm
160e69dff61Stvmanual page, do not currently describe the ELF archive format.
161