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