Commands Reference, Volume 1

ar Command

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

Description

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. Because 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 ar file format (Big), and the ar file format (Small).