ddpi_elf_create operation

The ddpi_elf_create operation creates a Ddpi_Elf object to enable access to debugging data in an ELF object file.

Description

Note: The Ddpi_Elf objects can also be created by the ddpi_module_extract _C_CPP_information operation. This is the preferred operation if the loaded application-executable module was compiled with the z/OS® XL C/C++ compiler. The operation creates and lists the Ddpi_Elf objects associated with the given Ddpi_Module object.

Prototype

int ddpi_elf_create(
    Ddpi_Access         access,
    Elf*                elf,
    char*               elf_filename,
    Ddpi_Elf_Source     source,
    Ddpi_Elf_Source_Type
                        source_type,
    Dwarf_Addr          ppa2_addr,
    Dwarf_Addr*         func_addr_list,
    Dwarf_Addr*         ppa1_addr_list,
    int                 ppa1_elements,
    Dwarf_Addr          csect_low_addr,
    Dwarf_Addr          csect_high_addr,
    unsigned char       md5_sig[16],
    int                 user_area_len,
    Ddpi_Elf*           ret_elf,
    Ddpi_Error*         error);

Parameters

access: Input. This provides access to libddpi.
elf: Input. This provides the ELF object file descriptor.
elf_filename: Input. This accepts the ELF object file name.
source: Input. This enables the source pointer to be given to elf_begin.
source_type: Input. This accepts the source_type.
ppa2_addr: Input. This accepts the PPA2 address.
func_addr_list: Input. This accepts a list of function address in the same order as the ppa1_addr_list. The value is copied, and the user may free their version.
ppa1_addr_list: Input. This accepts a list of PPA1 addresses. The value is copied, and the user may free their version.
ppa1_elements: Input. This accepts the number of elements in PPA1 list.
csect_low_addr: Input. This accepts the lowest address in the CSECT (the first byte of the object). Specify (Dwarf_Addr)-1 for an unknown address. All other addresses will be taken as valid.
csect_high_addr: Input. This accepts the highest address in the CSECT (the last byte of the object). Specify (Dwarf_Addr)-1 for an unknown address. All other addresses will be taken as valid.
Note: csect_low_addr and csect_high_addr are not guaranteed to enclose all control blocks. They are guaranteed to enclose all executable code for the given compilation unit (CU) if they are set to a value that is not -1.
md5_sig[16]: Input. This accepts and copies the MD5 signature.
user_area_len: Input. This accepts the user area length.
ret_elf: Output. This returns the Ddpi_Elf object.
error: See The libddpi error parameter.

Return values

DW_DLV_OK

Returned upon successful retrieval of the ELF object.

DW_DLV_NO_ENTRY

Returned if the user-area length is zero.

DW_DLV_ERROR

This value is returned if:

user_area_len is less than zero
An error occurs during memory allocation.