9.1. tiarmar - Archiver

The tiarmar command can be used to collect several files, such as object files and LLVM bitcode files, into a single archive library that can be linked into a program. By default, tiarmar generates a symbol table that can be consulted at link-time to aid the linker in determining whether a member of the archive can be pulled into the link to resolve a reference to an unresolved symbol.

When the tiarmar command is used to create an archive of LLVM bitcode files, the archive’s symbol table will contain both native and bitcode symbols.

9.1.1. Usage

tiarmar [-] <operation> [<modifier>] {<relpos>] {<count>] <archive> [<files> …]

  • <operation> - is an option identifying a single basic operation to be performed on the specified <archive>.

  • <modifier> - is an option that is applicable to the specified <operation> and indicates what available modifiers are to applied during the specified <operation>.

  • <relpos> - indicates position in an existing <archive> where a file is to be moved or inserted. This argument is only applicable when using the a, b, or i operation-specific <modifier> arguments.

  • <count> - identify an instance of a specified file that the specified <operation> applies to. This argument is only applicable in combination with the d <operation> and the N <modifier>.

  • <archive> - identifies the archive file that tiarmar will operate on.

  • <files> - optionally identifies a list of one of more files to be considered as input when operating on the specified <archive> file. if no <files> are specified, this generally refers to “none” or “all” of the <archive> members being the subject of the specified <operation>.

The minimal set of arguments to the tiarmar command includes at least one <operation> and the name of the <archive> file.

9.1.2. Operations/Modifiers

d[NT]

Delete specified <files> from the <archive>. If a specified file does not appear in the <archive>, it is simply ignored. If no <files> are specified, then the <archive> will not be modified.

Operation-Specific Modifiers

  • N - when there are multiple instances of a specified file in the <archive>, the N <modifier> can be used to identify which instance of a specified file to delete from the <archive> via the <count> argument, where a <count> value of 1 indicates the first instance of the file in the <archive>. If the N <modifier> is not specified, then the d <operation> will remove the first instance of a specified file to be deleted. If the N <modifier> is used without a <count> argument, then the d <operation> will fail.

  • T - when the T <modifier> is used, the <archive> that is created or modified as a result of the <operation> will be thin. By default, this behavior is disabled. In the absence of the T <modifier>, a newly created archive is always regular, and a modified thin archive will be converted to regular.

m[abi]

Move <files> from one location in the archive> to another. The specified <files> will be moved to the location indicated by the specified <modifier> options. If no <modifier> options are specified, then the specified <files> will be moved to the end of the <archive>. If no <files> are specified, then the <archive> will not be modified.

Operation-Specific Modifiers

  • a - when the a <modifier> is used in combination with the m <operation>, the destination of the file to be moved is indicated as after the member file identified via the <relpos> argument. If a <relpos> argument is not specified, then the new file is placed at the end of the <archive>.

  • b - when the b <modifier> is used in combination with the m <operation>, the destination of the file to be moved is indicated as before the member file identified via the <relpos> argument. If a <relpos> argument is not specified, then the new file is placed at the end of the <archive>.

  • i - the i <modifier> is a synonym for the b <modifier>.

p[v]

Print specified <files> to the standard output stream. If no <files> are specified, the entire archive is printed. The p <operation> does not modify the specified <archive>.

Operation-Specific Modifiers

  • v - print the name of each file in the list of specified <files> in addition to the files themselves.

q[LT]

Append specified <files. to the end of the <archive> without removing duplicate files. If no <files> are specified, then the <archive> is not modified.

The L and T modifiers may come into play when using the q <operation> to append one archive to another:

  • Appending a regular archive to a regular archive will append the archive file. If the L modifier is specified, the members will be appended instead.

  • Appending a regular archive to a thin archive requires the T modifier and will append the archive file. The L modifier is not supported for this use case.

  • Appending a thin archive to a regular archive will append the archive file. If the L modifier is specified, the members will be appended instead.

  • Appending a thin archive to a thin archive will always append its members.

Operation-Specific Modifiers

  • L - when the L <modifier> is used while appending one archive to another, instead of appending the indicated archive, append that archive’s members.

  • T - when the T <modifier> is used, the <archive> that is created or modified as a result of the <operation> will be thin. By default, this behavior is disabled. In the absence of the T <modifier>, a newly created archive is always regular, and a modified thin archive will be converted to regular.

r[abTu]

Replace existing <files> or insert them at the end of the <archive> if they do not exist. If no <files> are specified, the <archive> is not modified.

