1*01869ca4Swiz.\" $NetBSD: ar.5,v 1.9 2017/07/03 21:30:59 wiz Exp $ 2e69dff61Stv.\" 3e69dff61Stv.\" Copyright (c) 1990, 1991, 1993 4e69dff61Stv.\" The Regents of the University of California. All rights reserved. 5e69dff61Stv.\" 6e69dff61Stv.\" Redistribution and use in source and binary forms, with or without 7e69dff61Stv.\" modification, are permitted provided that the following conditions 8e69dff61Stv.\" are met: 9e69dff61Stv.\" 1. Redistributions of source code must retain the above copyright 10e69dff61Stv.\" notice, this list of conditions and the following disclaimer. 11e69dff61Stv.\" 2. Redistributions in binary form must reproduce the above copyright 12e69dff61Stv.\" notice, this list of conditions and the following disclaimer in the 13e69dff61Stv.\" documentation and/or other materials provided with the distribution. 14075022b3Sagc.\" 3. Neither the name of the University nor the names of its contributors 15e69dff61Stv.\" may be used to endorse or promote products derived from this software 16e69dff61Stv.\" without specific prior written permission. 17e69dff61Stv.\" 18e69dff61Stv.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19e69dff61Stv.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20e69dff61Stv.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21e69dff61Stv.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22e69dff61Stv.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23e69dff61Stv.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24e69dff61Stv.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25e69dff61Stv.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26e69dff61Stv.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27e69dff61Stv.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28e69dff61Stv.\" SUCH DAMAGE. 29e69dff61Stv.\" 30e69dff61Stv.\" @(#)ar.5.5 8.2 (Berkeley) 6/1/94 31e69dff61Stv.\" 32e69dff61Stv.Dd June 1, 1994 33e69dff61Stv.Dt AR 5 34e69dff61Stv.Os 35e69dff61Stv.Sh NAME 36e69dff61Stv.Nm ar 37e69dff61Stv.Nd a.out archive (library) file format 38e69dff61Stv.Sh SYNOPSIS 39472351e1Swiz.In ar.h 40e69dff61Stv.Sh DESCRIPTION 41e69dff61StvThe archive command 42e69dff61Stv.Nm 43e69dff61Stvcombines several files into one. 44e69dff61StvArchives are mainly used as libraries of object files intended to be 45e69dff61Stvloaded using the link-editor 46e69dff61Stv.Xr ld 1 . 47e69dff61Stv.Pp 48e69dff61StvA file created with 49e69dff61Stv.Nm 5071e62d7dSlukembegins with the 5171e62d7dSlukem.Dq magic 5271e62d7dSlukemstring 53*01869ca4Swiz.Dq Li "!<arch>\en" . 54e69dff61StvThe rest of the archive is made up of objects, each of which is composed 55e69dff61Stvof a header for a file, a possible file name, and the file contents. 56e69dff61StvThe header is portable between machine architectures, and, if the file 57e69dff61Stvcontents are printable, the archive is itself printable. 58e69dff61Stv.Pp 59e69dff61StvThe header is made up of six variable length 60e69dff61Stv.Tn ASCII 61e69dff61Stvfields, followed by a 62e69dff61Stvtwo character trailer. 63e69dff61StvThe fields are the object name (16 characters), the file last modification 64e69dff61Stvtime (12 characters), the user and group id's (each 6 characters), the file 65e69dff61Stvmode (8 characters) and the file size (10 characters). 66e69dff61StvAll numeric fields are in decimal, except for the file mode which is in 67e69dff61Stvoctal. 68e69dff61Stv.Pp 69e69dff61StvThe modification time is the file 70e69dff61Stv.Fa st_mtime 71e69dff61Stvfield, i.e., 72e69dff61Stv.Dv CUT 73e69dff61Stvseconds since 74e69dff61Stvthe epoch. 75e69dff61StvThe user and group id's are the file 76e69dff61Stv.Fa st_uid 77e69dff61Stvand 78e69dff61Stv.Fa st_gid 79e69dff61Stvfields. 80e69dff61StvThe file mode is the file 81e69dff61Stv.Fa st_mode 82e69dff61Stvfield. 83e69dff61StvThe file size is the file 84e69dff61Stv.Fa st_size 85e69dff61Stvfield. 86e69dff61StvThe two-byte trailer is the string "\`\en". 87e69dff61Stv.Pp 88e69dff61StvOnly the name field has any provision for overflow. 89e69dff61StvIf any file name is more than 16 characters in length or contains an 90e69dff61Stvembedded space, the string "#1/" followed by the 91e69dff61Stv.Tn ASCII 92e69dff61Stvlength of the 93e69dff61Stvname is written in the name field. 94e69dff61StvThe file size (stored in the archive header) is incremented by the length 95e69dff61Stvof the name. 96e69dff61StvThe name is then written immediately following the archive header. 97e69dff61Stv.Pp 98e69dff61StvAny unused characters in any of these fields are written as space 99e69dff61Stvcharacters. 100e69dff61StvIf any fields are their particular maximum number of characters in 101e69dff61Stvlength, there will be no separation between the fields. 102e69dff61Stv.Pp 103e69dff61StvObjects in the archive are always an even number of bytes long; files 10471e62d7dSlukemwhich are an odd number of bytes long are padded with a newline 10571e62d7dSlukem.Pq Dq \en 106e69dff61Stvcharacter, although the size in the header does not reflect this. 1072a65137fSwiz.Sh COMPATIBILITY 1082a65137fSwizThe current a.out archive format is not specified by any standard. 1092a65137fSwiz.Pp 1102a65137fSwizELF systems use the 1112a65137fSwiz.Nm 1122a65137fSwizformat specified by the 1132a65137fSwiz.At V.4 1142a65137fSwizABI, with the same headers but different long file name handling. 115e69dff61Stv.Sh SEE ALSO 116e69dff61Stv.Xr ar 1 , 117e69dff61Stv.Xr stat 2 118e69dff61Stv.Sh HISTORY 119e69dff61StvThere have been at least four 120e69dff61Stv.Nm 121e69dff61Stvformats. 12271e62d7dSlukemThe first was denoted by the leading 12371e62d7dSlukem.Dq magic 12471e62d7dSlukemnumber 0177555 (stored as type int). 125e69dff61StvThese archives were almost certainly created on a 16-bit machine, and 126e69dff61Stvcontain headers made up of five fields. 127e69dff61StvThe fields are the object name (8 characters), the file last modification 128e69dff61Stvtime (type long), the user id (type char), the file mode (type char) and 129e69dff61Stvthe file size (type unsigned int). 130e69dff61StvFiles were padded to an even number of bytes. 131e69dff61Stv.Pp 13271e62d7dSlukemThe second was denoted by the leading 13371e62d7dSlukem.Dq magic 13471e62d7dSlukemnumber 0177545 (stored as type int). 135e69dff61StvThese archives may have been created on either 16 or 32-bit machines, and 136e69dff61Stvcontain headers made up of six fields. 137e69dff61StvThe fields are the object name (14 characters), the file last modification 138e69dff61Stvtime (type long), the user and group id's (each type char), the file mode 139e69dff61Stv(type int), and the file size (type long). 140e69dff61StvFiles were padded to an even number of bytes. 141e69dff61Stv.Pp 142e69dff61StvBoth of these historical formats may be read with 143e69dff61Stv.Xr ar 1 . 144e69dff61Stv.Pp 145e69dff61StvThe current archive format (without support for long character names and 146e69dff61Stvnames with embedded spaces) was introduced in 147e69dff61Stv.Bx 4.0 . 148e69dff61StvThe headers were the same as the current format, with the exception that 149e69dff61Stvnames longer than 16 characters were truncated, and names with embedded 150e69dff61Stvspaces (and often trailing spaces) were not supported. 151e69dff61StvIt has been extended for these reasons, 152e69dff61Stvas described above. 153e69dff61StvThis format first appeared in 154e69dff61Stv.Bx 4.4 . 155e69dff61Stv.Sh BUGS 156e69dff61StvThe 157*01869ca4Swiz.Tn <ar.h> 158e69dff61Stvheader file, and the 1596ad1c679Swiz.Nm 160e69dff61Stvmanual page, do not currently describe the ELF archive format. 161