addr2line command linux

Linux uses the addr2line command to translate hexadecimal addresses in a executable into file names and line numbers. These executable computer instructions are shown together with their corresponding memory locations (address). Given an address in an executable or an offset in a section of a relocatable object, it uses the debugging information to figure out which file name and line number, in the source code, are associated with it.

addr2line has two modes of operation;

1. Hexadecimal addresses are specified on the command line as argument,
2. Read hexadecimal addresses from standard input (stdin).

The format of the output is FILENAME:LINENO. By default each input address generates one line of output. If the address is not found then addr2line will print ??:0 as output. If the file name or function name can not be determined, addr2line will print two question marks (??) in their place. If the line number can not be determined, addr2line will print 0.

Install addr2line command in Linux

Debian - apt install binutils
Alpine - apk add binutils
Arch Linux - pacman -S binutils
CentOS - yum install binutils
Fedora - dnf install binutils
OS X - brew install binutils
Raspbian - apt-get install binutils
Docker - docker run cmd.cat/addr2line addr2line

addr2line command syntax:

       addr2line [-a|--addresses]
                 [-b bfdname|--target=bfdname]
                 [-C|--demangle[=style]]
                 [-r|--no-recurse-limit]
                 [-R|--recurse-limit]
                 [-e filename|--exe=filename]
                 [-f|--functions] [-s|--basename]
                 [-i|--inlines]
                 [-p|--pretty-print]
                 [-j|--section=name]
                 [-H|--help] [-V|--version]
                 [addr addr ...]

addr2line command options

1. Set the input file name (default is a.out).

The -e and its long form option specifies the executable or relocatable object to use. file a.out is used by default. The -j option specifies the part of the relocatable object to use.

$ addr2line -e path/to/executable_file [other_options] address
$ addr2line --exe=path/to/executable_file [other_options] address

2. Display the input addresses.

When -a option is used, a line with the input address is displayed before the function name, file and line number information. The address is printed with a 0x prefix to easily identify it.

$ addr2line -a [other_options] address
$ addr2line -addresses [other_options] address

3. Display the function names.

The -f option is used to display a line with the FUNCTIONNAME. This is the name of the function containing the address.

$ addr2line -f [other_options] address
$ addr2line -functions [other_options] address

4. Unwind inlined functions

The -i option is used with the code at the given address is present there because of inlining by the compiler then additional lines are displayed afterwards. If the -f option is used, one or two extra lines are shown for each inline function.
If the address belongs to a function that was inlined, the source information for all enclosing scopes back to the first non-inlined function will also be printed.

$ addr2line -i [other_options] address
$ addr2line –inlines [other_options] address

5. Demangle function names

Decode (demangle) low-level symbol names into user-level names. This makes C++ function names legible and removes any system-prefixed beginning underscore. Various compilers have various mangling techniques. You can select a suitable demangling style for your compiler using the optional demangling style argument.

$ addr2line -C [other_options] address
$ addr2line --demangle=style [other_options] address

6. Enable or disable a limit on recursion whilst demangling.

The -r/--recurse-limit/--recursion-limit and -R/--no-recurse-limit/--no-recursion-limit options allow us to enable or disable a limit on the amount of recursion performed whilst demangling strings. It is possible to build strings whose decoding will use up all of the stack space on the host machine due to the name mangling formats' infinite level of recursion, resulting in a memory fault. By limiting recursion to 2048 levels of nesting, the limit aims to stop this from occurring.

Enable recursion (-r, --recurse-limit, --recursion-limit)

$ addr2line -C -r [other_options] address

Disable recursion (-R, --no-recurse-limit, --no-recursion-limit)

$ addr2line -C -R [other_options] address

Example uses of addr2line command:

To use addr2line, you must provide the address you want to convert and the name of the executable file or the shared object file that contains the address. For example, to convert the address 0x40053d in the program executable file, you would use the following command:

$ addr2line -e program 0x40053d

This would output the file name and line number where the address is located in the program executable file. For example:

/path/to/program/src/main.c:123

You can also use addr2line to convert multiple addresses at once by providing a list of addresses separated by spaces. For example:

$ addr2line -e program 0x40053d 0x401287 0x4012a3

This would output the file name and line number for each of the addresses provided.

Conclusion

In this article, we explored addr2line command which is a tool included in binutils (binary utilities) package. Addresses from binary files are converted by addr2line into file names and line numbers. It is beneficial while debugging code. It uses the debugging information to determine whether file name and line number in the source code are related to a certain address in an executable or offset in a particular portion of a relocatable object.