Operation-Specific Modifiers

  • a - when the a <modifier> is used in combination with the r <operation>, the destination of the new file is indicated as after the member file identified via the <relpos> argument. If a <relpos> argument is not specified, then the new file is placed at the end of the <archive>.

  • b - when the b <modifier> is used in combination with the r <operation>, the destination of the new file is indicated as before the member file identified via the <relpos> argument. If a <relpos> argument is not specified, then the new file is placed at the end of the <archive>.

  • T - when the T <modifier> is used, the <archive> that is created or modified as a result of the <operation> will be thin. By default, this behavior is disabled. In the absence of the T <modifier>, a newly created archive is always regular, and a modified thin archive will be converted to regular.

t[vO]

Print the table of contents for the specified <archive> file. Without any modifiers, this operation will print the names of the <archive> members to stdout. If any <files> are specified, the operation only applies for those files that are present in the <archive>. If no <files> are specified, then tiarmar will print the table of contents for the entire <archive>.

Operation-Specific Modifiers

  • v - with this modifier applied to the t <operation>, tiarmar will print additional information about the members of the <archive> that the operation applies to (e.g. file type, file permissions, file size, and timestamp).

  • O - with this modifier applied to the t “<operation>, tiarmar will print <archive> member offsets in addition to the names of the <files>.

x[oP]

Extract <archive> members back to <files>. This operation retrieves the specified <files> from an existing <archive> and writes the contents of those files to the operating system’s file system. If no <files> are specified, then the entire <archive> will be extracted.

Operation-Specific Modifiers

  • o - when extracting <files>, use the timestamp of the specified <files> as they exist in the <archive>. Without this modifier, an extracted file will be marked with a timestamp corresponding to the time of extraction.

9.1.3. Generic Modifiers

The following <modifier> arguments can be applied to any operation:

c

Normally, tiarmar will print a warning message indicating that an <archive> is being created if it doesn’t already exist. Use of the c modifier will suppress this warning.

D

Use zero for timestamps and UIDs/GIDs. This is enabled by default.

P

Use full paths when matching <archive> member names rather than just the file name.

s

Request that a symbol table (or archive index) be added to the <archive>. The symbol table will contain all externally visible functions and global variables defined by all the members of the <archive>. This behavior is enabled by default. The s generic modifier can also be used as an <operation> for an archive that doesn’t already contain a symbol table.

S

Disable generation of the <archive> symbol table.

u

Only update <archive> members with <files> that have more recent timestamps.

U

Use actual timestamps and UIDs/GIDs. This overrides the default D modifier.

9.1.4. Other Options

-h, --help

Print a summary of tiarmar usage information to stdout.

V, --version

Display the version of the tiarmar executable.

@<file>

Read command-line options and commands from specified <file>.

9.1.5. Examples

  • Creating an object file library:

    Assuming you have the following object files available in your current working directory: sin.o, cos.o, and tan.o, you can create an object file library containing those files with the following command:

%> tiarmar rc functions.lib sine.o cos.o tan.o

The r option instructs the archiver to replace or insert the specified object files into the specified archive file. The c option will prevent the archiver from printing a warning when creating the archive file.

  • Listing the contents of a library:

You can then list the contents of functions.lib using the following command:

%> tiarmar tv functions.lib
rw-r--r-- 0/0   1648 Dec 31 18:00 1969 sin.o
rw-r--r-- 0/0   1732 Dec 31 18:00 1969 cos.o
rw-r--r-- 0/0   1716 Dec 31 18:00 1969 tan.o

Without the v (verbose) option, the above command will simply list the names of the object files contained in functions.lib.

  • Adding files to a library:

Assuming you have additional object files in your current working directory that you want to add to the functions.lib object file library, you can do this with the following command:

%> tiarmar r functions.lib asin.o acos.o atan.o

Now verify the updated contents of functions.lib:

%> tiarmar t functions.lib
sin.o
cos.o
tan.o
asin.o
acos.o
atan.o

  • Replacing an existing library member:

Suppose you’ve made some improvements to the sin.c file that was used as the source for the compiler generated sin.o file. You can then re-compile the updated source file and replace the previous version of sin.o in the object file library with the new one:

%> tiarmclang -mcpu=cortex-m0 -c sin.c
%> tiarmar r functions.lib sin.o

9.1.6. Exit Status

If tiarmar execution is successful, it will exit with a zero return code. If an error occurs during execution, tiarmar will exit with a non-zero return code.