ar

archiving binary utility

Create and maintain library archives holding commonly needed subroutines.

ar -t [-TLsv] archive [file ]
ar -p [-TLsv] archive [file …]
ar -q [-cTLsv] archive file
ar -r [-cuTLsv] archive file
ar -r [-abciuTLsv] position archive file
ar -x [-ouTLsv] archive [file ]
ar -m [-abiTLsv] position archive file
ar -m [-TLsv] archive file
ar -d [-TLsv] archive file

Members in the archive have a simple name (sometimes restricted to 15 characters).

If multiple members in the archive have the same name, only the first will be selected.
Frequently used for the creation and maintenance of libraries for use with the loader although it is not restricted to this purpose. Order of members is significant. Otherwise tar may be more useful.

-t[v] Output table of contents entries containing only the specified files in the order they occur.
v Verbosely.
ar -t nrfc_t4t_lib_gccov.a
/
//
/0
isodepmsg.c.o/
nfc_t4t_lib.c.o/
/23
nrf_assert.c.o/
nrfx_atomic.c.o/
> ar -tv nrfc_t4t_lib_gccov.a
---------   0/0    2004 Mar 27 09:23 2020 /
---------   0/0      44 Dec 31 19:00 1969 //
rw-rw-rw-   0/0  570824 Mar 27 09:23 2020 /0
rw-rw-rw-   0/0  654428 Mar 27 09:23 2020 isodepmsg.c.o/
rw-rw-rw-   0/0  649580 Mar 27 09:23 2020 nfc_t4t_lib.c.o/
rw-rw-rw-   0/0  638620 Mar 27 09:23 2020 /23
rw-rw-rw-   0/0  563292 Mar 27 09:23 2020 nrf_assert.c.o/
rw-rw-rw-   0/0  629604 Mar 27 09:23 2020 nrfx_atomic.c.o/
> ar -t libm.a |head
/
acos.o/
addsf3.o/
addsf3x.o/
asin.o/
atan2.o/
…
-L with -t List using the extended format to allow long archive member names. default.
-p print the the files to the standard output.
(Not helpful if they are binary object members) in the order they occur.
>  ar -p libm.a |head -2|hexdump -C
00000000  00 00 00 57 00 00 04 82  00 00 07 a6 00 00 07 a6  |...W............|
00000010  00 00 0a 9e 00 00 0f fa  00 00 13 da 00 00 18 ae  |................|
00000020  00 00 1d 1a 00 00 22 ae  00 00 26 26 00 00 26 26  |......"...&&..&&|
00000030  00 00 26 26 00 00 26 26  00 00 26 26 00 00 29 4a  |..&&..&&..&&..)J|
…
00000150  00 00 f1 0c 00 00 f5 50  00 00 f9 80 00 00 fc c8  |.......P........|
00000160  61 63 6f 73 00 5f 5f 73  75 62 73 66 33 00 5f 5f  |acos.__subsf3.__|
00000170  61 64 64 73 66 33 00 5f  5f 61 64 64 73 66 33 78  |addsf3.__addsf3x|
…
-q Quickly append members. If the archive does not exist it is created.
-c Supress created message.
-r Replace OR add the members . Order of existing members is not changed.
appended unless -b(before) or -i(insert before) is specified.
-u update : with -r if member is older than file,
With -x : members will be extracted only if newer then file.
> ar -x libm.a modf.o
/home/realger1/www/docs/l > ls -l
       66,760        15:41 libm.a
          856        15:43 modf.o
-x[o] extract members to the files.
-o The ownerID, groupID, modes, access and modification times are preserved.
Owner & Group ID may NOT reflect the correct user on the system!
Only if the user is the owner or the super-user of the extracted file .
-d delete the archive files.
-m Move the archive files within the archive.
With -a, -b or -i files are moved before or after the position member.
-a Enter files after A positioning modifier used with the options -r and -m.
-b Enter files before
-i Insert files before
 
-S Supress Symbol table generation. resulting archive can not be used with the linker.
To build a symbol table, omit -S on the last execution of ar, or run ranlib on the archive.
-s Store an object-file index in the archive, or update an existing one, even if no other change is made to the archive.
ar -s is equivalent to running ranlib on it.
-v Provide verbose. With -d, -m, -q or -x , outputs a file-by-file description option letter, dash and member name.
With -r the initial letter a if member is added and r if the member is replaced.
With -p the name is output before the contents.
With -t displays an ls -l style listing
> ar -tv libm.a a*
---------       0/0          1086 Apr 14 10:25 2015 /
rw-r--r--     504/20          744 Apr 14 10:24 2015 acos.o/
rw-r--r--     504/20          700 Apr 14 10:24 2015 addsf3.o/
rw-r--r--     504/20         1312 Apr 14 10:24 2015 addsf3x.o/
rw-r--r--     504/20          932 Apr 14 10:24 2015 asin.o/
rw-r--r--     504/20         1176 Apr 14 10:24 2015 atan2.o/
rw-r--r--     504/20         1072 Apr 14 10:24 2015 atan.o/
-T Truncate member names to fifteen characters.
Names that are not unique in their first fifteen characters will subsequently be confused or over written.
A warning is output to the standard error if names are truncated.

