'\"!  tbl | mmdoc
'\"macro stdmacro
.if n .pH g3e.elf_getdata @(#)elf_getdata	40.9 of 10/27/89
.\" Copyright 1989 AT&T
.\"#ident	"@(#)ci5-doc:req/libelf/getdata.man	1.3"
.nr X
.if \nX=0 .ds x} elf_getdata 3E "ELF Library" "\&"
.if \nX=1 .ds x} elf_getdata 3E "ELF Library"
.if \nX=2 .ds x} elf_getdata 3E "" "\&"
.if \nX=3 .ds x} elf_getdata "" "" "\&"
.TH \*(x}
.SH NAME
\f4elf_getdata\f1, \f4elf_newdata\f1, \f4elf_rawdata\f1 \- get section data
.SH SYNOPSIS
\f4cc\f1
[\f2flag\fP \|.\|.\|.] \f2file\fP \|.\|.\|.
\f4\-lelf\f1
[\f2library\fP \|.\|.\|.]
.PP
.nf
.na
.ft 4
#include <libelf.h>
.sp 0.5
Elf_Data \(**elf_getdata(Elf_Scn \(**scn, Elf_Data \(**data);
.sp 0.5
Elf_Data \(**elf_newdata(Elf_Scn \(**scn);
.sp 0.5
Elf_Data \(**elf_rawdata(Elf_Scn \(**scn, Elf_Data \(**data);
.ft 1
.ad
.fi
.SH DESCRIPTION
These functions access and manipulate the data
associated with a section descriptor,
.IR 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.
.P
\f4elf_getdata\fP
lets a program step through a section's data list.
If the incoming data descriptor,
.IR data ,
is null, the function returns the first buffer associated
with the section.
Otherwise,
.I data
should be a data descriptor associated with
.IR scn ,
and the function gives the program access to the next
data element for the section.
If
.I scn
is null or an error occurs,
\f4elf_getdata\fP
returns a null pointer.
.P
\f4elf_getdata\fP
translates the data from file representations into
memory representations [see
\f4elf_xlate\fP(3E)]
and presents objects with memory data types to the program,
based on the file's
.I class
[see
\f4elf\fP(3E)].
The working library version [see
\f4elf_version\fP(3E)]
specifies what version of the memory structures the program wishes
\f4elf_getdata\fP
to present.
.P
\f4elf_newdata\fP
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 (\f4d_type\fP below)
is set to
\f4ELF_T_BYTE\f1,
and the version (\f4d_version\fP below) is set to
the working version.
The program is responsible for setting (or changing)
the descriptor members as needed.
This function implicitly sets the
\f4ELF_F_DIRTY\f1
bit for the section's data [see
\f4elf_flag\fP(3E)].
If
.I scn
is null or an error occurs,
\f4elf_newdata\fP
returns a null pointer.
.P
\f4elf_rawdata\fP
differs from
\f4elf_getdata\fP
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
\f4elf_cntl\fP(3E)]
the file descriptor associated with
.I elf
before the initial raw operation,
because
\f4elf_rawdata\fP
might read the data from the file to ensure it doesn't
interfere with
\f4elf_getdata\fP.
See
\f4elf_rawfile\fP(3E)
for a related facility that applies to the entire file.
When
\f4elf_getdata\fP
provides the right translation, its use is recommended over
\f4elf_rawdata\fP.
If
.I scn
is null or an error occurs,
\f4elf_rawdata\fP
returns a null pointer.
.P
The
\f4Elf_Data\f1
structure includes the following members.
.P
.RS .5i
.DT
.nf
.ft 4
.ta 8u*\w' 'u +8u*\w' 'u +8u*\w' 'u +8u*\w' 'u +8u*\w' 'u +8u*\w' 'u
.ne 11
	void		\(**d_buf;
	Elf_Type	d_type;
	size_t		d_size;
	off_t		d_off;
	size_t		d_align;
	unsigned	d_version;
.fi
.RE
.P
These members are available for direct manipulation
by the program.
Descriptions appear below.
.P
.IP "\f4d_buf\fP" 14
A pointer to the data buffer resides here.
A data element with no data has a null pointer.
.IP "\f4d_type\fP"
This member's value specifies the type of
the data to which \f4d_buf\fP points.
A section's type determines how to
interpret the section contents, as summarized below.
.IP "\f4d_size\fP"
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
\f4SHT_NOBITS\f1
below for more information.]
.IP \f4d_off\fP
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.
.IP \f4d_align\fP
This member holds the buffer's required alignment, from the beginning
of the section.
That is, \f4d_off\fP 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.
.IP "\f4d_version\fP"
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 version
to control the translation to memory objects.
.SH "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.
.P
First, the program can use
\f4elf_fill\fP
to tell the library how to set the intervening 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
\f4elf_fill\fP
lets the application change that.
.P
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-operation instructions, while filling data section holes with zero.
Using this technique, the library finds no holes to fill,
because the application eliminated them.
.SH "SECTION AND MEMORY TYPES"
\f4elf_getdata\fP
interprets sections' data according to the
section type, as noted in the section header available
through
\f4elf_getshdr\fP.
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
\f4elf_xlate\fP.
.P
.ne 14
.TS
center;
c cf4 c
lf4 | lf4 | lf4.
Section Type	Elf_Type	32-Bit Type
.sp .3v
_
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	\f2none\fP	\f2none\fP
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
\f2other\fP	ELF_T_BYTE	unsigned char
.sp .3v
_
.TE
.P
\f4elf_rawdata\fP
creates a buffer with type
\f4ELF_T_BYTE\f1.
.P
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
\f4ELF_T_BYTE\f1,
just as it would for an unrecognized section type.
.P
A section with a special type,
\f4SHT_NOBITS\f1,
occupies no space in an object file, even when
the section header indicates a non-zero size.
\f4elf_getdata\fP
and
\f4elf_rawdata\fP
``work'' on such a section, setting the
.I data
structure to have a null buffer pointer and
the type indicated above.
Although no data are present, the \f4d_size\fP
value is set to the size from the section header.
When a program is creating a new section of type
\f4SHT_NOBITS\f1,
it should use
\f4elf_newdata\fP
to add data buffers to the section.
These ``empty'' data buffers should have the
\f4d_size\fP members set to the desired size
and the \f4d_buf\fP members set to null.
.SH EXAMPLE
The following fragment obtains the string table that holds
section names (ignoring error checking).
See
\f4elf_strptr\fP(3E)
for a variation of string table handling.
.P
.RS .5i
.DT
.nf
.ft 4
.ta 8u*\w' 'u +8u*\w' 'u +8u*\w' 'u +8u*\w' 'u +8u*\w' 'u +8u*\w' 'u
.ne 9
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 \(**/
}
.fi
.RE
.P
The \f4e_shstrndx\fP member in an
.SM 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, \f4\%data->d_buf\fP points at the
first byte of the string table, and \f4\%data->d_size\fP holds
the string table's size in bytes.
.SH "SEE ALSO"
.na
\f4elf\fP(3E),
\f4elf_cntl\fP(3E),
\f4elf_fill\fP(3E),
\f4elf_flag\fP(3E),
\f4elf_getehdr\fP(3E),
\f4elf_getscn\fP(3E),
\f4elf_getshdr\fP(3E),
\f4elf_rawfile\fP(3E),
\f4elf_version\fP(3E),
\f4elf_xlate\fP(3E).
