Writing DWARF data to the ELF object file

Once an ELF descriptor has been created, a producer application can use it to write DWARF debugging information to the ELF object file. This section discusses how a producer application writes to an ELF object file using the libelf and libdwarf libraries.

The following diagram shows an overview of the process.

Figure 1. Write to an ELF object file

An overview of the process to write to an ELF object file using the libelf and libdwarf libraries.

The following stages show how a producer application writes to an ELF object file with calls to libelf and libdwarf operations.

Stage	Description
Create an ELF descriptor	Create an ELF descriptor for writing. This descriptor will be used to write DWARF debugging information into the ELF object file. For more information, see Creating an ELF descriptor.
Initialize a `libdwarf` object	Initialize the `Dwarf_P_Debug` producer object. The object is initialized using the ELF descriptor. An ELF header (`ehdr`) is then created and used to complete the initialization. The following code demonstrates how to initialize the DWARF producer object: `Dwarf_P_Debug dbg; /* Producer DWARF object / / Initialize libdwarf producer instance / flag = DW_DLC_WRITE \| DW_DLC_SIZE_32 \| DW_DLC_ISA_ELF_HDR \| DW_DLC_STREAM_RELOCATIONS; dbg = dwarf_producer_init_b( flag, / callback function for creating ELF section/ section_creation_func, / error handling callback function/ error_handling_func, / arguments to be passed into error_handling_func/ "error arguments", &dwarf_error );` Note: The `ehdr` is extracted from the descriptor. An update to the header will update the descriptor. `/ Create the ELF header / ehdr = elf32_newehdr(elf); / Initialize the ELF header */ ehdr->e_type = ET_REL; ehdr->e_machine = EM_S390; ehdr->e_version = EV_CURRENT; dwarf_producer_target(dbg, elf, &dwarf_error);`
Use `libdwarf` APIs	`libdwarf` producer operations are called to add DWARF debugging information to the ELF object file. For example, `dwarf_add_line_entry` will add one line-number statement to the line number program matrix. `dwarf_new_die` will create a new DIE with a given DIE tag.
Transform DWARF data	`dwarf_transform_to_disk_form` must be called to format the DWARF debugging information before it can be written to the file. That is, the debugging information in the `Dwarf_P_Debug` object must conform to the actual binary representation of the ELF object file.
Write the `libdwarf` object	The data is written to the ELF object file by calling `dwarf_producer_write_elf`. `libdwarf` interacts with `libelf` to write all the gathered debug sections to the ELF object file that is managed by the ELF descriptor.
Terminate the `libdwarf` object	`dwarf_producer_finish` is called to terminate the `Dwarf_P_Debug` object.
Terminate the ELF descriptor	The ELF descriptor is terminated with `elf_end`.