ar Command Purpose Maintains the indexed libraries used by the linkage editor. Syntax ar [ c ] [ l ] [ o ] [ s ] [ v ] { m [ a | b | PositionName | r [ a | b | i | u ] PositionName | { d | h | p | q | t | w | x } } ArchiveFile Name ... Description The ar command combines one or more named files into a single ArchiveFile written in ar archive format. When ar creates a li- brary, it creates headers in a transportable format; when it creates or updates a library, it rebuilds the symbol table. See the ar file entry for information on the format and structure of indexed archives and symbol tables. Flags In an ar command, you must list all selected flags together on the command line without blanks between them. One optional dash can precede the list of flags. You can specify any number of op- tional flags from the set closv. You must specify one flag from the set dhmpqrtwx. If you select m or r, you may also specify a positioning flag (a, b, or i); for a, b, or i, you must also specify the name of a file within ArchiveFile (PositionName), im- mediately following the flag list and separated from it by a blank. a PositionName Positions the named files after the existing file identified by PositionName. b PositionName Positions the named files before the existing file identified by PositionName. c Suppresses the normal message that is produced when library is created. d Deletes the named files from the library. 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, ar sets the time stamps of all member headers. i PositionName Positions the named files before the existing file identified by PositionName (same as b). l Places temporary files in the current (local) directory instead of directory /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 Sequentially orders and compresses an archive file. The ar- chive file members are linked together within the archive and may not be in sequential order. If file members are deleted or re- placed, free space may occur in the archive. This option re- builds the archive file with the members in sequential order and all free space removed. Sufficient temporary file space must ex- ist to perform this operation. p Writes to standard output the contents of the named Files, or all files in an ArchiveFile if you do not specify any files. q Adds the named files to the end of the library. Positioning flags, if present, do not have any effect. Note that this pro- cess does not check to see if the named files are already in 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 ad- ditional effect. When used with the u flag (update), r replaces only files modified since they were last added to the library file. If a named file does not already appear in the library, ar 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 ar modifies the library contents. Use this flag to restore the library symbol table after using the strip command on the li- brary. t Writes to the standard output a table of contents for the li- brary. If you specify file names, only those files appear. If you do not specify any files, t lists all files in the library. u Copies only files which 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, x copies all files out of the library. This process does not alter the library. ArchiveFile An archive file name; required. Name... Names of individual archive members. Exit Status This command returns the following exit values: 0 Successful completion. >0 An error occurred. Examples 1. To create a library, enter: ar vq lib.a strlen.o strcpy.o If lib.a does not exist, then this creates it and enters into it copies of the files strlen.o and strcpy.o. If lib.a does exist, then this adds the new members to the end without checking for duplicate members. The v flag sets verbose mode, in which ar displays progress reports as it proceeds. 2. To list the table of contents of a library, enter: ar vt lib.a This lists the table of contents of lib.a, displaying a long listing similar to ls -l. To list only the member file names, omit the v flag. 3. To replace or add new members to a library, enter: ar vr lib.a strlen.o strcat.o This replaces the members strlen.o and strcat.o. If lib.a was created as shown in Example 2, then the strlen.o member is re- placed. A member named strcat.o does not already exist, so it is added to the end of the library. 4. To specify where to insert a new member, enter: ar vrb strlen.o lib.a strcmp.o This adds strcmp.o, placing the new member before strlen.o. 5. To update a member if it has been changed, enter: ar vru lib.a strcpy.o This replaces the existing strcpy.o member, but only if the file strcpy.o has been modified since it was last added to the li- brary. 6. To change the order of the library members, enter: ar vma strcmp.o lib.a strcat.o strcpy.o This moves the members strcat.o and strcpy.o to positions immedi- ately after strcmp.o. The relative order of strcat.o and strcpy.o is preserved. In other words, if strcpy.o preceded strcat.o before the move, then it still does. 7. To extract library members, enter: ar vx lib.a strcat.o strcpy.o This copies the members strcat.o and strcpy.o into individual files named strcat.o and strcpy.o, respectively. 8. To extract and rename a member, enter: ar p lib.a strcpy.o >stringcopy.o This copies the member strcpy.o to a file named stringcopy.o. 9. To delete a member, enter: ar vd lib.a strlen.o This deletes the member strlen.o from the library lib.a. 10. To create an archive library from multiple shared libraries created with the ld command, enter : ar rv libshr.a shrsub.o shrsub2.o shrsub3.o ... This creates an archive library named libshr.a from the shared libraries named shrsub.o, shrsub2.o, shrsub3.o, etc. To compile and link the program main using the archive library libshr.a, use the following command: cc -o main main.c -L/u/sharedlib -lshr The program main is now executable. Any symbols referenced by main that are contained by the archive library libshr.a have been marked for deferred resolution. The -l flag specifies that the libshr.a library be searched for the symbols. Implementation Specifics This command is part of Base Operating System (BOS) Runtime. Files /tmp/ar* Temporary files. Related Information The ld command, lorder command, make command, nm command, strip command. The a.out file format, ar file format. ================================================================= ================================================================= ar File Format Purpose Describes the indexed archive file format. Description The ar (archive) command combines several files into one. The ar command creates an archive file. The ld (link editor) command searches archive files to resolve program linkage. The /usr/include/ar.h file describes the archive file format. Fixed-Length Header Each archive begins with a fixed-length header that contains offsets to special archive file members. The fixed-length header also contains the magic number, which identifies the archive file. The fixed-length header has the following format: #define AIAMAG "\n" /* Magic string */ #define SAIAMAG 8 /* Length of magic string */ struct fl_hdr /* Fixed-length header */ { char fl_magic[SAIAMAG]; /* Archive magic string */ char fl_memoff[12]; /* Offset to member table */ char fl_gstoff[12]; /* Offset to global symbol table */ char fl_fstmoff[12]; /* Offset to first archive member */ char fl_lstmoff[12]; /* Offset to last archive member */ char fl_freeoff[12]; /* Offset to first mem on free list */ }; The indexed archive file format uses a double-linked list within the archive file to order the file members. Therefore, file members may not be sequentially ordered within the archive. The offsets contained in the fixed-length header locate the first and last file members of the archive. Member order is determined by the linked list. The fixed-length header also contains the offsets to the member table, the global symbol table, and the free list. Both the member table and the global symbol table exist as members of the archive and are kept at the end of the archive file. The free list contains file members that have been deleted from the ar- chive. When adding new file members to the archive, free list space is used before the archive file size is expanded. A zero offset in the fixed-length header indicates that the member is not present in the archive file. File Member Header Each archive file member is preceded by a file member header, which contains the following information about the file member: #define AIAFMAG "`\n" /* Header trailer string */ struct ar_hdr /* File member header */ { char ar_size[12]; /* File member size - decimal */ char ar_nxtmem[12]; /* Next member offset - decimal*/ char ar_prvmem[12]; /* Previous member offset - dec */ char ar_date[12]; /* File member date - decimal */ char ar_uid[12]; /* File member user id - decimal */ char ar_gid[12]; /* File member group id - decimal */ char ar_mode[12]; /* File member mode - octal */ char ar_namlen[4]; /* File member name length - dec */ union { char ar_name[2]; /* Start of member name */ char ar_fmag[2]; /* AIAFMAG - string to end */ }; _ar_name; /* Header and member name */ }; The member header provides support for member names up to 255 characters long. The ar_namlen field contains the length of the member name. The character string containing the member name be- gins at the _ar_name field. The AIAFMAG string is cosmetic only. Each archive member header begins on an even-byte boundary. The total length of a member header is: sizeof (struct ar_hdr) + ar_namlen The actual data for a file member begins at the first even-byte boundary beyond the member header and continues for the number of bytes specified by the ar_size field. The ar command inserts null bytes for padding where necessary. All information in the fixed-length header and archive members is in printable ASCII format. Numeric information, with the excep- tion of the ar_mode field, is stored as decimal numbers; the ar_mode field is stored in octal format. Thus, if the archive file contains only printable files, you can print the archive. Member Table A member table is always present in an indexed archive file. This table quickly locates members of the archive. The fl_memoff field in the fixed-length header contains the offset to the member table. The member table member has a zero-length name. The ar command automatically creates and updates (but does not list) the member table. A member table contains the following information: * The number of members. This member is 12 bytes long and stored in ASCII format as a decimal number. * The array of offsets into the archive file. The length is 12 times the number of members. Each offset is 12 bytes long and stored in ASCII format as a decimal number. * The name string table. The size is: ar_size - (12 * (the number of members +1)); that is, the size equals the total length of all members minus the length of the offsets, minus the length of the number of members. The string table contains the same number of strings as offsets. All strings are null-terminated. Each offset from the array corresponds sequentially to a name in the string table. Global Symbol Table If an archive file contains XCOFF object-file members that are not stripped, the archive file will contain a global symbol-table member. This global symbol table locates file members that de- fine global symbols. The strip command deletes the global symbol table from the archive. The fl_gstoff field in the fixed-length header contains the offset to the global symbol table. The glo- bal symbol table member has a zero-length name. The ar command automatically creates and updates, but does not list the global symbol table. A global symbol table contains the following in- formation: * The number of symbols. This is 4 bytes long and can be ac- cessed with the sgetl and sputl commands. * The array of offsets into the archive file. The length is four times the number of symbols. Each offset is 4 bytes long and can be accessed with the sgetl and sputl commands. * The name-string table. The size is: ar_size - (4 * (the number of symbols + 1)); That is, the size equals the total length of the members, minus the length of the offsets, minus the length of the number of sym- bols. The string table contains the same number of strings as offsets. All strings are null-terminated. Each offset from the array corresponds sequentially to a name in the string table. Implementation Specifics This file is part of Base Operating System (BOS) Runtime. Related Information The a.out file format. The ar command, ld command, strip command. The sgetl or sputl subroutine. The Header Files Overview in AIX Version 3.2 Files Reference.