HP-UX Reference (11i v1 05/09) - 3 Library Functions A-M (vol 6)

e
elf_getdata(3E) elf_getdata(3E)
NAME
elf_getdata, elf_newdata, elf_rawdata - get section data
SYNOPSIS
cc [flag... ] file...
-lelf [library] ...
#include <libelf.h>
Elf_Data *elf_getdata(Elf_Scn *scn, Elf_Data *data);
Elf_Data *elf_newdata(Elf_Scn *scn);
Elf_Data *elf_rawdata(Elf_Scn *scn, Elf_Data *data);
DESCRIPTION
These functions access and manipulate the data associated with a section descriptor, scn. When reading an
existing file, a section will have a single data buffer associated with it. A program may build a new section
in pieces, however, composing the new data from multiple data buffers. For this reason, ‘‘the’’ data for a
section should be viewed as a list of buffers, each of which is available through a data descriptor.
elf_getdata lets a program step through a section’s data list. If the incoming data descriptor, data,is
null, the function returns the first buffer associated with the section. Otherwise, data should be a data
descriptor associated with scn, and the function gives the program access to the next data buffer for the
section. If scn is null or an error occurs,
elf_getdata returns a null pointer.
elf_getdata translates the data from file representations into memory representations (see
elf_xlate(3E)) and presents objects with memory data types to the program, based on the file’s class (see
elf(3E)). The working library version (see elf_version(3E)) specifies what version of the memory structures
the program wishes
elf_getdata to present.
elf_newdata creates a new data descriptor for a section, appending it to any data buffers already associ-
ated with the section. As described below, the new data descriptor appears empty, indicating the buffer
holds no data. For convenience, the descriptor’s type (
d_type below) is set to ELF_T_BYTE , and the ver-
sion (
d_version below) is set to the working version. The program is responsible for setting (or chang-
ing) the descriptor members as needed. This function implicitly sets the ELF_F_DIRTY bit for the
section’s data (see elf_flag(3E)). If scn is null or an error occurs,
elf_newdata returns a null pointer.
elf_rawdata differs from elf_getdata by returning only uninterpreted bytes, regardless of the sec-
tion type. This function typically should be used only to retrieve a section image from a file being read, and
then only when a program must avoid the automatic data translation described below. Moreover, a pro-
gram may not close or disable (see elf_cntl(3E)) the file descriptor associated with elf before the initial raw
operation, because
elf_rawdata might read the data from the file to ensure it doesn’t interfere with
elf_getdata . See elf_rawfile(3E) for a related facility that applies to the entire file. When
elf_getdata provides the right translation, its use is recommended over elf_rawdata .Ifscn is null
or an error occurs,
elf_rawdata returns a null pointer.
The Elf_Data structure includes the following members.
void *d_buf;
Elf_Type d_type;
size_t d_size;
off_t d_off;
size_t d_align;
unsigned d_version;
These members are available for direct manipulation by the program. Descriptions appear below.
d_buf A pointer to the data buffer resides here. A data element with no data has a null pointer.
d_type This member’s value specifies the type of the data to which d_buf points. A section’s type
determines how to interpret the section contents, as summarized below.
d_size This member holds the total size, in bytes, of the memory occupied by the data. This may
differ from the size as represented in the file. The size will be zero if no data exist. (See
the discussion of SHT_NOBITS below for more information.)
d_off This member gives the offset, within the section, at which the buffer resides. This offset is
relative to the file’s section, not the memory object’s.
d_align This member holds the buffer’s required alignment, from the beginning of the section. That
is, d_off will be a multiple of this member’s value. For example, if this member’s value is
four, the beginning of the buffer will be four-byte aligned within the section. Moreover, the
HP-UX 11i Version 1: September 2005 − 1 − Hewlett-Packard Company Section 3−−207