How to Read Symbol Tables Using the nm Command in Linux

When you are debugging a complex C or C++ application in Linux, attempting to execute a compiled binary file will occasionally result in a catastrophic “Undefined Reference” or “Symbol Not Found” error. Because compiled binary files are illegible to the human eye, you cannot simply open them in a text editor to figure out which specific function or variable is missing. To mathematically extract and translate the hidden internal architecture of a compiled object file, you must use the nm command.

How the nm Command Works

When a developer compiles source code (like a .c file) into an object file (like a .o file) or a shared library (like a .so file), the compiler generates a “Symbol Table.” This table is a highly structured index containing the exact names and memory locations of every single function, variable, and class used in the program. The nm command’s sole purpose is to rip this Symbol Table out of the binary file and print it to your terminal screen.

To use the command, simply type it followed by the path to the compiled file:

nm my_program.o

The system will instantly output a massive, highly dense list of data that looks something like this:

0000000000000000 T main
                 U printf
0000000000000024 T calculate_sum
0000000000000000 D global_variable

Understanding the Symbol Output

To successfully debug a linking error, you must understand the highly specific, single-letter codes located in the center column of the output. These letters define exactly what the symbol is and where it lives.

• T (Text section): This indicates a function that is fully defined and exists directly inside this specific file (e.g., the main function or the calculate_sum function).
• D (Data section): This indicates an initialized global variable.
• U (Undefined): This is the most critical code for debugging. An uppercase ‘U’ indicates that the program is trying to call a function (like printf), but the actual code for that function does not exist inside this file. The linker will have to search external libraries to find it.

Diagnosing Missing Dependencies

If your program is crashing with an “Undefined Reference to ‘calculate_sum'” error, you can use the nm command to aggressively scan your compiled libraries to figure out why the linker cannot find it.

You can pipe the output directly into a grep command to filter the massive list:

nm my_math_library.so | grep calculate_sum

If the output shows a U next to calculate_sum, or if it returns absolutely nothing, you have instantly found the root cause of the crash: the library you are linking against does not actually contain the required function.