ar(1)
ar - archive and library maintainer
As shipped in IRIX 6.5.5. Last changed in IRIX 6.5.5.
NAME ar - archive and library maintainer SYNOPSIS ar -d [-lv] archive file ... ar -m [-lv] [-abi] [posname] archive file ... ar -p [-ls] archive [file ...] ar -q [-clzf] archive file ... ar -r [-cuvsfl] [-abi] [posname] archive file ... ar -t [-vs] archive [file ...] ar -x [-vosCT] archive [file ...] IMPLEMENTATION IRIX systems DESCRIPTION The archiver (ar) maintains groups of files as a single archive file. Generally, you use this utility to create and update library files that the link editor uses; however, you can use the archiver for any similar purpose. This version of ar produces both 32-bit and 64-bit archives. The 32- bit archive format is defined in the System V Release 4 ABI. The 64- bit archive format is defined in the 64-bit ELF OBJECT File Specification. 32-bit objects and 64-bit objects cannot be mixed in an archive. The first object determines whether the archive will be 32-bit or 64-bit, if the archive does not exist to begin with. In compilers of version 7.x and higher, the archiver also archives WHIRL objects. Mixing is allowed between 32-bit relocatable ELF objects and 32-bit WHIRL objects, and between 64-bit relocatable ELF objects and 64-bit WHIRL objects. Different versions of WHIRL objects are NOT mixable. If the environment variable _XPG is defined, ar operates in conformance with the X/Open XPG4 specifications. The format of the output may differ in accordance to the XPG4 standards. Changes are either in the exit status or the format of the output. Any option that changes an object library causes the archive-symbol- table to be updated. This makes adding one file at a time to a library very slow. Useless options (such as using option -u with option -t) are not diagnosed. NOTE: ar uses a portable ASCII-format archive that you can use on various machines that run UNIX. Options are documented here with a leading hyphen(-) form. An older form with all option letters together and no leading hyphen is still supported. The first example below shows the old form. Examples: ar cr lib.a a.o b.o ar -c -r lib.a a.o b.o ar -cr lib.a a.o b.o Options are: -a Position new files in the archive after the file named by the posname operand. Use this suboption with the m or r options. -b Position new files in the archive before the file named by the posname operand. Use this suboption with the m or r options. -c Suppress the normal message that the archiver prints when it creates the archive file archive. Normally, the archiver creates the specified archiver file when it needs to. -C Prevent extracted files from replacing like-named files in the file system. This option is useful when -T is also used, to prevent truncated names from replacing files with the same prefix. -d Delete the specified files from archive. -i Position new files in the archive before the file named by the posname operand (equivalent to -b). Use this suboption with the -m or -r options. -f Adds padding to the end of each object file archived, using the character '\0'. This enables the loader (ld) to have faster access to members in the archive while performing static linking. Warning: this option results in the change in size of files permanently, normally increased by 1 to 15 bytes. In compiler releases 7.1 and higher, this option is the default. -l Puts temporary files in the local directory. If option -l is not supplied and the environment variable TMPDIR is defined then TMPDIR's value is used as the name of the directory for temporary files. If neither option -l nor TMPDIR is supplied, the archiver puts its temporary files in the directory /tmp. -m Moves the specified files to the end of the archive. If you specify a positioning character, you must also specify the posname (as in option -r) to tell the archiver where to move the files. -o Force each newly created file to have the `last modified' date that it had before it was extracted from the archive. -p Prints the contents of the files from archive to the standard output. If no files are specified, the contents of all files in the archive will be written in the order of the archive. -q Append the specified files to the end of the archive file. The archiver does not accept suboption positioning characters with the -q option. It also does not check whether the files you want to add already exist in the archive. This is useful to bypass the searching otherwise done when creating a large archive piece by piece. Since the archive-symbol-table of an object library is updated with -q it is advisable to add as many files as possible in one execution of ar. Only -qz (see -z below) avoids quadratic behavior when creating a large object archive piece by piece. -r Replace or add files to archive. If the archive named by archive does not exist, a new archive file will be created and a diagnostic message will be written to standard error (unless the -c option is specified). If no files are specified and the archive exists, nothing is done. Files that replace existing files will not change the order of the archive. If you use the suboption -u with -r, the archiver only replaces those files that have `last-modified' dates later than the archive files. If you use a positioning character (from the set abi) you must specify the posname argument to tell the archiver to put the new files after (a) or before (b or i). Otherwise, the archiver puts new files at the end of the archive. -s Makes an archive-symbol-table file in the archive. The -s option is automatically added when any of the options -d, -m, or -r is requested. If you specify -s, the archiver creates the archive-symbol-table file as its last action before finishing execution. You must specify at least one other archive option (m, p, d, r, or t) when you use the -s option. -t Write a table of contents for the files in archive to the standard output. If you don't specify any file names, write a table of contents for all files in the order of the archave. If you specify file names, the archiver writes a table of contents only for those files. -T Allow filename truncation of extracted files whose archive names are longer than the file system can support. By default, extracting a file with a name that is too long is an error; a diagnostic message will be written and the file will not be extracted. -u Update older files. When used with the -r option, files within the archive will be replaced only if the corresponding file is newer than the existing archive file. This option uses the UNIX system `last-modified' date for this comparison. -u gives no warning when replacement is refused. -v Gives a verbose file-by-file description as the archiver makes a new archive file from an old archive and its constituent files. When you use this option with -t, the archiver lists, on standard output, all information about the files in the archive. When you use this option with -p, the archiver writes the name of the file to standard output before writing the file itself to standard output. If you add a second -v additional informational messages can appear. -x Extract the files named by the file operands from the archive. The contents of the archive file will not be changed. If you don't specify any file names, the archiver extracts all files. Normally, the `last-modified' date for each extracted file shows the date when someone extracted it; however, when you use -o, the archiver resets the `last-modified' date to the date recorded in the archive. -z Only be useful with -q. -qz supresses updating of the archive- symbol-table and updates the archive in-place. The resulting archive cannot be used with ld (and is not a System V Release 4 ABI compliant archive) until an archive-symbol-table update is done. ld(1) will fail with a message suggesting use of ar -ts if the last change to the archive uses -qz: Use of -qz is discouraged: the updates are not checked for duplications and in case of a file or other error the archive may be destroyed. If any file name added is longer than 15 characters, line qz updates the archive-symbol-table even with -qz. If all file names added with qz on a particular execution are 15 characters or less the archive-symbol-table update is suppressed (even if some file names already in the archive are longer than 15 characters). x option. NOTES There is no ranlib program in IRIX. Option -s creates the archive- symbol-table ld uses. Options -r, -d, -m, and -q imply option -s. Since option -s creates an archive-symbol-table, creating an object library by executing ar once per object file will be very slow. Creating an object library with a single execution of ar is much faster. DIAGNOSTICS xxxxx not found The file xxxxx was not found in the archive. It could mean a simple misspelling, but it could also mean that you supplied xxxxx more than the number of times xxxxx appears in the archive! Files not found change the exit code from ar but any attempted update of the archive (by option r for example) is not suppressed. "not in archive format" You probably forgot to specify the archive name in the command. The archive mentioned in the synopsis should be the archive name. The diagnostics "s - creating Symbol hash table" and "s - done" are no longer emitted when -v is used (to make the -v output standard- conforming). If you really want to see those messages, add a second v, as in -vv. MORE NOTES The behavior documented in this section is not guaranteed to remain the same across releases. This section is provided as help in case ar does something surprising. If there is only one hard link (ie, at most one non-symbolic link) to an archive which is being updated then an old archive contents are replaced by the new contents by rename(2). (For more information on symbolic and hard links, see ln(2).) Otherwise, when updating, replacement is by copying the new data onto the old file. If the archive is updated, the replacement archive is built in the same directory as the named archive (after following symbolic links to the location of the named archive). In case the copy operation mentioned above is interrupted in mid-copy (which is normally not possible) ar will attempt to set the archive length to 0 and the modification-date to January 1, 1970 as a hint that the archive is not usable. If the ar command results in an unchanged archive, the old archive will not be replaced. This is best achieved with, for example, ar ru lib.a x.o; if the named object file is not put into the archive, the archive is not modified. The definition of unchanged is very conservative: ar r lib.a x.o, for example, always changes the archive since x.o is added or replaced (even though x.o itself may be unchanged). The following is a sampling of traditional ar behaviors that you may find surprising. If you specify the same file twice in an argument list, it can appear twice in the archive file. The o option does not change the `last-modified' date of a file unless you own the extracted file or you are the super-user. Trailing slashes are removed from file-path-names. Only the final component of a file-path-name is recorded in an archive. For example, in /a/b/c/dfile////, the file searched for is /a/b/c/dfile, and the name recorded in the archive is dfile. If you give ar the same name twice in an ar x command the second instance of the name will provoke a ``not found'' message. FILES /tmp/ar.tmp.v* or TMPDIR/ar.tmp.v* temporaries SEE ALSO lorder(1), ld(1), ar(4) System V Application Binary Interface, ISBN 0-13-877598-2, Prentice Hall This man page is available only online.