fold header.c into archive.c

[unix-history] / usr / src / usr.bin / ar / ar.5.5

.\" Copyright (c) 1990 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" %sccs.include.redist.man%
.\"
.\"	@(#)ar.5.5	6.2 (Berkeley) %G%
.\"
.TH AR 5  ""
.AT 3
.SH NAME
ar \- archive (library) file format
.SH SYNOPSIS
.B #include <ar.h>
.SH DESCRIPTION
.PP
The archive command
.IR ar
combines several files into one.
Archives are mainly used as libraries of object files intended to be
loaded using the link-editor
.IR ld (1).
.PP
A file created with
.I ar
begins with the ``magic'' string "!<arch>\en".
The rest of the archive is made up of objects, each of which is composed
of a header for a file, a possible file name, and the file contents.
The header is portable between machine architectures, and, if the file
contents are printable, the archive is itself printable.
.PP
The header is made up of six variable length ASCII fields, followed by a
two character trailer.
The fields are the object name (16 characters), the file last modification
time (12 characters), the user and group id's (each 6 characters), the file
mode (8 characters) and the file size (10 characters).
All numeric fields are in decimal, except for the file mode which is in
octal.
.PP
The modification time is the file st_mtime field, i.e., CUT seconds since
the epoch.
The user and group id's are the file st_uid and st_gid fields.
The file mode is the file st_mode field.
The file size is the file st_size field.
The two-byte trailer is the string "\`\en".
.PP
Only the name field has any provision for overflow.
If any file name is more than 16 characters in length or contains an
embedded space, the string "#1/" followed by the ASCII length of the
name is written in the name field.
The file size (stored in the archive header) is incremented by the length
of the name.
The name is then written immediately following the archive header.
.PP
Any unused characters in any of these fields are written as space
characters.
If any fields are their particular maximum number of characters in
length, there will be no separation between the fields.
.PP
Objects in the archive are always an even number of bytes long; files
which are an odd number of bytes long are padded with a newline (``\en'')
character, although the size in the header does not reflect this.
.SH "SEE ALSO"
ar(1), stat(2)
.SH HISTORY
There have been at least four
.I ar
formats.
The first was denoted by the leading ``magic'' number 0177555 (stored as
type int).
These archives were almost certainly created on a 16-bit machine, and
contain headers made up of five fields.
The fields are the object name (8 characters), the file last modification
time (type long), the user id (type char), the file mode (type char) and
the file size (type unsigned int).
Files were padded to an even number of bytes.
.PP
The second was denoted by the leading ``magic'' number 0177545 (stored as
type int).
These archives may have been created on either 16 or 32-bit machines, and
contain headers made up of six fields.
The fields are the object name (14 characters), the file last modification
time (type long), the user and group id's (each type char), the file mode
(type int) and the file size (type long).
Files were padded to an even number of bytes.
For more information on converting from this format see
.IR arcv (8).
.PP
The current archive format (without support for long character names and
names with embedded spaces) was introduced in 4.0BSD.
The headers were the same as the current format, with the exception that
names longer than 16 characters were truncated, and names with embedded
spaces (and often trailing spaces) were not supported.
It was extended for these reasons in 4.4BSD, as described above.
.SH COMPATIBILITY
No archive format is currently specified by any standard.
System V has historically distributed archives in a different format from
all of the above.