src/usr.bin/ar/ar.5 - annotate

Return to ar.5 CVS log

Up to [local] / src / usr.bin / ar

Annotation of src/usr.bin/ar/ar.5, Revision 1.9

1.9 ! jmc 1: .\" $OpenBSD: ar.5,v 1.8 2007/02/06 17:44:51 jmc Exp $
1.1 deraadt 2: .\" $NetBSD: ar.5,v 1.2 1995/03/25 06:39:38 glass Exp $
3: .\"
4: .\" Copyright (c) 1990, 1991, 1993
5: .\" The Regents of the University of California. All rights reserved.
6: .\"
7: .\" Redistribution and use in source and binary forms, with or without
8: .\" modification, are permitted provided that the following conditions
9: .\" are met:
10: .\" 1. Redistributions of source code must retain the above copyright
11: .\" notice, this list of conditions and the following disclaimer.
12: .\" 2. Redistributions in binary form must reproduce the above copyright
13: .\" notice, this list of conditions and the following disclaimer in the
14: .\" documentation and/or other materials provided with the distribution.
1.6 millert 15: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 16: .\" may be used to endorse or promote products derived from this software
17: .\" without specific prior written permission.
18: .\"
19: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29: .\" SUCH DAMAGE.
30: .\"
31: .\" @(#)ar.5.5 8.1 (Berkeley) 6/9/93
32: .\"
1.9 ! jmc 33: .Dd $Mdocdate$
1.1 deraadt 34: .Dt AR 5
35: .Os
36: .Sh NAME
37: .Nm ar
38: .Nd archive (library) file format
39: .Sh SYNOPSIS
40: .Fd #include <ar.h>
41: .Sh DESCRIPTION
42: The archive command
43: .Nm ar
44: combines several files into one.
45: Archives are mainly used as libraries of object files intended to be
46: loaded using the link-editor
47: .Xr ld 1 .
48: .Pp
49: A file created with
50: .Nm ar
51: begins with the ``magic'' string "!<arch>\en".
52: The rest of the archive is made up of objects, each of which is composed
53: of a header for a file, a possible file name, and the file contents.
54: The header is portable between machine architectures, and, if the file
55: contents are printable, the archive is itself printable.
56: .Pp
57: The header is made up of six variable length
58: .Tn ASCII
59: fields, followed by a
60: two character trailer.
61: The fields are the object name (16 characters), the file last modification
1.4 aaron 62: time (12 characters), the user and group IDs (each 6 characters), the file
1.1 deraadt 63: mode (8 characters) and the file size (10 characters).
64: All numeric fields are in decimal, except for the file mode which is in
65: octal.
66: .Pp
67: The modification time is the file
68: .Fa st_mtime
69: field, i.e.,
70: .Dv CUT
71: seconds since
1.8 jmc 72: the Epoch.
1.4 aaron 73: The user and group IDs are the file
1.1 deraadt 74: .Fa st_uid
75: and
76: .Fa st_gid
77: fields.
78: The file mode is the file
79: .Fa st_mode
80: field.
81: The file size is the file
82: .Fa st_size
83: field.
84: The two-byte trailer is the string "\`\en".
85: .Pp
86: Only the name field has any provision for overflow.
87: If any file name is more than 16 characters in length or contains an
88: embedded space, the string "#1/" followed by the
89: .Tn ASCII
90: length of the
91: name is written in the name field.
92: The file size (stored in the archive header) is incremented by the length
93: of the name.
94: The name is then written immediately following the archive header.
95: .Pp
96: Any unused characters in any of these fields are written as space
97: characters.
98: If any fields are their particular maximum number of characters in
99: length, there will be no separation between the fields.
100: .Pp
101: Objects in the archive are always an even number of bytes long; files
1.4 aaron 102: which are an odd number of bytes long are padded with a newline (`\en')
1.1 deraadt 103: character, although the size in the header does not reflect this.
104: .Sh SEE ALSO
105: .Xr ar 1 ,
106: .Xr stat 2
1.7 jmc 107: .Sh STANDARDS
108: No archive format is currently specified by any standard.
109: .At V
110: has historically distributed archives in a different format from
111: all of the above.
1.1 deraadt 112: .Sh HISTORY
113: There have been at least four
114: .Nm ar
115: formats.
116: The first was denoted by the leading ``magic'' number 0177555 (stored as
117: type int).
118: These archives were almost certainly created on a 16-bit machine, and
119: contain headers made up of five fields.
120: The fields are the object name (8 characters), the file last modification
1.4 aaron 121: time (type long), the user ID (type char), the file mode (type char) and
1.1 deraadt 122: the file size (type unsigned int).
123: Files were padded to an even number of bytes.
124: .Pp
125: The second was denoted by the leading ``magic'' number 0177545 (stored as
126: type int).
127: These archives may have been created on either 16 or 32-bit machines, and
128: contain headers made up of six fields.
129: The fields are the object name (14 characters), the file last modification
1.4 aaron 130: time (type long), the user and group IDs (each type char), the file mode
1.1 deraadt 131: (type int) and the file size (type long).
132: Files were padded to an even number of bytes.
1.5 jmc 133: .\" For more information on converting from this format see
134: .\" .Xr arcv 8 .
1.1 deraadt 135: .Pp
136: The current archive format (without support for long character names and
137: names with embedded spaces) was introduced in
138: .Bx 4.0 .
139: The headers were the same as the current format, with the exception that
140: names longer than 16 characters were truncated, and names with embedded
141: spaces (and often trailing spaces) were not supported.
142: It has been extended for these reasons,
143: as described above.
1.3 mickey 144: This format first appeared in
145: .Bx 4.4 .