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.2

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