1.\" $OpenBSD: ar.5,v 1.1 2013/07/05 21:37:15 miod 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: July 5 2013 $ 34.Dt AR 5 35.Os 36.Sh NAME 37.Nm ar 38.Nd archive (library) file format 39.Sh SYNOPSIS 40.Fd #include <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 "!<arch>\en". 52The rest of the archive is made up of objects, each of which is composed 53of a header for a file, a possible file name, and the file contents. 54The header is portable between machine architectures, and, if the file 55contents are printable, the archive is itself printable. 56.Pp 57The header is made up of six variable length 58.Tn ASCII 59fields, followed by a 60two character trailer. 61The fields are the object name (16 characters), the file last modification 62time (12 characters), the user and group IDs (each 6 characters), the file 63mode (8 characters) and the file size (10 characters). 64All numeric fields are in decimal, except for the file mode which is in 65octal. 66.Pp 67The modification time is the file 68.Fa st_mtime 69field, i.e., 70.Dv CUT 71seconds since 72the Epoch. 73The user and group IDs are the file 74.Fa st_uid 75and 76.Fa st_gid 77fields. 78The file mode is the file 79.Fa st_mode 80field. 81The file size is the file 82.Fa st_size 83field. 84The two-byte trailer is the string "\`\en". 85.Pp 86Only the name field has any provision for overflow. 87If any file name is more than 16 characters in length or contains an 88embedded space, the string "#1/" followed by the 89.Tn ASCII 90length of the 91name is written in the name field. 92The file size (stored in the archive header) is incremented by the length 93of the name. 94The name is then written immediately following the archive header. 95.Pp 96Any unused characters in any of these fields are written as space 97characters. 98If any fields are their particular maximum number of characters in 99length, there will be no separation between the fields. 100.Pp 101Objects in the archive are always an even number of bytes long; files 102which are an odd number of bytes long are padded with a newline (`\en') 103character, although the size in the header does not reflect this. 104.Sh SEE ALSO 105.Xr ar 1 , 106.Xr stat 2 107.Sh STANDARDS 108No archive format is currently specified by any standard. 109.At V 110has historically distributed archives in a different format from 111all of the above. 112.Sh HISTORY 113There have been at least four 114.Nm ar 115formats. 116The first was denoted by the leading ``magic'' number 0177555 (stored as 117type int). 118These archives were almost certainly created on a 16-bit machine, and 119contain headers made up of five fields. 120The fields are the object name (8 characters), the file last modification 121time (type long), the user ID (type char), the file mode (type char) and 122the file size (type unsigned int). 123Files were padded to an even number of bytes. 124.Pp 125The second was denoted by the leading ``magic'' number 0177545 (stored as 126type int). 127These archives may have been created on either 16 or 32-bit machines, and 128contain headers made up of six fields. 129The fields are the object name (14 characters), the file last modification 130time (type long), the user and group IDs (each type char), the file mode 131(type int) and the file size (type long). 132Files were padded to an even number of bytes. 133.\" For more information on converting from this format see 134.\" .Xr arcv 8 . 135.Pp 136The current archive format (without support for long character names and 137names with embedded spaces) was introduced in 138.Bx 4.0 . 139The headers were the same as the current format, with the exception that 140names longer than 16 characters were truncated, and names with embedded 141spaces (and often trailing spaces) were not supported. 142It has been extended for these reasons, 143as described above. 144This format first appeared in 145.Bx 4.4 . 146