ar

create and maintain library archives 

Command

SYNOPSIS

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 [-abcIilsv] [-F format] [posname] archive member ...

ar -x [-CIlsTv] archive [member ...]

DESCRIPTION

ar creates and maintains file archives. You can use ar to

These libraries may be in Intel Object Module Format (OMF) or Common Object File Format (COFF). On Windows systems, ar defaults to OMF format when creating a new library.

This implementation takes UNIX-compatible options and arguments, but works with libraries in either the OMF format or the COFF format. ar tries to deduce the format of an existing archive; the default for a new library is OMF format. You may specify the format of a new library with the -F option. Only valid OMF or COFF .obj files may be members of a library.

ar identifies each member in the archive by the final component (basename) of its file name. When adding a file to an archive, you can use the full path name, but when storing the member or comparing a member name, ar uses only the final component of the name.

Note:

Because other linker tools (and similar applications) do not support different object types in the same archive, all object files in an ar archive must be of the same type.

Options

ar accepts the following options that represent its main functions:

-d 

deletes each named member from the archive and regenerates the symbol table.

-m 

moves the named archive member in the archive. You indicate the new position for the member with -a, -b, or -i and posname; if you do not specify a location, ar moves the member to the end of the archive.

-p 

displays each specified member on the standard output. If you do not specify any members, ar displays all members.

-q 

quickly appends the specified file to the archive. ar does not check to see if file is already a member of the archive.

-r 

replaces or adds file to archive. If archive does not exist, ar creates it and prints a message. When ar replaces an existing member, it does not change the archive order. If file is not replacing a member, ar adds it to the end of the archive (unless you specify -a, -b, or -i). This option regenerates the symbol table.

-t 

displays a table of contents that lists member or every member if you do not specify a particular member. ar displays a diagnostic for each member that it cannot find. Normally, ar displays only the member's name, but with the verbose (-v) option, ar displays more information about archive members using a format similar to ls -l.

-x 

extracts each specified member from the archive and copies it to a file. If you specify member as a full path name, ar copies it to that path name. If you do not specify a member, ar extracts all members. The archive remains unchanged.

The following options modify the behavior of the main functions:

-a 

places file in archive after the member specified by posname. If you do not specify a member, ar adds file to the end of the archive.

-b 

places file in archive before the member specified by posname. If you do not specify posname, ar adds file to the beginning of the archive.

-C 

prevents ar from overwriting existing files with extracted files. You can only specify this option when extracting files with the -x option.

-c 

suppresses the message ar normally prints when it creates a new archive file. You can only use this in conjunction with the -r and -q options.

-F format 

specifies the archive format to be used by a new archive. Valid formats are omf and coff. You can only use this option when creating a new archive with the -r option or the -q option.

When no format for a new library is specified, ar creates the new library using the format (OMF or COFF) of the first .obj file specified on the command line. If no .obj files exist on the command line, the library is created using the OMF format.

-I 

ignores the case of letters when searching the archive for specified member names. Normally, the case is significant.

-i 

inserts the file into the archive before the member specified by posname. If you do not specify posname, ar inserts file at the beginning of the archive. This option is the same as -b.

-l 

puts any temporary files that ar generates in the current directory rather than the default temporary file directory.

-s 

regenerates the symbol table regardless of whether the command modifies the archive.

-T 

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.

-u 

replaces the member only if the modification time of the file member is more recent than the time of the archive member. -u implies -r, so it is not necessary to specify -r also.

-v 

gives verbose output. With -d, -q, -r, and -x, this option displays the command letter and the member name affected before performing each operation. With -t, it prints more information about archive members using a format similar to ls -l. With -p, it displays the member name before the contents.

DIAGNOSTICS

Possible exit status values are:

0 

Successful completion.

1 

Failure due to any of the following:

— 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 invalid module on appending
— inability to access the module on appending
— a module not found on table/extraction
2 

Invalid command line arguments or options

PORTABILITY

POSIX.2. x/OPEN Portability Guide 4.0. Windows 8.1. Windows Server 2012 R2. Windows 10. Windows Server 2016. Windows Server 2019. Windows 11. Windows Server 2022. All UNIX systems.

On Windows systems, the archive format is either OMF, or the Common Object File Format (COFF). The options included in this implementation are the best possible approximation of those defined by the POSIX standard for the ar command, to make makefiles reasonably portable. For historical compatibility, you can omit the - preceding 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 -I options are extensions to the POSIX and XPG standards.

AVAILABILITY

PTC MKS Toolkit for System Administrators
PTC MKS Toolkit for Developers
PTC MKS Toolkit for Interoperability
PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition
PTC Windchill Requirements and Validation

SEE ALSO

Commands:
cc, make

PTC MKS Toolkit 10.4 Documentation Build 39.