ELF Library Functions elfgetdata(3ELF)
NAME
elfgetdata, elfnewdata, elfrawdata - get section data
SYNOPSIS
cc [ flag ... ] file ... -lelf [ library ... ]
#include
ElfData *elfgetdata(ElfScn *scn, ElfData *data);
ElfData *elfnewdata(ElfScn *scn);
ElfData *elfrawdata(ElfScn *scn, ElfData *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, how-
ever, 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.
The elfgetdata() function 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, elfgetdata() returns a null
pointer.
The elfgetdata() function translates the data from file
representations into memory representations (see
elf32xlatetof(3ELF)) and presents objects with memory data
types to the program, based on the file's class (see
elf(3ELF)). The working library version (see
elfversion(3ELF)) specifies what version of the memory
structures the program wishes elfgetdata() to present.
The elfnewdata() function creates a new data descriptor for
a section, appending it to any data elements already associ-
ated with the section. As described below, the new data
descriptor appears empty, indicating the element holds no
data. For convenience, the descriptor's type (dtype below)
is set to ELFTBYTE, and the version (dversion below) is
SunOS 5.11 Last change: 11 Jul 2001 1
ELF Library Functions elfgetdata(3ELF)
set to the working version. The program is responsible for
setting (or changing) the descriptor members as needed. This
function implicitly sets the ELFDIRTY bit for the
section's data (see elfflagdata(3ELF)). If scn is null or
an error occurs, elfnewdata() returns a null pointer.
The elfrawdata() function differs from elfgetdata() 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 transla-
tion described below. Moreover, a program may not close or
disable (see elfcntl(3ELF)) the file descriptor associated
with elf before the initial raw operation, because
elfrawdata() might read the data from the file to ensure it
doesn't interfere with elfgetdata(). See elfrawfile(3ELF)
for a related facility that applies to the entire file. When
elfgetdata() provides the right translation, its use is
recommended over elfrawdata(). If scn is null or an error
occurs, elfrawdata() returns a null pointer.
The ElfData structure includes the following members:
void *dbuf;
ElfType dtype;
sizet dsize;
offt doff;
sizet dalign;
unsigned dversion;
These members are available for direct manipulation by the
program. Descriptions appear below.
dbuf A pointer to the data buffer resides here. A
data element with no data has a null pointer.
dtype This member's value specifies the type of the
data to which dbuf points. A section's type
determines how to interpret the section con-
tents, as summarized below.
dsize 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 SHTNOBITS below for
SunOS 5.11 Last change: 11 Jul 2001 2
ELF Library Functions elfgetdata(3ELF)
more information.)
doff This member gives the offset, within the sec-
tion, at which the buffer resides. This offset
is relative to the file's section, not the
memory object's.
dalign This member holds the buffer's required align-
ment, from the beginning of the section. That
is, doff will be a multiple of this member's
value. For example, if this member's value is
4, 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.
dversion This member holds the version number of the
objects in the buffer. When the library origi-
nally read the data from the object file, it
used the working version to control the trans-
lation to memory objects.
Data Alignment
As mentioned above, data buffers within a section have
explicit alignment 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 elffill() to tell the library
how to set the intervening bytes. When the library must gen-
erate gaps in the file, it uses the fill byte to initialize
the data there. The library's initial fill value is 0, and
elffill() 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 dif-
ferent fill values for different sections. For example, it
could set text sections' bytes to no-operation instructions,
while filling data section holes with zero. Using this tech-
nique, the library finds no holes to fill, because the
application eliminated them.
SunOS 5.11 Last change: 11 Jul 2001 3
ELF Library Functions elfgetdata(3ELF)
Section and Memory Types
The elfgetdata() function interprets sections' data accord-
ing to the section type, as noted in the section header
available through elf32getshdr(). 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 translation by elf32xlatetof(3ELF)
Section Type ElfType 32-bit Type
SHTDYNAMIC ELFTDYN Elf32Dyn
SHTDYNSYM ELFTSYM Elf32Sym
SHTFINIARAY ELFTADR Elf32Addr
SHTGROUP ELFTWORD Elf32Word
SHTHASH ELFTWORD Elf32Word
SHTINITARAY ELFTADR Elf32Addr
SHTNOBITS ELFTBYTE unsigned char
SHTNOTE ELFTNOTE unsigned char
SHTNUL none none
SHTPREINITARAY ELFTADR Elf32Addr
SHTPROGBITS ELFTBYTE unsigned char
SHTREL ELFTREL Elf32Rel
SHTRELA ELFTRELA Elf32Rela
SHTSTRTAB ELFTBYTE unsigned char
SHTSYMTAB ELFTSYM Elf32Sym
SHTSUNWcomdat ELFTBYTE unsigned char
SHTSUNWmove ELFTMOVE Elf32Move (sparc)
SHTSUNWmove ELFTMOVEP Elf32Move (ia32)
SHTSUNWsyminfo ELFTSYMINFO Elf32Syminfo
SHTSUNWverdef ELFTVDEF Elf32Verdef
SHTSUNWverneed ELFTVNED Elf32Verneed
SHTSUNWversym ELFTHALF Elf32Versym
other ELFTBYTE unsigned char
The elfrawdata() function creates a buffer with type
ELFTBYTE.
As mentioned above, the program's working version controls
what structures 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 application cannot
know the data format in this case, the library presents an
untranslated buffer of type ELFTBYTE, just as it would for
an unrecognized section type.
SunOS 5.11 Last change: 11 Jul 2001 4
ELF Library Functions elfgetdata(3ELF)
A section with a special type, SHTNOBITS, occupies no space
in an object file, even when the section header indicates a
non-zero size. elfgetdata() and elfrawdata() work on such
a section, setting the data structure to have a null buffer
pointer and the type indicated above. Although no data are
present, the dsize value is set to the size from the sec-
tion header. When a program is creating a new section of
type SHTNOBITS, it should use elfnewdata() to add data
buffers to the section. These empty data buffers should have
the dsize members set to the desired size and the dbuf
members set to NUL.
EXAMPLES
Example 1 A sample program of calling elfgetdata().
The following fragment obtains the string table that holds
section names (ignoring error checking). See
elfstrptr(3ELF) for a variation of string table handling.
ehdr = elf32getehdr(elf);
scn = elfgetscn(elf, (sizet)ehdr->eshstrndx);
shdr = elf32getshdr(scn);
if (shdr->shtype != SHTSTRTAB)
{
/* not a string table */
}
data = 0;
if ((data = elfgetdata(scn, data)) == 0 data->dsize == 0)
{
/* error or no data */
}
The eshstrndx member in an ELF header holds the section
table index of the string table. The program gets a section
descriptor for that section, verifies it is a string table,
and then retrieves the data. When this fragment finishes,
data->dbuf points at the first byte of the string table,
and data->dsize holds the string table's size in bytes.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 11 Jul 2001 5
ELF Library Functions elfgetdata(3ELF)
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Stable
MT-Level MT-Safe
SEE ALSO
elf(3ELF), elf32getehdr(3ELF), elf64getehdr(3ELF),
elf32getshdr(3ELF), elf64getshdr(3ELF),
elf32xlatetof(3ELF), elf64xlatetof(3ELF), elfcntl(3ELF),
elffill(3ELF), elfflagdata(3ELF), elfgetscn(3ELF),
elfrawfile(3ELF), elfstrptr(3ELF), elfversion(3ELF),
libelf(3LIB), attributes(5)
SunOS 5.11 Last change: 11 Jul 2001 6
|
