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