1.\" $NetBSD: ar.5,v 1.1 1998/08/22 05:29:57 tv 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 <ar.h> 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 ``magic'' string "!<arch>\en". 55The rest of the archive is made up of objects, each of which is composed 56of a header for a file, a possible file name, and the file contents. 57The header is portable between machine architectures, and, if the file 58contents are printable, the archive is itself printable. 59.Pp 60The header is made up of six variable length 61.Tn ASCII 62fields, followed by a 63two character trailer. 64The fields are the object name (16 characters), the file last modification 65time (12 characters), the user and group id's (each 6 characters), the file 66mode (8 characters) and the file size (10 characters). 67All numeric fields are in decimal, except for the file mode which is in 68octal. 69.Pp 70The modification time is the file 71.Fa st_mtime 72field, i.e., 73.Dv CUT 74seconds since 75the epoch. 76The user and group id's are the file 77.Fa st_uid 78and 79.Fa st_gid 80fields. 81The file mode is the file 82.Fa st_mode 83field. 84The file size is the file 85.Fa st_size 86field. 87The two-byte trailer is the string "\`\en". 88.Pp 89Only the name field has any provision for overflow. 90If any file name is more than 16 characters in length or contains an 91embedded space, the string "#1/" followed by the 92.Tn ASCII 93length of the 94name is written in the name field. 95The file size (stored in the archive header) is incremented by the length 96of the name. 97The name is then written immediately following the archive header. 98.Pp 99Any unused characters in any of these fields are written as space 100characters. 101If any fields are their particular maximum number of characters in 102length, there will be no separation between the fields. 103.Pp 104Objects in the archive are always an even number of bytes long; files 105which are an odd number of bytes long are padded with a newline (``\en'') 106character, 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 111There have been at least four 112.Nm 113formats. 114The first was denoted by the leading ``magic'' number 0177555 (stored as 115type int). 116These archives were almost certainly created on a 16-bit machine, and 117contain headers made up of five fields. 118The fields are the object name (8 characters), the file last modification 119time (type long), the user id (type char), the file mode (type char) and 120the file size (type unsigned int). 121Files were padded to an even number of bytes. 122.Pp 123The second was denoted by the leading ``magic'' number 0177545 (stored as 124type int). 125These archives may have been created on either 16 or 32-bit machines, and 126contain headers made up of six fields. 127The fields are the object name (14 characters), the file last modification 128time (type long), the user and group id's (each type char), the file mode 129(type int), and the file size (type long). 130Files were padded to an even number of bytes. 131.Pp 132Both of these historical formats may be read with 133.Xr ar 1 . 134.Pp 135The current archive format (without support for long character names and 136names with embedded spaces) was introduced in 137.Bx 4.0 . 138The headers were the same as the current format, with the exception that 139names longer than 16 characters were truncated, and names with embedded 140spaces (and often trailing spaces) were not supported. 141It has been extended for these reasons, 142as described above. 143This format first appeared in 144.Bx 4.4 . 145.Sh COMPATIBILITY 146The current a.out archive format is not specified by any standard. 147.Pp 148ELF systems use the 149.Nm 150format specified by the 151.At V.4 152ABI, with the same headers but different long file name handling. 153.Pp 154.Sh BUGS 155The 156.Tn <ar.h> 157header file, and the 158.Xr ar 5 159manual page, do not currently describe the ELF archive format. 160