Go to main content
Oracle® Developer Studio 12.5: Debugging a Program with dbx

Exit Print View

Updated: June 2016

Using a Separate Debug File

dbx enables you to use options in the objcopy command on Linux platforms and the gobjcopy command on Oracle Solaris platforms to copy the debugging information from an executable to a separate debug file, strip that information from the executable, and create a link between these two files.

    dbx searches for the separate debug file in the following order and reads the debugging information from the first file it finds:

  1. The directory that contains the executable file.

  2. A subdirectory named debug in the directory that contains the executable file.

  3. A subdirectory of the global debug file directory, which you can view or change if the dbxenv variable debug_file_directory is set to the path name of the directory. The default value of the environment variable is /usr/lib/debug.

For example, the following procedure describes how to create a separate debug file for executable a.out.

How to Create a Separate Debug File

  1. Create a separate debug file named a.out.debug containing the debugging information.
    objcopy --only-keep-debug a.out a.out.debug
  2. Strip the debugging information from a.out.
    objcopy --strip-debug a.out
  3. Establish the link between the two files.
    objcopy --add-gnu-debuglink=a.out.debug a.out

    On Oracle Solaris platforms, use the gobjcopy command. On Linux platforms, use the objcopy command.

    On a Linux platform, you can use the command objcopy –help to find out whether the –add-gnu-debuglink option is supported on the platform. You can replace the –only-keep-debug option of the objcopy command with the command cp a.out a.out.debug to make a.out.debug a fully executable file.

Ancillary Files (Oracle Solaris Only)

By default, load objects contain both allocable and non-allocable sections. Allocable sections are the sections that contain executable code and the data needed by that code at runtime. Non-allocable sections contain supplemental information that is not required to execute a file at runtime. These sections support the operation of debuggers and other observability tools. The non-allocable sections in an object are not loaded into memory at runtime by the operating system, and so, they have no impact on memory use or other aspects of runtime performance no matter their size.

For convenience, both allocable and non-allocable sections are normally maintained in the same file. However, there are situations in which it can be useful to separate these sections. Specifically, to support fine grained debugging of highly optimized code requires considerable debug data. In modern systems, the debugging data can easily be larger than the code it describes. The size of a 32-bit object is limited to 4GB. In very large 32-bit objects, the debug data can cause this limit to be exceeded and prevent the creation of the object.

Traditionally, load objects have been stripped of non-allocable sections in order to address these issues. Stripping is effective, but destroys data that might be needed later. The Oracle Solaris link-editor can instead write non-allocable sections to an ancillary file. This feature is enabled via the –z ancillary command line option.

% ld ... –z ancillary[=outfile] ...
/* Your file is separated into a.out and b.out, where
a.out: ELF 32-bit LSB executable 80386 Version 1 [FPU], dynamically linked, not stripped, ancillary object b.out
b.out: ELF 32-bit LSB ancillary 80386 Version 1, primary object a.out */

By default, the ancillary file is given the same name as the primary output object, with a .anc file extension. However, a different name can be provided by providing an outfile value to the –z ancillary option.

Note -  The ELF definition of ancillary files provides for a single primary file, and an arbitrary number of ancillary file. At this time, the Oracle Solaris link-editor only produces a single ancillary file containing all non-allocable sections. This might change in the future.

When –z ancillary is specified, the link-editor does the following.

  • All allocable sections are written to the primary file. In addition, all non-allocable sections containing one or more input sections that have the SHF_SUNW_PRIMARY section header flag set are written to the primary file.

  • All remaining non-allocable sections are written to the ancillary file.

  • Both output files receive full identical copies of the following well known non-allocable sections:


    Section name string table.


    The full non-dynamic symbol table.


    The symbol table extended index section associated with .symtab.


    The non-dynamic string table associated with .symtab.


    Contains the information required to identify the primary object, and all of the ancillary objects, and to identify the object being examined.

  • The primary file and all ancillary files contain the same array of sections headers. Each section has the same section index in every file.

  • Although the primary and ancillary files all define the same section headers, the data for most sections will be written to a single file as described above. If the data for a section is not present in a given file, the SHF_SUNW_ABSENT section header flag will be set, and sh_size field will be 0.

This organization makes it possible to acquire a full list of section headers, a complete symbol table, and a complete list of the primary and ancillary files, all from examining a single file.

dbx can then use these ancillary files just as dbx uses a separate debug file, by looking for ancillary files in your executable. Use the –z ancillary option when compiling as follows:

%CC -g -z ancillary=a.out demo.cpp //"a.out" contains the ancillary object

The primary load object, and all associated ancillary files, contain a .SUNW_ancillary section that allows all the load objects to be identified and related together.

For more information, see Chapter 2, Link-Editor in Oracle Solaris 11.3 Linkers and Libraries Guide.

Note -  This feature is currently only available for Oracle Solaris 11.1.