Commands Reference, Volume 1

ar Command

The ar command includes information for ar on a POWER-based platform and an ar on an Itanium-based platform.

ar Command on POWER-based Platform

Purpose

Maintains the indexed libraries used by the linkage editor.

Syntax

ar [ -c ] [ -l ] [ -g | -o ] [ -s ] [ -v ] [ -C ] [ -T ] [ -z ] { -h | -p | -t | -x } [ -X {32|64|32_64}] ArchiveFile [ File ... ]

ar [ -c ] [ -l ] [ -g | -o ] [ -s ] [ -v ] [ -C ] [ -T ] [ -z ] { -m | -r [ -u ] } [ { -a | -b | -i } PositionName ] [ -X {32|64|32_64}] ArchiveFile File ...

ar [ -c ] [ -l ] [ -g | -o ] [ -s ] [ -v ] [ -C ] [ -T ] [ -z ] { -d | -q } [ -X {32|64|32_64}] ArchiveFile File ...

ar [ -c ] [ -l ] [ -v ] [ -C ] [ -T ] [ -z ] { -g | -o | -s | -w } [ -X {32|64|32_64}] ArchiveFile

The ar command maintains the indexed libraries used by the linkage editor. The ar command combines one or more named files into a single archive file written in ar archive format. When the ar command creates a library, it creates headers in a transportable format; when it creates or updates a library, it rebuilds the symbol table. See the ar file format entry for information on the format and structure of indexed archives and symbol tables.

There are two file formats that the ar command recognizes. The Big Archive Format, ar_big, is the default file format and supports both 32-bit and 64-bit object files. The Small Archive Format can be used to create archives that are recognized on versions older than AIX 4.3, see the -g flag. If a 64-bit object is added to a small format archive, ar first converts it to the big format, unless -g is specified. By default, ar only handles 32-bit object files; any 64-bit object files in an archive are silently ignored. To change this behavior, use the -X flag or set the OBJECT_MODE environment variable.

Flags

In an ar command, you can specify any number of optional flags from the set cClosTv. You must specify one flag from the set of flags dhmopqrstwx. If you select the -m or -r flag, you may also specify a positioning flag (-a, -b, or -i); for the -a, -b, or -i flags, you must also specify the name of a file within ArchiveFile (PositionName), immediately following the flag list and separated from it by a blank.

-a PositionName	Positions the named files after the existing file identified by the PositionName parameter.
-b PositionName	Positions the named files before the existing file identified by the PositionName parameter.
-c	Suppresses the normal message that is produced when library is created.
-C	Prevents extracted files from replacing like-named files in the file system.
-d	Deletes the named files from the library.
-g	Orders the members of the archive to ensure maximum loader efficiency with a minimum amount of unused space. In almost all cases, the -g flag physically positions the archive members in the order in which they are logically linked. The resulting archive is always written in the small format, so this flag can be used to convert a big-format archive to a small-format archive. Archives that contain 64-bit XCOFF objects cannot be created in or converted to the small format.
-h	Sets the modification times in the member headers of the named files to the current date and time. If you do not specify any file names, the ar command sets the time stamps of all member headers. This flag cannot be used with the -z flag.
-i PositionName	Positions the named files before the existing file identified by the PositionName parameter (same as the -b).
-l	Places temporary files in the current (local) directory instead of the TMPDIR directory (by default /tmp).
-m	Moves the named files to some other position in the library. By default, it moves the named files to the end of the library. Use a positioning flag (abi) to specify some other position.
-o	Orders the members of the archive to ensure maximum loader efficiency with a minimum amount of unused space. In almost all cases, the -o flag physically positions the archive members in the order in which they are logically linked. The resulting archive is always written in the big archive format, so this flag can be used to convert a small-format archive to a big-format archive.
-p	Writes to standard output the contents of the named in the Files parameter, or all files specified in the ArchiveFile parameter if you do not specify any files.
-q	Adds the named files to the end of the library. In addition, if you name the same file twice, it may be put in the library twice.
-r	Replaces a named file if it already appears in the library. Since the named files occupy the same position in the library as the files they replace, a positioning flag does not have any additional effect. When used with the -u flag (update), the -r flag replaces only files modified since they were last added to the library file. If a named file does not already appear in the library, the ar command adds it. In this case, positioning flags do affect placement. If you do not specify a position, new files are placed at the end of the library. If you name the same file twice, it may be put in the library twice.
-s	Forces the regeneration of the library symbol table whether or not the ar command modifies the library contents. Use this flag to restore the library symbol table after using the strip command on the library.
-t	Writes to the standard output a table of contents for the library. If you specify file names, only those files appear. If you do not specify any files, the -t flag lists all files in the library.
-T	Allows file name truncation if the archive member name is longer than the file system supports. This option has no effect because the file system supports names equal in length to the maximum archive member name of 255 characters.
-u	Copies only files that have been changed since they were last copied (see the -r flag discussed previously).
-v	Writes to standard output a verbose file-by-file description of the making of the new library. When used with the -t flag, it gives a long listing similar to that of the ls -l command. When used with the -x flag, it precedes each file with a name. When used with the -h flag, it lists the member name and the updated modification times.
-w	Displays the archive symbol table. Each symbol is listed with the name of the file in which the symbol is defined.
-x	Extracts the named files by copying them into the current directory. These copies have the same name as the original files, which remain in the library. If you do not specify any files, the -x flag copies all files out of the library. This process does not alter the library.
-X mode	Specifies the type of object file ar should examine. The mode must be one of the following: 32 Processes only 32-bit object files 64 Processes only 64-bit object files 32_64 Processes both 32-bit and 64-bit object files The default is to process 32-bit object files (ignore 64-bit objects). The mode can also be set with the OBJECT_MODE environment variable. For example, OBJECT_MODE=64 causes ar to process any 64-bit objects and ignore 32-bit objects. The -X flag overrides the OBJECT_MODE variable.
-z	Creates a temporary copy of the archive and performs all requested modifications to the copy. When all operations have completed successfully, the working copy of the archive is copied over the original copy. This flag cannot be used with the -h flag.
ArchiveFile	Specifies an archive file name; required.
MemberName ...	Names of individual archive members.

