Creating an ELF descriptor

Producer and consumer operations use ELF descriptors to access ELF object files. The following diagram shows how an application uses the libelf library to create an ELF descriptor:

Figure 1. Creation of an ELF descriptor

An overview of the process to create an ELF descriptor using the libelf library.

Table 1 describes how producer or consumer operations create an ELF descriptor with calls to libelf operations.

Table 1. Stages to create an ELF descriptor with calls to libelf operations
Stage	Description
Version check	Since `libelf` is packaged as a DLL, this step will check the version. It is good practice to validate that the correct version of the DLL exists. For example: #define _UNIX03_SOURCE #include <dlfcn.h> /* dlopen,dlsym,dlclose / #include "libelf.h" void cdadll; unsigned int (version_chk)(unsigned int); unsigned int dll_version; #ifdef _LP64 #define __CDA_ELF "CDAEQED" #else #define __CDA_ELF "CDAEED" #endif #if LIBELF_IS_DLL cdadll = dlopen(__CDA_ELF, RTLD_LOCAL \| RTLD_LAZY); if (cdadll == NULL) { / elf/dwarf DLL not found / } version_chk = (unsigned int ()(unsigned int)) dlsym(cdadll, "elf_dll_version"); if (version_chk == NULL) { /* Version API not found, should NEVER happen / } dll_version = version_chk (LIBELF_DLL_VERSION); if (dll_version != 0) { / Incompatible DLL version / } dlclose(cdadll); #endif It is mandatory to perform a verification of the ELF version before using the other functions offered by libelf. For example: #include <dll.h> { / Verify existence of libelf DLL / dllhandle dll_handle = dllload ("CDAEED"); if (dll_handle == NULL) { /* DLL not found, verify CEE.SCEERUN2 is in your STEPLIB / } / Verify that the current version of the ELF DLL meets or exceeds the minimum required version / if (elf_dll_version (LIBELF_DLL_VERSION) != 0) { / DLL version mismatch. - verify that "libelf.h" comes from: "/usr/lpp/cbclib/include/libelf" - verify CEE.SCEERUN2 is the first dataset on your STEPLIB - verify you have the latest service level of CDA libraries */ } }
Version check (continued)	It is mandatory to perform a verification of the ELF version before using the other operations offered by `libelf`. For example: `/* Verify that the current version of the ELF DLL meets or exceeds the minimum required version / elf_version (EV_NONE); if (elf_version(EV_CURRENT) == EV_NONE) { / libelf is out of date */ }`
Open a file	The producer or consumer operations create a file handle for the ELF object file. This file handle is used to create an ELF descriptor. Consult z/OS® XL C/C++ Run-Time Library Reference for more information on opening files and creating file handles.
Initialize ELF descriptor	An ELF descriptor is required before you can call any other `libelf` operations. The file handle is used to initialize `libelf` and create an ELF descriptor for the ELF object file. The `libelf` operation that will create the ELF descriptor is determined by the operation that creates the file handle. For example, if the `fopen` operation creates the file handle, the `elf_begin_b` operation is used. The following code demonstrates how to use the file pointer obtained from `fopen` to create the ELF descriptor: `Elf* elf; /* ELF descriptor / FILE fp; /* File pointer / / Open test.dbg for reading / fp = fopen ("test.dbg", "rb"); / Create ELF descriptor for reading */ elf = elf_begin_b (fp, ELF_C_READ, NULL);`
Operate on the descriptor	After the ELF descriptor is initialized, you can call any `libelf` operations. For example, `elf_getscn` returns an ELF section, and `elf_kind` describes that section.
Terminate ELF descriptor	When the debugging information is no longer needed, the descriptor is terminated by the `elf_end` operation. Note: If you are using the `libdwarf` library, you must terminate its objects before you terminate the ELF descriptor. Close the file handle after the ELF descriptor is terminated.