Environment

$TMPDIR The pathname of the directory to use when creating temporary files.

Files

/tmp default temporary file directory ar.XXXXXXM temporary file names

Errors

ar: file: Inappropriate file type or format
not found in archive
No such file or directory
warning: /Library/Developer/CommandLineTools/usr/bin/ranlib: archive library: libm.a the table of contents is empty (no object file members in the library define global symbols)


Mac os

libtool

create libraries

ranlib

add or update the table of contents of archive libraries

libtool -static -o output [ -sacLTD ] [ -arch_only arch_type ] [ -no_warning_for_no_symbols ] [ - ] file... [-filelist listfile[,dirname]]

libtool -dynamic -o output [ -install_name name ] [ -compatibility_version number ]
        [ link editor flags ] [ -v ] [ -noall_load ] [ - ] [ -arch_only arch_type ] [ -V ] [ - ] file... [-filelist listfile[,dirname]]

ranlib [ -sactfqLT ] [ - ] archive...

libtool takes the input object files and creates a library for use with the link editor, ld(1). The library's name is specified by output (the argument to -o). The input object files must be object files (universal files, archives, object files).
ranlib will put non-object input file into the output .

When producing a universal file from objects of the same CPU type and differing CPU subtypes, libtool and ranlib create at most one library for each CPU type, rather than a separate library in a universal file for each of the unique pairings of CPU type and CPU subtype. The resulting CPU subtype for each library is the _ALL CPU subtype for that CPU type. This encourages the implementor to create one library that chooses optimum code to run at run time, rather than at link time.