Exit Status

This command returns the following exit values:

0	Successful completion.
>0	An error occurred.

Examples

To create a library, enter:
```
ar -v -q lib.a strlen.o strcpy.o
```
If the lib.a library does not exist, this command creates it and enters into it copies of the files strlen.o and strcpy.o. If the lib.a library does exist, then this command adds the new members to the end without checking for duplicate members. The v flag sets verbose mode, in which the ar command displays progress reports as it proceeds.
To list the table of contents of a library, enter:
```
ar -v -t lib.a
```
This command lists the table of contents of the lib.a library, displaying a long listing similar to the output of the ls -l command. To list only the member file names, omit the -v flag.
To replace or add new members to a library, enter:
```
ar -v -r lib.a strlen.o strcat.o
```
This command replaces the members strlen.o and strcat.o. If lib.a was created as shown in example 1, then the strlen.o member is replaced. A member named strcat.o does not already exist, so it is added to the end of the library.
To specify where to insert a new member, enter:
```
ar -v -r -b strlen.o lib.a strcmp.o
```
This command adds the strcmp.o file, placing the new member before the strlen.o member.
To update a member if it has been changed, enter:
```
ar -v -r -u lib.a strcpy.o
```
This command replaces the existing strcpy.o member, but only if the file strcpy.o has been modified since it was last added to the library.
To change the order of the library members, enter:
```
ar -v -m -a strcmp.o lib.a strcat.o strcpy.o
```
This command moves the members strcat.o and strcpy.o to positions immediately after the strcmp.o member. The relative order of the strcat.o and strcpy.o members is preserved. In other words, if the strcpy.o member preceded the strcat.o member before the move, it still does.
To extract library members, enter:
```
ar -v -x lib.a strcat.o strcpy.o
```
This command copies the members strcat.o and strcpy.o into individual files named strcat.o and strcpy.o, respectively.
To extract and rename a member, enter:
```
ar -p lib.a strcpy.o >stringcopy.o
```
This command copies the member strcpy.o to a file named stringcopy.o.
To delete a member, enter:
```
ar -v -d lib.a strlen.o
```
This command deletes the member strlen.o from the lib.a library.
To create an archive library from multiple shared modules created with the ld command, enter:
```
ar -r -v libshr.a shrsub.o shrsub2.o shrsub3.o ...
```
This command creates an archive library named libshr.a from the shared modules named shrsub.o, shrsub2.o, shrsub3.o, and so on. To compile and link the main program using the libshr.a archive library, use the following command:
```
cc -o main main.c -L/u/sharedlib -lshr
```
The main program is now executable. Any symbols referenced by the main program that are contained by the libshr.a archive library have been marked for deferred resolution. The -l flag specifies that the libshr.a library be searched for the symbols.
To list the contents of lib.a, ignoring any 32-bit object file, enter:
```
ar -X64 -t -v lib.a
```
To extract all 32-bit object files from lib.a, enter:
```
ar -X32 -x lib.a
```
To list all files in lib.a, whether 32-bit, 64-bit, or non-objects, enter:
```
ar -X32_64 -t -v lib.a
```

