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