elf_getdata(3E)elf_getdata(3E)NAME
elf_getdata, elf_newdata, elf_rawdata - get section data
SYNOPSIS
[flag... ] file... [library] ...
DESCRIPTION
These functions access and manipulate the data associated with a sec‐
tion 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.
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 descrip‐
tor associated with scn, and the function gives the program access to
the next data element for the section. If scn is null or an error
occurs, returns a null pointer.
translates the data from file representations into memory representa‐
tions (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 to present.
creates a new data descriptor for a section, appending it to any data
elements already associated with the section. As described below, the
new data descriptor appears empty, indicating the element holds no
data. For convenience, the descriptor's type below) is set to and the
version below) is set to the working version. The program is responsi‐
ble for setting (or changing) the descriptor members as needed. This
function implicitly sets the bit for the section's data (see
elf_flag(3E)). If scn is null or an error occurs, returns a null
pointer.
differs from by returning only uninterpreted bytes, regardless of the
section 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
program may not close or disable (see elf_cntl(3E)) the file descriptor
associated with elf before the initial raw operation, because might
read the data from the file to ensure it doesn't interfere with See
elf_rawfile(3E) for a related facility that applies to the entire file.
When provides the right translation, its use is recommended over If scn
is null or an error occurs, returns a null pointer.
The structure includes the following members.
Elf_Void *d_buf;
Elf_Type d_type;
Elf64_Xword d_size;
Elf64_Off d_off;
Elf64_Xword d_align;
unsigned d_version;
These members are available for direct manipulation by the program.
Descriptions appear below.
A pointer to the data buffer resides here. A data
element with no data has a null pointer.
This member's value specifies the type of the data
to which points. A section's type determines how to
interpret the section contents, as summarized below.
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 below for more
information.)
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.
This member holds the buffer's required alignment,
from the beginning of the section. That is, 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
entire section will be aligned to the maximum of its
constituents, thus ensuring appropriate alignment for a
buffer within the section and within the file.
This member holds the version number of the
objects in the buffer. When the library originally read
the data from the object file, it used the working ver‐
sion to control the translation to memory objects.
Data Alignment
As mentioned above, data buffers within a section have explicit align‐
ment constraints. Consequently, adjacent buffers sometimes will not
abut, causing ``holes'' within a section. Programs that create output
files have two ways of dealing with these holes.
First, the program can use to tell the library how to set the interven‐
ing bytes. When the library must generate gaps in the file, it uses
the fill byte to initialize the data there. The library's initial fill
value is zero, and lets the application change that.
Second, the application can generate its own data buffers to occupy the
gaps, filling the gaps with values appropriate for the section being
created. A program might even use different fill values for different
sections. For example, it could set text sections' bytes to no-opera‐
tion instructions, while filling data section holes with zero. Using
this technique, the library finds no holes to fill, because the appli‐
cation eliminated them.
Section and Memory Types
interprets sections' data according to the section type, as noted in
the section header available through elf_getshdr(3E). The following
table shows the section types and how the library represents them with
memory data types for the 32-bit file class. Other classes would have
similar tables. By implication, the memory data types control transla‐
tion by elf_xlate(3E).
Section Type Elf_Type 32-Bit Type
──────────────────────────────────────────
SHT_DYNAMIC ELF_T_DYN Elf32_Dyn
SHT_DYNSYM ELF_T_SYM Elf32_Sym
SHT_HASH ELF_T_WORD Elf32_Word
SHT_NOBITS ELF_T_BYTE unsigned char
SHT_NOTE ELF_T_BYTE unsigned char
SHT_NULL none none
SHT_PROGBITS ELF_T_BYTE unsigned char
SHT_REL ELF_T_REL Elf32_Rel
SHT_RELA ELF_T_RELA Elf32_Rela
SHT_STRTAB ELF_T_BYTE unsigned char
SHT_SYMTAB ELF_T_SYM Elf32_Sym
other ELF_T_BYTE unsigned char
creates a buffer with type
As mentioned above, the program's working version controls what struc‐
tures the library creates for the application. The library similarly
interprets section types according to the versions. If a section type
``belongs'' to a version newer than the application's working version,
the library does not translate the section data. Because the applica‐
tion cannot know the data format in this case, the library presents an
untranslated buffer of type just as it would for an unrecognized sec‐
tion type.
A section with a special type, occupies no space in an object file,
even when the section header indicates a non-zero size. and ``work''
on such a section, setting the data structure to have a null buffer
pointer and the type indicated above. Although no data is present, the
value is set to the size from the section header. When a program is
creating a new section of type it should use to add data buffers to the
section. These ``empty'' data buffers should have the members set to
the desired size and the members set to null.
EXAMPLES
The following fragment obtains the string table that holds section
names (ignoring error checking). See elf_strptr(3E) for a variation of
string table handling.
ehdr = elf32_getehdr(elf);
scn = elf_getscn(elf, (size_t)ehdr->e_shstrndx);
shdr = elf32_getshdr(scn);
if (shdr->sh_type != SHT_STRTAB)
{
/* not a string table */
}
data = 0;
if ((data = elf_getdata(scn, data)) == 0
|| data->d_size == 0)
{
/* error or no data */
}
The member in an ELF header holds the section table index of the string
table. The program gets a section descriptor for that section, veri‐
fies it is a string table, and then retrieves the data. When this
fragment finishes, points at the first byte of the string table, and
holds the string table's size in bytes.
SEE ALSOelf(3E), elf_cntl(3E), elf_fill(3E), elf_flag(3E), elf_getehdr(3E),
elf_getscn(3E), elf_getshdr(3E), elf_rawfile(3E), elf_strptr(3E),
elf_version(3E), elf_xlate(3E).
elf_getdata(3E)