File

/tmp/ar*

Contains temporary files.

Related Information

The ld command, lorder command, make command, nm command, strip command.

The a.out file format, ar file format (Big), ar file format (Small).

ar Command on Itanium-based Platform

Purpose

Maintain portable archive or library.

Syntax

ar [-V] -key [arg] [posname] afile [name . . . ]

Description

The ar command maintains groups of files combined into a single archive file. Its main use is to create and update library files. However, it can be used for any similar purpose. If an archive is composed of printable files, the entire archive is printable.

When ar creates an archive, it creates headers in a format that is portable across all machines. The archive symbol table (described in ar file format is used by the link editor ld to effect multiple passes over libraries of object files in an efficient manner. An archive symbol table is only created and maintained by ar when there is at least one object file in the archive. The archive symbol table is in a specially named file that is always the first file in the archive. This file is never mentioned or accessible to the user. Whenever the ar command is used to create or update the contents of such an archive, the symbol table is rebuilt. The s argument to key, described below, will force the symbol table to be rebuilt.

-V: Cause ar to print its version number on standard error.
-key [arg]: key is formed with one of the following characters: drqtpmx. arg is formed with one of more of the following letters: vucs. An additional single-character argument to key, called the positioning character (chosen from one of the following letters: abi), can be used with key characters r and m. key characters are described below.
posname: Archive member name used as a reference point in positioning other files in the archive.
afile: Archive file.
name: One or more constituent files in the archive file.

The meanings of the key characters are as follows:

-d: Delete the named files from the archive file.
-m: Move the named files to the end of the archive. If an optional positioning character from the set abi is used, the posname argument must be present and specifies that new files are to be placed after a or before b or i posname. Otherwise new files are placed at the end.
-p: Print the named files in the archive.
-q: Quickly append the named files to the end of the archive file. Optional positioning characters are invalid. The command does not check whether the added members are already in the archive. This option is useful to avoid creating a large archive piece-by-piece.
-r: Replace the named files in the archive file. If the optional argument u is used with r, replace only those files with dates of modification later than the named files already in the archive. If an optional positioning character from the set abi is used, the posname argument must be present and specifies that new files are to be placed after a or before b or i posname. Otherwise new files are placed at the end.
-t: Print a table of contents of the archive file. If no names are given, all files in the archive are listed. If names are given, only those files are listed.
-u: Update older files. When used with the -r option, files within the archive are replaced only if the corresponding file has a modification time that is at least as new as the modification time of the file within the archive.
-x: Extract the named files. If no names are given, all files in the archive are extracted. In neither case does x alter the archive file.

The meanings of the other key arguments are as follows:

v: Give a verbose file-by-file description of the making of a new archive file from the old archive and the constituent files. When used with the -t option, give a long listing of all information about the files. When used with x, d, or r, print the name of the file preceding each extraction. When used with p, write the file to standard output.
c: Suppress the message that is produced by default when afile is created.
s: Force the regeneration of the archive symbol table even if ar is not invoked with a command which will modify the archive contents. This command is useful to restore the archive symbol table after the strip command has been used on the archive.

Files

/usr/lib/nls/msg/locale/LC_MESSAGES/uxar: language-specific message file (See LANG on environ.)

Related Information

The a.out file format, ar file format.

The ld command, lorder command, strip command.

Notices

If the same file is mentioned twice in an argument list, it may be put in the archive twice.

Since the archiver no longer uses temporary files, the -l option is obsolete and occurrences of this option are ignored.

By convention, archives are suffixed with the characters .a.

Applications currently using options without the leading hyphen must be changed to use the hyphen since non-hyphenated options may not be supported in a future release.