Libtool can create either dynamically linked shared (-dynamic,) or statically linked (archive) (-static libraries.

Dynamically Linked Shared Libraries

Unlike statically linked libraries, are Mach-O format files and not ar(5) format files.
Dynamically linked libraries have two restrictions: No symbol may be defined in more than one object file and no common symbol can be used. To maximize sharing of a dynamically linked shared library the objects should be compiled with the -dynamic flag of cc(1) to produce indirect undefined references and position-independent code. To build a dynamically linked library, libtool, runs the link editor, ld(1), with -dylib once for each architecture present in the input objects and then lipo(1) to create a universal file if needed.

ARCHIVE (or statically linked) LIBRARIES

Libtool with -static is intended to replace ar(5) and ranlib. For backward compatibility, ranlib is still available, and it supports universal files. Ranlib adds or updates the table of contents to each archive so it can be linked by the link editor, ld(1). The table of contents is an archive member at the beginning of the archive that indicates which symbols are defined in which library members. Because ranlib rewrites the archive, sufficient temporary file space must be available in the file system that contains the current directory. Ranlib takes all correct forms of libraries (universal files containing archives, and simple archives) and updates the table of contents for all archives in the file. Ranlib also takes one common incorrect form of archive, an archive whose members are universal object files, adding or updating the table of contents and producing the library in correct form (a universal file containing multiple archives).

The archive member name for a table of contents begins with ``__.SYMDEF''. Currently, there are two types of table of contents produced by libtool -static and ranlib and understood by the link editor, ld(1). These are explained below, under the -s and -a options.

Don't warn about file that have no symbols. Write an Xcode dependency info file describing a successful build operation. This file describes the inputs directly or indirectly used to create the library or dylib.
libtool only.
@file Arguments beginning with @ are replaced by arguments read from the specified file, as an alternative to listing those arguments on the command line. The files simply contain libtool options and files separated by whitespace: spaces, tabs, and newlines. Characters can be escaped with a backslash (\), including whitespace characters and other backslashes. Also, arguments that include whitespace can be enclosed, wholly or in part, by single- or double-quote charcters. These files may contain @file references to additional files, although libtool will error on include cycles. If a file cannot be found, the original @file argument will remain in the argument list.
-static Produce a statically linked (archive) library from the input files. This is the default.
-dynamic Produce a dynamically linked shared library from the input files.
-install_name name For a dynamic shared library, this specifies the file name the library will be installed in for programs that use it. If this is not specified the name specified by the -o output option will be used.
-compatibility_version number For a dynamic shared library, this specifies the compatibility version number of the library. When a library is used the compatibility version is checked and if the user's version is greater that the library's version, an error message is printed and the using program exits. The format of number is X[.Y[.Z]] where X must be a positive non-zero number less than or equal to 65535, and .Y and .Z are optional and if present must be non- negative numbers less than or equal to 255. If this is not specified then it has a value of 0 and no checking is done when the library is used.
-current_version number For dynamic shared library files this specifies the current version number of the library. The program using the library can obtain the current version of the library programmatically to determine exactly which version of the library it is using. The format of number is X[.Y[.Z]] where X must be a positive non-zero number less than or equal to 65535, and .Y and .Z are optional and if present must be non-negative numbers less than or equal to 255. If this is not specified then it has a value of 0.
-noall_load For dynamic shared library files this specifies the the default behavior of loading all members of archives on the command line is not to be done. This option is used by the GNU compiler driver, cc(1), when used with it's -dynamiclib option. This is done to allow selective loading of the GNU's compiler's runtime support library, libcc_dynamic.a .
- Treat all remaining arguments as names of files (or archives) and not as options.
link editor flags For a dynamic shared library the following ld(1) flags are accepted and passed through: -lx, -weak-lx, -search_paths_first -weak_library, -Ldir, -ysym, -usym, -initsym, -idefinition:indirect, -seg1addr, -segs_read_only_addr, -segs_read_write_addr, -seg_addr_table, -seg_addr_table_filename, -segprot, -segalign, -sectcreate, -sectorder, -sectorder_detail, -sectalign, -undefined, -read_only_relocs, -prebind, -prebind_all_twolevel_modules, -prebind_allow_overlap, -noprebind, -framework, -weak_framework, -umbrella, -allowable_client, -sub_umbrella, -sub_library, -F, -U, -Y, -Sn, -Si, -Sp, -S, -X, -x, -whyload, -all_load. -arch_errors_fatal, -dylib_file, -run_init_lazily, -final_output, -macosx_version_min, -multiply_defined, -multiply_defined_unused, -twolevel_namespace, -twolevel_namespace_hints, -flat_namespace, -nomultidefs, -headerpad, -headerpad_max_install_names, -weak_reference_mismatches, -M, -t, -no_arch_warnings, -single_module, -multi_module, -exported_symbols_list, -unexported_symbols_list, -m, -dead_strip, -no_dead_strip_inits_and_terms, -executable_path, -syslibroot, -no_uuid. See the ld(1) man page for details on these flags. The flag -image_base is a synonym for -seg1addr.
-v Verbose mode, which prints the ld(1) commands and lipo(1) commands executed.
-V Print the version of libtool. -filelist listfile[,dirname] The listfile contains a list of file names and is an alternative way of specifiying file names on the command line. The file names are listed one per line separated only by newlines (spaces and tabs are assumed to be part of the file name). If the optional directory name, dirname is specified then it is prepended to each name in the list file. -arch_only arch_type This option causes libtool to build a library only for the specified arch_type and ignores all other architectures in the input files. When building a dynamic library, if this is specified with a specific cpusubtype other than the family cpusubtype then libtool it does not use the ld(1) -force_cpusubtype_ALL flag and passes the -arch_only argument to ld(1) as the -arch flag so that the output is tagged with that cpusubtype. The following options pertain to the table of contents for an archive library, and apply to both libtool -static and ranlib:
-s Produce the preferred type of table of contents, which results in faster link editing when linking with the archive. The order of the table of contents is sorted by symbol name. The library member name of this type of table of contents is ``__.SYMDEF SORTED''. This type of table of contents can only be produced when the library does not have multiple members that define the same symbol. This is the default.
-a Produce the original type of table of contents, whose order is based on the order of the members in the archive. The library member name of this type of table of contents is ``__.SYMDEF''. This type of table of contents must be used when the library has multiple members that define the same symbol.
-c Include common symbols as definitions with respect to the table of contents. This is seldom the intended behavior for linking from a library, as it forces the linking of a library member just because it uses an uninitialized global that is undefined at that point in the linking. This option is included only because this was the original behavior of ranlib. This option is not the default.
-L Use the 4.4bsd archive extended format #1, which allows archive member names to be longer than 16 characters and have spaces in their names. This option is the default.
-T Truncate archive member names to 16 characters and don't use the 4.4bsd extended format #1. This option is not the default.
-f Warns when the output archive is universal and ar(1) will no longer be able to operate on it.
-q Do nothing if a universal file would be created.
-D When building a static library, set archive contents' user ids, group ids, dates, and file modes to reasonable defaults. This allows libraries created with identical input to be identical to each other, regardless of time of day, user, group, umask, and other aspects of the environment.
- Treat all remaining arguments as names of files (or archives) and not as options.
-no_warning_for_no_symbols
-dependency_info path
SEE ALSO ld(1), ar(1), otool(1), make(1), redo_prebinding(1), ar(5) BUGS Errors are possible if the library was modified with ar(1) and the table of contents was not updated by rerunning ranlib(1). The link editor, ld(1), generated an error when the modification date of a library was more recent than the creation date of its table of contents,` even if you only copy the library. It is possible to get link errors if the library is modified and the table of contents is not updated.