12.1. tiarmnm - Name Utility¶

The tiarmnm utility can be used to print a list of the names of symbols from tiarmclang compiler-generated bitcode files, object files, object file libraries, or static executables.

12.1.1. Usage¶

tiarmnm [options] [input files]

options - affect how the tiarmnm utility behaves in processing any specified input files.
input files - a list of one or more tiarmclang compiler-generated bitcode files, object files, object file libraries, or static executables. If there is no input files list specified, tiarmnm will attempt to read a.out as an input file. If - is specified in place of the input files argument, then tiarmnm will expect a user-specified input file from stdin.

12.1.2. Output Format¶

tiarmnm will output a list of symbols including the symbol name along with some simple information about its provenance. tiarmnm’s default output format is the traditional BSD nm output format. Each such output record consists of an (optional) 8-digit hexadecimal address, followed by a type code character to indicate the symbol’s kind, followed by a name, for each symbol. One record is printed per line; fields are separated by spaces. When the address field is omitted, it is replaced by 8 spaces.

Because compiler-generated bitcode files typically contain objects that are not considered to have addresses until they are linked into an executable image or dynamically compiled “just-in-time”, tiarmnm does not print an address for any symbol in an bitcode file, even symbols which are defined in the bitcode file.

Symbol Kind Annotations

As mentioned above, each symbol output record is annotated with a single character that indicates a symbol’s type or kind.

The supported symbol kind characters are listed in the table below. Both lower and upper case versions of the a given character are interpreted with the same meaning with respect to a given symbol’s kind, but lower-case characters are used for local symbols and upper-case characters are used for global symbols.

Kind Characters	Meaning
a,A	Absolute symbol.
b,B	Uninitialized data (.bss) symbol.
C	Common symbol. Multiple definitions link together into one definition.
d,D	Writable data object.
n	Local symbol from unallocated section.
N	Debug symbol or global symbol from unallocated section.
r,R	Read-only data object.
t,T	Code (.text) object.
u	GNU unique symbol.
U	Named object is undefined in this file.
v	Undefined weak object. It is not a link failure if the object is not defined.
V	Defined weak object symbol. This definition will only be used if no regular definitions exist in a link. If multiple weak definitions and no regular definitions exist, then one of the weak definitions will be used.
?	Something unrecognizable.

12.1.3. Options¶

-B¶: Use BSD output format. This is an alias for the --format=bsd option.

--debug-syms, -a¶: Show all symbols, including those that are usually suppressed.

--defined-only, -U¶: Print only symbols defined in this file.

--demangle, -C¶: Demangle symbol names.

--dynamic, -D¶: Display dynamic symbols instead of normal symbols.

--extern-only, -g¶: Print only symbols whose definitions are externally accessible.

--format=<format>, -f=<format>¶

Select an output <format>. Supported values for the <format> argument include:

sysv
posix
darwin
bsd (default)

--help, -h¶: Print a summary of the command-line options and their meanings.

--help-list¶: Print an uncategorized summary of command-line options and their meanings.

--just-symbol-name, -j¶: Print only the symbol names.

-m¶: Use darwin output format. This is an alias for the --format=darwin option.

--no-demangle¶: Don’t demangle symbol names. This option is enabled by default.

--no-llvm-bc¶: Disable the bitcode reader.

--no-sort, -p¶: Show symbols in the order encountered.

--no-weak, -W¶: Don’t print weak symbols.

--numeric-sort, -n, -v¶: Sort symbols by address.

--portability, -P¶: Use POSIX.2 output format. This is an alias for the --format=posix option.

--print-armap, -M¶: Print the archive symbol table, in addition to the symbols.

--print-file-name, -A, -o¶: Precede each symbol record with the file that it came from.

--print-size, -S¶: Show symbol size as well as address.

--radix=<radix>, -t=<radix>¶

Specify the <radix> of the symbol addresses. Values accepted include:

d - decimal
x - hexadecimal
o - octal

--reverse-sort, -r¶: Sort symbols in reverse order.

--size-sort¶: Sort symbols by size.

--special-syms¶: Do not filter special symbols from the output.

--undefined-only, -u¶: Print only undefined symbols.

--version¶: Display the version of the tiarmnm executable. This option will cause tiarmnm to immediately return without reading any specified input files to print the symbols in those files.

--without-aliases¶: Exclude aliases from the output.

