Enable Debugging with Debug Information

To debug applications and libraries, you must obtain debugging information.

Debug information overview
Copy link

Debugging information links binary code to source code so you can inspect variables and execution flow. The GNU Compiler Collection (GCC) generates this data in the Debug With Arbitrary Record Format (DWARF) within ELF files, and the GNU Debugger (GDB) uses it to analyze program behavior.

Red Hat Enterprise Linux uses the ELF format for executable binaries, shared libraries, or debuginfo files. Within these ELF files, the DWARF format is used to hold the debug information.

To display DWARF information stored within an ELF file, run the readelf -w file command.

Important

STABS (Symbol Table format) is an older, less capable debugging format, occasionally used with UNIX. For debugging on RHEL, use the DWARF format instead. GCC and GDB support STABS on a best-effort basis only. Tools such as Valgrind and elfutils do not support STABS.

Enable debug of C and C++ applications with the GCC
Copy link

To debug C and C++ applications effectively, generate debugging information during compilation. Use GCC’s -g option to create this data. Debuggers use this data to map executable code to source lines for inspecting variables and logic.

Before you begin
Copy link

  • You have the gcc package installed.

Procedure
Copy link

  1. Compile and link your code with the -g option to generate debugging information: 
    $ gcc ... -g ...
  2. Optional: Set the optimization level to -Og: 
    $ gcc ... -g -Og ...

    Compiler optimizations can make executable code hard to relate to the source code. The -Og option optimizes the code without interfering with debugging. However, be aware that changing optimization levels can alter the program’s behavior.

  3. Optional: Use -g for moderate debugging information, or -g3 to include macro definitions: 
    $ gcc ... -g3 ...

Results
Copy link

  • Test the code by using the -fcompare-debug GCC option: 
    $ gcc -fcompare-debug ...

    This option tests code compiled with and without debug information. If the resulting binaries are identical, the executable code is not affected by debugging options. By using the -fcompare-debug option significantly increases compilation time.

Debuginfo and debugsource packages
Copy link

The debuginfo and debugsource packages contain debugging information and source code for programs and libraries. To debug Red Hat Enterprise Linux applications, install these packages from additional repositories.

Debugging information package types
Debuginfo packages: The debuginfo packages provide debugging information needed to provide human-readable names for binary code features. These packages contain .debug files, which contain DWARF debugging information. These files are installed to the /usr/lib/debug directory.

Debugsource packages: The debugsource packages contain the source files used for compiling the binary code. With both debuginfo and debugsource packages installed, debuggers such as GDB or LLDB can relate the execution of binary code to the source code. The source code files are installed to the /usr/src/debug directory.

Get debuginfo packages for an application or library by using GDB
Copy link

To obtain the necessary debuginfo packages for troubleshooting installed applications or libraries, use the GNU Debugger (GDB). It automatically detects missing symbols and identifies the specific packages needed. Follow GDB’s recommendations to install them for full debugging capabilities.

Before you begin
Copy link

Procedure
Copy link

  1. Start GDB attached to the application or library you want to debug. GDB automatically recognizes missing debugging information and suggests a command to run. 
    $ gdb -q /bin/ls
     
    Reading symbols from /bin/ls...Reading symbols from .gnu_debugdata for /usr/bin/ls...(no debugging symbols found)...done.
(no debugging symbols found)...done.
Missing separate debuginfos, use: dnf debuginfo-install coreutils-9.5-6.el10.x86_64
(gdb)
  2. Exit GDB: type q and confirm with Enter. 
    (gdb) q
  3. Run the command suggested by GDB to install the required debuginfo packages: 
    # dnf debuginfo-install coreutils-9.5-6.el10.x86_64

    The dnf package management tool provides a summary of the changes, asks for confirmation and once you confirm, downloads and installs all the necessary files.

  4. In case GDB is not able to suggest the debuginfo package, follow the procedure described in Getting debuginfo packages for an application or library manually.

Get debuginfo packages for an application or library manually
Copy link

To manually determine which debuginfo packages you need to install, locate the executable file and find the package that installs it.

Before you begin
Copy link

  • The application or library must be installed on the system.
  • The application or library was installed from a package.
  • The debuginfo-install tool must be available on the system. For details, see Installing tools for debugging applications.
  • Channels providing the debuginfo packages must be configured and enabled on the system.
  • If you use the locate command in this procedure, the mlocate package must be installed and its database must be current. As root, run dnf install mlocate if needed, then run updatedb.

About this task
Copy link

Prefer using GDB to determine the packages for installation when that is an option. For details, see Getting debuginfo packages for an application or library using GDB.

Use this manual procedure only if GDB cannot suggest which package to install.

Procedure
Copy link

  1. Find the executable file of the application or library.
    1. Use the which command to find the application file. 
      $ which less
       
      /usr/bin/less
    2. Use the locate command to find the library file. 
      $ locate libz | grep so
       
      /usr/lib64/libz.so.1
/usr/lib64/libz.so.1.2.11

      If your debugging started from error messages, choose the path where the library file name includes the same numbers as the messages. If you are unsure, continue with the path where the file name has no extra numbers.

  2. Search for a name and version of the package that provided the file: 
    $ rpm -qf /usr/lib64/libz.so.1.3.1.zlib-ng
     
    zlib-ng-compat-2.2.3-1.el10.x86_64

    The output provides details for the installed package in the name:epoch-version.release.architecture format.

    Important

    If this step does not produce any results, it is not possible to determine which package provided the binary file. There are several possible cases:

    • The file is installed from a package which is not known to package management tools in their current configuration.
    • The file is installed from a locally downloaded and manually installed package. Determining a suitable debuginfo package automatically is impossible in that case.
    • Your package management tools are misconfigured.
    • The file is not installed from any package. In such a case, no corresponding debuginfo package exists.

    Because further steps depend on this one, you must resolve this situation or stop this procedure. Describing the exact troubleshooting steps is beyond the scope of this procedure.
  3. Install the debuginfo packages using the dnf debuginfo-install utility. In the command, use the package name and other details you determined during the previous step: 
    # dnf debuginfo-install zlib-ng-compat-2.2.3-1.el10.x86_64