1.\" $NetBSD: ar.5,v 1.4 2002/02/13 08:18:09 ross 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.2 (Berkeley) 6/1/94 35.\" 36.Dd June 1, 1994 37.Dt AR 5 38.Os 39.Sh NAME 40.Nm ar 41.Nd a.out archive (library) file format 42.Sh SYNOPSIS 43.Fd #include \*[Lt]ar.h\*[Gt] 44.Sh DESCRIPTION 45The archive command 46.Nm 47combines several files into one. 48Archives are mainly used as libraries of object files intended to be 49loaded using the link-editor 50.Xr ld 1 . 51.Pp 52A file created with 53.Nm 54begins with the 55.Dq magic 56string 57.Dq Li "!\*[Lt]arch\*[Gt]\en" . 58The rest of the archive is made up of objects, each of which is composed 59of a header for a file, a possible file name, and the file contents. 60The header is portable between machine architectures, and, if the file 61contents are printable, the archive is itself printable. 62.Pp 63The header is made up of six variable length 64.Tn ASCII 65fields, followed by a 66two character trailer. 67The fields are the object name (16 characters), the file last modification 68time (12 characters), the user and group id's (each 6 characters), the file 69mode (8 characters) and the file size (10 characters). 70All numeric fields are in decimal, except for the file mode which is in 71octal. 72.Pp 73The modification time is the file 74.Fa st_mtime 75field, i.e., 76.Dv CUT 77seconds since 78the epoch. 79The user and group id's are the file 80.Fa st_uid 81and 82.Fa st_gid 83fields. 84The file mode is the file 85.Fa st_mode 86field. 87The file size is the file 88.Fa st_size 89field. 90The two-byte trailer is the string "\`\en". 91.Pp 92Only the name field has any provision for overflow. 93If any file name is more than 16 characters in length or contains an 94embedded space, the string "#1/" followed by the 95.Tn ASCII 96length of the 97name is written in the name field. 98The file size (stored in the archive header) is incremented by the length 99of the name. 100The name is then written immediately following the archive header. 101.Pp 102Any unused characters in any of these fields are written as space 103characters. 104If any fields are their particular maximum number of characters in 105length, there will be no separation between the fields. 106.Pp 107Objects in the archive are always an even number of bytes long; files 108which are an odd number of bytes long are padded with a newline 109.Pq Dq \en 110character, although the size in the header does not reflect this. 111.Sh SEE ALSO 112.Xr ar 1 , 113.Xr stat 2 114.Sh HISTORY 115There have been at least four 116.Nm 117formats. 118The first was denoted by the leading 119.Dq magic 120number 0177555 (stored as type int). 121These archives were almost certainly created on a 16-bit machine, and 122contain headers made up of five fields. 123The fields are the object name (8 characters), the file last modification 124time (type long), the user id (type char), the file mode (type char) and 125the file size (type unsigned int). 126Files were padded to an even number of bytes. 127.Pp 128The second was denoted by the leading 129.Dq magic 130number 0177545 (stored as type int). 131These archives may have been created on either 16 or 32-bit machines, and 132contain headers made up of six fields. 133The fields are the object name (14 characters), the file last modification 134time (type long), the user and group id's (each type char), the file mode 135(type int), and the file size (type long). 136Files were padded to an even number of bytes. 137.Pp 138Both of these historical formats may be read with 139.Xr ar 1 . 140.Pp 141The current archive format (without support for long character names and 142names with embedded spaces) was introduced in 143.Bx 4.0 . 144The headers were the same as the current format, with the exception that 145names longer than 16 characters were truncated, and names with embedded 146spaces (and often trailing spaces) were not supported. 147It has been extended for these reasons, 148as described above. 149This format first appeared in 150.Bx 4.4 . 151.Sh COMPATIBILITY 152The current a.out archive format is not specified by any standard. 153.Pp 154ELF systems use the 155.Nm 156format specified by the 157.At V.4 158ABI, with the same headers but different long file name handling. 159.Sh BUGS 160The 161.Tn \*[Lt]ar.h\*[Gt] 162header file, and the 163.Xr ar 5 164manual page, do not currently describe the ELF archive format. 165