ar -d[-v] archive file ...
ar -m [-v] archive file ...
ar -m -a[-v] posname archive file ...
ar -m -b[-v] posname archive file ...
ar -m -i[-v] posname archive file ...
ar -p[-v][-s]archive [file
...]
ar -q[-cv] archive file ...
ar -r[-cuv] archive file ...
ar -r -a[-cuv] posname archive file
...
ar -r -b[-cuv] posname archive file ...
ar -r -i[-cuv] posname archive file ...
ar -t[-v][-s]archive [file
...]
ar -x[-v][-sCT]archive [file
...]
The ar utility is part of the Software Development Utilities option.
The ar utility can be used to create and maintain groups of files combined into an archive. Once an archive has been created, new files can be added, and existing files in an archive can be extracted, deleted, or replaced. When an archive consists entirely of valid object files, the implementation shall format the archive so that it is usable as a library for link editing (see c99 and fort77). When some of the archived files are not valid object files, the suitability of the archive for library use is undefined. If an archive consists entirely of printable files, the entire archive shall be printable.
When ar creates an archive, it creates administrative information indicating whether a symbol table is present in the archive. When there is at least one object file that ar recognizes as such in the archive, an archive symbol table shall be created in the archive and maintained by ar; it is used by the link editor to search the archive. Whenever the ar utility is used to create or update the contents of such an archive, the symbol table shall be rebuilt. The -s option shall force the symbol table to be rebuilt.
All file operands can be pathnames. However, files within archives shall be named by a filename, which is the last component of the pathname used when the file was entered into the archive. The comparison of file operands to the names of files in archives shall be performed by comparing the last component of the operand to the name of the file in the archive.
It is unspecified whether multiple files in the archive may be identically named. In the case of such files, however, each file and posname operand shall match only the first file in the archive having a name that is the same as the last component of the operand.
The ar utility shall conform to the Base Definitions volume of IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
The following options shall be supported:
When used with -p, write the name of the file in the archive to the standard output before writing the file in the archive itself to the standard output, as described in the STDOUT section.
When used with -t, include a long listing of information about the files in the archive, as described in the STDOUT section.
The following operands shall be supported:
The archive named by archive shall be a file in the format created by ar -r.
The following environment variables shall affect the execution of ar:
If the -d option is used with the -v option, the standard output format shall be:
"d - %s\n", <file>
where file is the operand specified on the command line.
If the -p option is used with the -v option, ar shall precede the contents of each file with:
"\n<%s>\n\n", <file>
where file is the operand specified on the command line, if file operands were specified, and the name of the file in the archive if they were not.
If the -r option is used with the -v option:
"r - %s\n", <file>
where <file> is the operand specified on the command line.
"a - %s\n", <file>
where <file> is the operand specified on the command line.
If the -t option is used, ar shall write the names of the files in the archive to the standard output in the format:
"%s\n", <file>
where file is the operand specified on the command line, if file operands were specified, or the name of the file in the archive if they were not.
If the -t option is used with the -v option, the standard output format shall be:
"%s %u/%u %u %s %d %d:%d %d %s\n", <member mode>, <user ID>,
<group ID>, <number of bytes in member>,
<abbreviated month>, <day-of-month>, <hour>,
<minute>, <year>, <file>
where:
Shall be formatted the same as the <file mode> string defined in the STDOUT section of ls, except that the first character, the <entry type>, is not used; the string represents the file mode of the file in the archive at the time it was added to or replaced in the archive.
The following represent the last-modification time of a file when it was most recently added to or replaced in the archive:
Equivalent to the format of the %b conversion specification format in date.
Equivalent to the format of the %e conversion specification format in date.
When LC_TIME does not specify the POSIX locale, a different format and order of presentation of these fields relative to each other may be used in a format appropriate in the specified locale.
If the -x option is used with the -v option, the standard output format shall be:
"x - %s\n", <file>
where file is the operand specified on the command line, if file operands were specified, or the name of the file in the archive if they were not.
The standard error shall be used only for diagnostic messages. The diagnostic message about creating a new archive when -c is not specified shall not modify the exit status.
Archives are files with unspecified formats.
The following exit values shall be returned:
Default.
The following sections are informative.
The archive format is not described. It is recognized that there are several known ar formats, which are not compatible. The ar utility is included, however, to allow creation of archives that are intended for use only on one machine. The archive is specified as a file, and it can be moved as a file. This does allow an archive to be moved from one machine to another machine that uses the same implementation of ar.
Utilities such as pax (and its forebears tar and cpio) also provide portable "archives". This is a not a duplication; the ar utility is included to provide an interface primarily for make and the compilers, based on a historical model.
In historical implementations, the -q option (available on XSI-conforming systems) is known to execute quickly because ar does not check on whether the added members are already in the archive. This is useful to bypass the searching otherwise done when creating a large archive piece-by-piece. These remarks may but need not remain true for a brand new implementation of this utility; hence, these remarks have been moved into the RATIONALE.
BSD implementations historically required applications to provide the -s option whenever the archive was supposed to contain a symbol table. As in this volume of IEEE Std 1003.1-2001, System V historically creates or updates an archive symbol table whenever an object file is removed from, added to, or updated in the archive.
The OPERANDS section requires what might seem to be true without specifying it: the archive cannot truncate the filenames below {NAME_MAX}. Some historical implementations do so, however, causing unexpected results for the application. Therefore, this volume of IEEE Std 1003.1-2001 makes the requirement explicit to avoid misunderstandings.
According to the System V documentation, the options -dmpqrtx are not required to begin with a hyphen ( '-' ). This volume of IEEE Std 1003.1-2001 requires that a conforming application use the leading hyphen.
The archive format used by the 4.4 BSD implementation is documented in this RATIONALE as an example: A file created by ar begins with the "magic" string "!<arch>\n" . The rest of the archive is made up of objects, each of which is composed of a header for a file, a possible filename, and the file contents. The header is portable between machine architectures, and, if the file contents are printable, the archive is itself printable.
The header is made up of six 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 IDs (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.
The modification time is the file st_mtime field. The user and group IDs 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 "`<newline>" .
Only the name field has any provision for overflow. If any filename 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.
Any unused characters in any of these fields are written as <space>s. If any fields are their particular maximum number of characters in length, there is no separation between the fields.
Objects in the archive are always an even number of bytes long; files that are an odd number of bytes long are padded with a <newline>, although the size in the header does not reflect this.
The ar utility description requires that (when all its members are valid object files) ar produce an object code library, which the linkage editor can use to extract object modules. If the linkage editor needs a symbol table to permit random access to the archive, ar must provide it; however, ar does not require a symbol table.
The BSD -o option was omitted. It is a rare conforming application that uses ar to extract object code from a library with concern for its modification time, since this can only be of importance to make. Hence, since this functionality is not deemed important for applications portability, the modification time of the extracted files is set to the current time.
There is at least one known implementation (for a small computer) that can accommodate only object files for that system, disallowing mixed object and other files. The ability to handle any type of file is not only historical practice for most implementations, but is also a reasonable expectation.
Consideration was given to changing the output format of ar -tv to the same format as the output of ls -l. This would have made parsing the output of ar the same as that of ls. This was rejected in part because the current ar format is commonly used and changes would break historical usage. Second, ar gives the user ID and group ID in numeric format separated by a slash. Changing this to be the user name and group name would not be correct if the archive were moved to a machine that contained a different user database. Since ar cannot know whether the archive was generated on the same machine, it cannot tell what to report.
The text on the -ur option combination is historical practice-since one filename can easily represent two different files (for example, /a/foo and /b/foo), it is reasonable to replace the file in the archive even when the modification time in the archive is identical to that in the file system.
c99 , date , fort77 , pax , strip the Base Definitions volume of IEEE Std 1003.1-2001, Chapter 13, Headers, <unistd.h> description of {POSIX_NO_TRUNC}