@<file>¶: Read command-line options from specified <file>.

12.1.4. Examples¶

Simple C++ “Hello World” example:

Consider the follwing source file (hello.cpp):

#include <iostream>
using namespace std;

int main ()
{
  int i;
  cout << "Please enter an integer value: ";
  cin >> i;
  cout << "The value you entered is " << i;
  cout << " and its double is " << i*2 << ".\n";
  return 0;
}

If we then compile hello.cpp to an object file:

%> tiarmclang -mcpu=cortex-m0 -c hello.cpp

We can output the list of symbols in the symbol table for hello.o:

%> tiarmnm hello.o
00000000 W _ZNKSt3__112basic_stringIcNS_11char_traitsIcEENS_9allocatorIcEEE13__get_pointerEv
00000000 W _ZNKSt3__112basic_stringIcNS_11char_traitsIcEENS_9allocatorIcEEE18__get_long_pointerEv
...
00000000 W _ZNSt3__19use_facetINS_5ctypeIcEEEERKT_RKNS_6localeE
00000000 W _ZNSt3__1lsINS_11char_traitsIcEEEERNS_13basic_ostreamIcT_EES6_PKc
00000000 T main
         U strlen

We could also filter the tiarmnm output to only include symbols that are not defined in hello.o:

%> tiarmnm -u hello.o
         U _ZNKSt3__16locale9use_facetERNS0_2idE
         U _ZNKSt3__18ios_base6getlocEv
         U _ZNSt3__112basic_stringIcNS_11char_traitsIcEENS_9allocatorIcEEE6__initEjc
         U _ZNSt3__112basic_stringIcNS_11char_traitsIcEENS_9allocatorIcEEED1Ev
         U _ZNSt3__113basic_istreamIcNS_11char_traitsIcEEErsERi
         U _ZNSt3__113basic_ostreamIcNS_11char_traitsIcEEE6sentryC1ERS3_
         U _ZNSt3__113basic_ostreamIcNS_11char_traitsIcEEE6sentryD1Ev
         U _ZNSt3__113basic_ostreamIcNS_11char_traitsIcEEElsEi
         U _ZNSt3__13cinE
         U _ZNSt3__14coutE
         U _ZNSt3__15ctypeIcE2idE
         U _ZNSt3__16localeD1Ev
         U _ZNSt3__18ios_base5clearEj
         U strlen

Now if we build a static executable for hello.cpp:

%> tiarmclang -mcpu=cortex-m0 hello.cpp -o hello.out -Wl,-llnk.cmd,-mhello.map

We can now see addresses assigned for some of the symbols that were referenced, but not defined in hello.o:

%> tiarmnm hello.out
...
00026e54 T _ZNKSt3__16locale9use_facetERNS0_2idE
...
00028e1c T _ZNKSt3__18ios_base6getlocEv
...
00027198 W _ZNSt3__112basic_stringIcNS_11char_traitsIcEENS_9allocatorIcEEE6__initEjc
...
2000b024 B _ZNSt3__13cinE
...
2000b17c B _ZNSt3__14coutE
...
00028b5a T strlen

Piping output of tiarmnm as input to tiarmdem:

Consider the following source file (test.cpp):

int g_my_num;
namespace NS { int ns_my_num = 2; }
int f() { return g_my_num + NS::ns_my_num; }
int main() { return f(); }

If the above test.cpp is compiled:

tiarmclang -mcpu=cortex-m4 -c test.cpp

We can then use the tiarmnm utility to write out the symbol names in test.o:

%> tiarmnm test.o
00000000 T _Z1fv
00000000 D _ZN2NS9ns_my_numE
00000000 B g_my_num
00000000 T main

and we could pass the output of tiarmnm to tiarmdem to demangle the mangled names that are present in the tiarmnm output:

%> tiarmnm test.o | tiarmdem
00000000 T f()
00000000 D NS::ns_my_num
00000000 B g_my_num
00000000 T main

Incidentally, we could get the same result without using tiarmdem by just using tiarmnm’s --demangle or -C option to instruct tiarmnm to demangle the symbol names that it prints out:

%> tiarmnm --demangle test.o
00000000 T f()
00000000 D NS::ns_my_num
00000000 B g_my_num
00000000 T main

12.1.5. Exit Status¶

The tiarmnm utility should exit with a return code of zero.