BSD 4_3_Net_2 release

[unix-history] / usr / src / usr.bin / ar / ar.5.5

diff --git a/usr/src/usr.bin/ar/ar.5.5 b/usr/src/usr.bin/ar/ar.5.5
index 65de651..ac4ca2b 100644 (file)
--- a/usr/src/usr.bin/ar/ar.5.5
+++ b/usr/src/usr.bin/ar/ar.5.5
@@ -1,69 +1,113 @@
-.\" Copyright (c) 1990 The Regents of the University of California.
+.\" Copyright (c) 1990, 1991 The Regents of the University of California.

 .\" All rights reserved.
 .\"
 .\" All rights reserved.
 .\"

-.\" %sccs.include.redist.man%
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"    This product includes software developed by the University of
+.\"    California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.

 .\"
 .\"

-.\"    @(#)ar.5.5      6.2 (Berkeley) %G%
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.

 .\"
 .\"

-.TH AR 5  ""
-.AT 3
-.SH NAME
-ar \- archive (library) file format
-.SH SYNOPSIS
-.B #include <ar.h>
-.SH DESCRIPTION
-.PP
+.\"     @(#)ar.5.5     6.3 (Berkeley) 5/10/91
+.\"
+.Dd May 10, 1991
+.Dt AR 5
+.Os
+.Sh NAME
+.Nm ar
+.Nd archive (library) file format
+.Sh SYNOPSIS
+.Fd #include <ar.h>
+.Sh DESCRIPTION

 The archive command
 The archive command

-.IR ar
+.Nm ar

 combines several files into one.
 Archives are mainly used as libraries of object files intended to be
 loaded using the link-editor
 combines several files into one.
 Archives are mainly used as libraries of object files intended to be
 loaded using the link-editor

-.IR ld (1).
-.PP
+.Xr ld 1 .
+.Pp

 A file created with
 A file created with

-.I ar
+.Nm ar

 begins with the ``magic'' string "!<arch>\en".
 The rest of the archive is made up of objects, each of which is composed
 of a header for a file, a possible file name, and the file contents.
 The header is portable between machine architectures, and, if the file
 contents are printable, the archive is itself printable.
 begins with the ``magic'' string "!<arch>\en".
 The rest of the archive is made up of objects, each of which is composed
 of a header for a file, a possible file name, and the file contents.
 The header is portable between machine architectures, and, if the file
 contents are printable, the archive is itself printable.

-.PP
-The header is made up of six variable length ASCII fields, followed by a
+.Pp
+The header is made up of six variable length
+.Tn ASCII
+fields, followed by a

 two character trailer.
 The fields are the object name (16 characters), the file last modification
 time (12 characters), the user and group id's (each 6 characters), the file
 mode (8 characters) and the file size (10 characters).
 All numeric fields are in decimal, except for the file mode which is in
 octal.
 two character trailer.
 The fields are the object name (16 characters), the file last modification
 time (12 characters), the user and group id's (each 6 characters), the file
 mode (8 characters) and the file size (10 characters).
 All numeric fields are in decimal, except for the file mode which is in
 octal.

-.PP
-The modification time is the file st_mtime field, i.e., CUT seconds since
+.Pp
+The modification time is the file
+.Fa st_mtime
+field, i.e.,
+.Dv CUT
+seconds since

 the epoch.
 the epoch.

-The user and group id's are the file st_uid and st_gid fields.
-The file mode is the file st_mode field.
-The file size is the file st_size field.
+The user and group id's are the file
+.Fa st_uid
+and
+.Fa st_gid
+fields.
+The file mode is the file
+.Fa st_mode
+field.
+The file size is the file
+.Fa st_size
+field.

 The two-byte trailer is the string "\`\en".
 The two-byte trailer is the string "\`\en".

-.PP
+.Pp

 Only the name field has any provision for overflow.
 If any file name is more than 16 characters in length or contains an
 Only the name field has any provision for overflow.
 If any file name is more than 16 characters in length or contains an

-embedded space, the string "#1/" followed by the ASCII length of the
+embedded space, the string "#1/" followed by the
+.Tn ASCII
+length of the

 name is written in the name field.
 The file size (stored in the archive header) is incremented by the length
 of the name.
 The name is then written immediately following the archive header.
 name is written in the name field.
 The file size (stored in the archive header) is incremented by the length
 of the name.
 The name is then written immediately following the archive header.

-.PP
+.Pp

 Any unused characters in any of these fields are written as space
 characters.
 If any fields are their particular maximum number of characters in
 length, there will be no separation between the fields.
 Any unused characters in any of these fields are written as space
 characters.
 If any fields are their particular maximum number of characters in
 length, there will be no separation between the fields.

-.PP
+.Pp

 Objects in the archive are always an even number of bytes long; files
 which are an odd number of bytes long are padded with a newline (``\en'')
 character, although the size in the header does not reflect this.
 Objects in the archive are always an even number of bytes long; files
 which are an odd number of bytes long are padded with a newline (``\en'')
 character, although the size in the header does not reflect this.

-.SH "SEE ALSO"
-ar(1), stat(2)
-.SH HISTORY
+.Sh SEE ALSO
+.Xr ar 1 ,
+.Xr stat 2
+.Sh HISTORY

 There have been at least four
 There have been at least four

-.I ar
+.Nm ar

 formats.
 The first was denoted by the leading ``magic'' number 0177555 (stored as
 type int).
 formats.
 The first was denoted by the leading ``magic'' number 0177555 (stored as
 type int).


@@ -73,7 +117,7 @@ The fields are the object name (8 characters), the file last modification
 time (type long), the user id (type char), the file mode (type char) and
 the file size (type unsigned int).
 Files were padded to an even number of bytes.
 time (type long), the user id (type char), the file mode (type char) and
 the file size (type unsigned int).
 Files were padded to an even number of bytes.

-.PP
+.Pp

 The second was denoted by the leading ``magic'' number 0177545 (stored as
 type int).
 These archives may have been created on either 16 or 32-bit machines, and
 The second was denoted by the leading ``magic'' number 0177545 (stored as
 type int).
 These archives may have been created on either 16 or 32-bit machines, and


@@ -83,15 +127,20 @@ time (type long), the user and group id's (each type char), the file mode
 (type int) and the file size (type long).
 Files were padded to an even number of bytes.
 For more information on converting from this format see
 (type int) and the file size (type long).
 Files were padded to an even number of bytes.
 For more information on converting from this format see

-.IR arcv (8).
-.PP
+.Xr arcv 8 .
+.Pp

 The current archive format (without support for long character names and
 The current archive format (without support for long character names and

-names with embedded spaces) was introduced in 4.0BSD.
+names with embedded spaces) was introduced in
+.Bx 4.0 .

 The headers were the same as the current format, with the exception that
 names longer than 16 characters were truncated, and names with embedded
 spaces (and often trailing spaces) were not supported.
 The headers were the same as the current format, with the exception that
 names longer than 16 characters were truncated, and names with embedded
 spaces (and often trailing spaces) were not supported.

-It was extended for these reasons in 4.4BSD, as described above.
-.SH COMPATIBILITY
+It has been extended for these reasons,
+as described above.
+This format is
+.Ud .
+.Sh COMPATIBILITY

 No archive format is currently specified by any standard.
 No archive format is currently specified by any standard.

-System V has historically distributed archives in a different format from
+.At V
+has historically distributed archives in a different format from

 all of the above.
 all of the above.