ar - Create or maintain library archives


  • ar -d[-Ilv] archive member ... ..
  • ar -m[-abIilsv] [posname] archive member ...
  • ar -p[-Ilsv] archive member ...
  • ar -q[-clsv] [-F format] archive member ...
  • ar -r[abcIilsuv] [-F format] [posname] archive member ...
  • ar -t[Ilsv] archive member ...]
  • ar -u[-abcIiklsv] [-Fformat] [posname] archive member ...
  • ar -x[-CIlsTv] archive member...] ...


ar maintains archive libraries. The archive library is a collection of files, typically object files. Using ar, you can create a new library, add members to an existing library, delete members from a library, extract members from a library, and print a table of contents for a library.

A library member is an arbitrary file. Typically, these files are object files or side files, suitable for use by a linkage editor.

If any members of a library are object files, ar creates and maintains an external symbol index for link-editing.

Member names in an archive are only the final component of any path name. When creating a new library member (member) as given on the command line, ar uses the full path name given. When storing the member name in the library, or comparing a member name, ar uses only the final component.


The format shows the main functions of ar, which are defined as follows:
Deletes each named member from the archive and regenerates the symbol table.
Moves the named archive member in the archive. The new position is specified by -a, -b, i, or posname. If a location is not specified, the member is moved to the end of the archive.
Displays each member specified to the standard output. If you did not specify any members, ar displays all members.
Quickly appends the specified file to the archive. With this option, ar does not check to see if file is already a member of the archive.
Replaces or adds file to archive. If archive does not exist, ar creates it and prints a message. When ar replaces an existing member, the archive order is not changed. If file is not replacing a member, it is added to the end of the archive unless -a, -b, or -i is used. This option regenerates the symbol table.
Displays a table of contents that lists members, or every member if member is not specified. ar prints a message for each member it does not find. By default, ar prints the member name for all selected members. With the verbose (-v) option, ar prints more information for all selected members.
Extracts each specified member from the archive and copies it to a file. If member is specified as a full path name, it is copied to that path name. If no member is specified, all members are extracted. The archive remains unchanged.
The following options change the behavior of the main functions:
Places file in the archive after the member specified by posname. If no member is named, file is added to the end of the archive.
Places file in the archive before the member specified by posname. If no member is named, file is placed at the beginning of the archive.
Prevents ar from overwriting existing files with extracted files. This option is used only with extraction (-x).
Suppresses the message that is normally printed when ar creates a new archive file. You can use this only in conjunction with the -r and -q options.
-F format
Specifies the archive format to be used by a new archive. You can use this option only when creating a new archive with the -r and -q options.
Ignores the case of letters when searching the archive for specified member names. Normally, the case is significant.
Inserts file into the archive before the member specified by posname. If posname isn't specified, ar inserts file at the beginning of the archive. This option is the same as -b.
This option is ignored. It requests that temporary files that are generated by ar be put in the directory rather than in the default temporary file directory. It is provided for compatibility with earlier versions of ar
Regenerates the external symbol table regardless of whether the command modifies the archive.
When used with -x, allows extraction of members with names longer than the file system supports. Normally this is an error and ar does not extract the file. Most file systems truncate the file name to the appropriate length.
Replaces the archive member only if the member file's modification time is more recent than the archive member time. -u implies -r, so it is not necessary to specify -r also.
Gives verbose output. With -d, -q, -r, and -x, this option prints the command letter and the member name affected before performing each operation. With -t, ar prints more information about archive members using a format similar to ls -l. With -p, ar writes the name of the member to standard output, before displaying the contents of the file.


Specifies the path name of the archive file.
Specifies the path name of the file that is to be acted upon (placed, deleted, searched for, and so on) in the archive library.


  1. To add a member fioacc.o to the archive file /u/turner/bin/cliserpgm.a, specify:
    ar -rc /u/turner/bin/cliserpgm.a fioacc.o
  2. To display the members of the archive file /u/turner/bin/cliserpgm.a, specify:
    ar -tv /u/turner/bin/cliserpgm.a
  3. To delete the member repgen.o from the archive file /u/turner/bin/cliserpgm.a and regenerate the external symbol table for the archive, specify:
    ar -ds /u/turner/bin/cliserpgm.a repgen.o

Environment variables

ar uses the following environment variable:
The path name of the directory that is used for temporary files. If it is not set, z/OS UNIX uses /tmp.


ar uses the following localization environment variables:
  • LANG
  • LC_ALL

See Localization for more information.


ar creates temporary files in the directory of the archive file and in the directory named by the TMPDIR environment variable. These files are intermediate versions of the archive file being created or updated. Consequently, they require approximately the same file size as the archive file being manipulated.

Usage notes

ar can be used to store multiple versions of the same object file within one archive library. This is useful if you are providing an archive library which might be used to resolve references from code that is compiled with various compiler options. These options cause differences in the object files which must be matched with the archive library member attributes. Attributes for ar are: AMODE, XPLINK, and IPA.

ar will store the attribute information for every entry in the symbol table. The linkage editor will use the attribute information to resolve external references with the appropriate archive library member. Because archive library member names are only the final component of the path name, these member names must be unique for the different object file versions.

Side files (normally those created when link-editing a DLL) can be made members of an archive file. When the linkage editor processes such an archive file, it will normally read in all such side-files so that archives can be used for resolving symbol references in DLLs. For more information about resolving external references, see z/OS MVS Program Management: User's Guide and Reference.

You will want to establish a naming convention for the object files, and change your build procedures to generate the correct names. For example, if your archive contains three versions of myfuncs.o, you could generate names
     myfuncs.o			AMODE(31), non-XPLINK
     myfuncsX.o		AMODE(31), XPLINK
     myfuncs64.o		AMODE(64) (AMODE(64) always forces XPLINK)
Your make file might generate commands such as these:
     c89 -c myfuncs.c
     c89 -Wc,xplink -o myfuncsX.o -c myfuncs.c
     c89 -Wc,LP64 -o myfuncs64.o -c myfuncs.c
     ar  -ruv libmyfuncs.a myfuncs.o myfuncsX.o myfuncs64.o
To display the attributes of the symbols within an object file or an archive library of object files, use nm - Display symbol table of object, library, or executable files.

Exit values

Successful completion.
Failure due to any of the following reasons:
  • Inability to create the extracted file.
  • An error writing to the extracted file.
  • The requested module not found on appending.
  • An error opening the module on appending.
  • An incorrect module on appending.
  • Inability to access the module on appending.
  • A module not found on table or extraction.
Incorrect command-line arguments or options.


POSIX.2, X/Open Portability Guide, UNIX systems.

For compatibility with earlier versions, you can omit the dash that precedes the options if the options appear only as the first argument after the command name.

The following options are XPG extensions to the POSIX standard: -a, -b, -C, -i, -l, -m, -q, -s, and -t.

The -F and the -i options are extensions to the POSIX and XPG standards.

Related information

c89, make, nm