STANDARD INPUT

None.

INPUT FILES

The input file named by archive shall be a file in the format created by ar -r.

ENVIRONMENT VARIABLES

The following environment variables shall affect the execution of ar:

LANG

This variable shall determine the locale to use for the locale categories when both LC_ALL and the corresponding environment variable (beginning with LC_ ) do not specify a locale. See 2.6.

LC_ALL

This variable shall determine the locale to be used to override any values for locale categories specified by the settings of LANG or any environment variables beginning with LC_.

LC_CTYPE

This variable shall determine the locale for the interpretation of sequences of bytes of text data as characters (e.g., single- versus multibyte characters in arguments).

LC_MESSAGES

This variable shall determine the language in which messages should be written.

LC_TIME

This variable shall determine the format and content for date and time strings written by ar.

ASYNCHRONOUS EVENTS

Default.

STANDARD OUTPUT

If the −d option is used with the −v option, the standard output format is: "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, and file is already in the archive, the standard output format is: "r − %s\n", <file> where file is the operand specified on the command line. If file is being added to the archive with the −r option, the standard output format is: "a − %s\n", <file> where file is the operand specified on the command line. If the −t option is used, ar writes the names of the files 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 is: "%s %u/%u %u %s %d %d:%d %d %s\n", <member mode>, <user ID>, <group ID>, <number of bytes in member>, <abbreviated month>, <dayof-month>, <hour>, <minute>, <year>, <file> Where:

file shall be 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. <member mode> shall be formatted the same as the <file mode> string defined in ls(1)
(Standard Output of ls), except that the first character, the <entry type>, is not used; the string represents the file mode of the archive member 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: <abbreviated month> shall be equivalent to the %b format in date (see date(1) ). <day-of-month> shall be equivalent to the %e format in date. <hour> shall be equivalent to the %H format in date. <minute> shall be equivalent to the %M format in date. <year> shall be equivalent to the %Y 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 is: "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.

STANDARD ERROR

Used only for diagnostic messages. The diagnostic message about creating a new archive when −c is not specified shall not modify the exit status.

OUTPUT FILES

Archives are files with unspecified formats.

EXAMPLES

The archive format is not described. It is recognized that there are several known ar formats, which are not compatible. The ar utility is being included, however, to allow creation of archives that are intended for use only on the same machine. The archive file 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 interface is included in the standard to provide an interface primarily for make and the compilers, based on a historical model. In historical implementations, the −q option is known to execute quickly because ar does not check 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. The remarks may or may not hold true for a brand-new POSIX. 2 implementation; and hence, these remarks have been moved out of the specification and into the Rationale. Likewise, historical implementations maintain a symbol table to speed searches, particularly when the archive contains object files. However, future implementors may or may not use a symbol table, and the −s option was removed from this clause to permit implementors freedom of choice. Instead, the requirement that archive libraries be suitable for link editing was added to ensure the intended functionality. Systems such as System V maintain the symbol table without requiring the use of −s, so adding −s (even if it were worded as allowing a no-op) would essentially require all portable applications to use it in all invocations involving libraries. The Operands subclause 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, POSIX. 2 makes the requirement explicit to avoid misunderstandings.

According to the System V documentation, the options −dmpqrtx are not required to begin with a hyphen ( − ). POSIX. 2 requires that a conforming application use the leading hyphen. When extracting files with long filenames into a file system that supports only shorter filenames, an undefined condition occurs. Typical implementation actions might be one of the following:

• Extract and truncate the filename only when an existing file would not be overlaid.
• Extract and truncate the filename and overlay an existing file only if some extension such as another command-line option were used to override this safety feature.
• Refuse to extract any files unless an extension overrode the default.

The archive format used by the cat(1) BSD implementation is documented in the 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> characters. If any fields are their particular maximum number of characters in length, there will be 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> character, although the size in the header does not reflect this.

HISTORY OF DECISIONS MADE

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 historical −m and −q positioning options were omitted, as were the positioning modifiers formerly associated with the −m and −r options, because the two functions of positioning are handled by the ranlib-style (a utility found on some historical systems to create symbol tables within the archive) symbol tables and/or the ability of portable applications to create multiple archives instead of loading from a single archive. Earlier drafts had elaborate descriptions in the Asynchronous Events subclause about how signals were caught and then resent to itself. These were removed in favor of the default case because they are essentially implementation details, unnecessary for the application. Similarly, information about where (and if) temporary files are created was removed from earlier drafts. The BSD −o option was omitted. It is a rare portable application that will use 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 existing 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 existing 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 right if the archive were moved to a machine that contained a different user database. Since ar cannot know whether the archive file 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 (e.g., /a/foo and /b/foo), it is reasonable to replace the member in the archive even when the modification time in the archive is identical to that in the file system.