8322 nl: misleading-indentation

[unleashed/tickless.git] / usr / src / man / man3elf / elf_getdata.3elf

'\" te
.\"  Copyright 1989 AT&T  Copyright (c) 2001, Sun Microsystems, Inc.  All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH ELF_GETDATA 3ELF "Jul 11, 2001"
.SH NAME
elf_getdata, elf_newdata, elf_rawdata \- get section data
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR ... ] \fIfile\fR ... \fB-lelf\fR [ \fIlibrary\fR ... ]
#include <libelf.h>

\fBElf_Data *\fR\fBelf_getdata\fR(\fBElf_Scn *\fR\fIscn\fR, \fBElf_Data *\fR\fIdata\fR);
.fi

.LP
.nf
\fBElf_Data *\fR\fBelf_newdata\fR(\fBElf_Scn *\fR\fIscn\fR);
.fi

.LP
.nf
\fBElf_Data *\fR\fBelf_rawdata\fR(\fBElf_Scn *\fR\fIscn\fR, \fBElf_Data *\fR\fIdata\fR);
.fi

.SH DESCRIPTION
.sp
.LP
These functions access and manipulate the data associated with a section
descriptor, \fIscn\fR. 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.
.sp
.LP
The \fBelf_getdata()\fR function lets a program step through a section's data
list. If the incoming data descriptor, \fIdata\fR, is null, the function
returns the first buffer associated with the section. Otherwise, \fIdata\fR
should be a data descriptor associated with \fIscn\fR, and the function gives
the program access to the next data element for the section. If \fIscn\fR is
null or an error occurs, \fBelf_getdata()\fR returns a null pointer.
.sp
.LP
The \fBelf_getdata()\fR function translates the data from file representations
into memory representations (see \fBelf32_xlatetof\fR(3ELF)) and presents
objects with memory data types to the program, based on the file's \fIclass\fR
(see \fBelf\fR(3ELF)). The working library version (see
\fBelf_version\fR(3ELF)) specifies what version of the memory structures the
program wishes \fBelf_getdata()\fR to present.
.sp
.LP
The \fBelf_newdata()\fR function 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 (\fBd_type\fR below) is
set to \fBELF_T_BYTE\fR, and the version (\fBd_version\fR 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
\fBELF_F_DIRTY\fR bit for the section's data (see \fBelf_flagdata\fR(3ELF)). If
\fI scn\fR is null or an error occurs, \fBelf_newdata()\fR returns a null
pointer.
.sp
.LP
The \fBelf_rawdata()\fR function differs from \fBelf_getdata()\fR 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
\fBelf_cntl\fR(3ELF)) the file descriptor associated with \fIelf\fR before the
initial raw operation, because \fBelf_rawdata()\fR might read the data from the
file to ensure it doesn't interfere with \fBelf_getdata()\fR. See
\fBelf_rawfile\fR(3ELF) for a related facility that applies to the entire file.
When \fBelf_getdata()\fR provides the right translation, its use is recommended
over \fBelf_rawdata()\fR. If \fIscn\fR is null or an error occurs,
\fBelf_rawdata()\fR returns a null pointer.
.sp
.LP
The \fBElf_Data\fR structure includes the following members:
.sp
.in +2
.nf
void        *d_buf;
Elf_Type    d_type;
size_t      d_size;
off_t       d_off;
size_t      d_align;
unsigned    d_version;
.fi
.in -2

.sp
.LP
These members are available for direct manipulation by the program.
Descriptions appear below.
.sp
.ne 2
.na
\fB\fBd_buf\fR\fR
.ad
.RS 13n
A pointer to the data buffer resides here. A data element with no data has a
null pointer.
.RE

.sp
.ne 2
.na
\fB\fBd_type\fR\fR
.ad
.RS 13n
This member's value specifies the type of the data to which \fBd_buf\fR points.
A section's type determines how to interpret the section contents, as
summarized below.
.RE

.sp
.ne 2
.na
\fB\fBd_size\fR\fR
.ad
.RS 13n
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 \fBSHT_NOBITS\fR below for more
information.)
.RE

.sp
.ne 2
.na
\fB\fBd_off\fR\fR
.ad
.RS 13n
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.
.RE

.sp
.ne 2
.na
\fB\fBd_align\fR\fR
.ad
.RS 13n
This member holds the buffer's required alignment, from the beginning of the
section. That is, \fBd_off\fR will be a multiple of this member's value. For
example, if this member's value is \fB4\fR, 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.
.RE

.sp
.ne 2
.na
\fB\fBd_version\fR\fR
.ad
.RS 13n
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.
.RE

.SS "Data Alignment"
.sp
.LP
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.
.sp
.LP
First, the program can use \fBelf_fill()\fR 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
\fB0\fR, and \fBelf_fill()\fR lets the application change that.
.sp
.LP
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.
.SS "Section and Memory Types"
.sp
.LP
The \fBelf_getdata()\fR function interprets sections' data according to the
section type, as noted in the section header available through
\fBelf32_getshdr()\fR. 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 \fBelf32_xlatetof\fR(3ELF)
.sp

.sp
.TS
c c c
l l l .
Section Type    Elf_Type        32-bit Type
\fBSHT_DYNAMIC\fR       \fBELF_T_DYN\fR \fBElf32_Dyn\fR
\fBSHT_DYNSYM\fR        \fBELF_T_SYM\fR \fBElf32_Sym\fR
\fBSHT_FINI_ARRAY\fR    \fBELF_T_ADDR\fR        \fBElf32_Addr\fR
\fBSHT_GROUP\fR \fBELF_T_WORD\fR        \fBElf32_Word\fR
\fBSHT_HASH\fR  \fBELF_T_WORD\fR        \fBElf32_Word\fR
\fBSHT_INIT_ARRAY\fR    \fBELF_T_ADDR\fR        \fBElf32_Addr\fR
\fBSHT_NOBITS\fR        \fBELF_T_BYTE\fR        \fBunsigned char\fR
\fBSHT_NOTE\fR  \fBELF_T_NOTE\fR        \fBunsigned char\fR
\fBSHT_NULL\fR  \fInone\fR      \fInone\fR
\fBSHT_PREINIT_ARRAY\fR \fBELF_T_ADDR\fR        \fBElf32_Addr\fR
\fBSHT_PROGBITS\fR      \fBELF_T_BYTE\fR        \fBunsigned char\fR
\fBSHT_REL\fR   \fBELF_T_REL\fR \fBElf32_Rel\fR
\fBSHT_RELA\fR  \fBELF_T_RELA\fR        \fBElf32_Rela\fR
\fBSHT_STRTAB\fR        \fBELF_T_BYTE\fR        \fBunsigned char\fR
\fBSHT_SYMTAB\fR        \fBELF_T_SYM\fR \fBElf32_Sym\fR
\fBSHT_SUNW_comdat\fR   \fBELF_T_BYTE\fR        \fBunsigned char\fR
\fBSHT_SUNW_move\fR     \fBELF_T_MOVE\fR        \fBElf32_Move\fR (sparc)
\fBSHT_SUNW_move\fR     \fBELF_T_MOVEP\fR       \fBElf32_Move\fR (ia32)
\fBSHT_SUNW_syminfo\fR  \fBELF_T_SYMINFO\fR     \fBElf32_Syminfo\fR
\fBSHT_SUNW_verdef\fR   \fBELF_T_VDEF\fR        \fBElf32_Verdef\fR
\fBSHT_SUNW_verneed\fR  \fBELF_T_VNEED\fR       \fBElf32_Verneed\fR
\fBSHT_SUNW_versym\fR   \fBELF_T_HALF\fR        \fBElf32_Versym\fR
\fIother\fR     \fBELF_T_BYTE\fR        \fBunsigned char\fR
.TE

.sp
.LP
The \fBelf_rawdata()\fR function creates a buffer with type \fBELF_T_BYTE\fR.
.sp
.LP
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 \fBELF_T_BYTE\fR, just as
it would for an unrecognized section type.
.sp
.LP
A section with a special type, \fBSHT_NOBITS\fR, occupies no space in an object
file, even when the section header indicates a non-zero size.
\fBelf_getdata()\fR and \fBelf_rawdata()\fR work on such a section, setting the
\fIdata\fR structure to have a null buffer pointer and the type indicated
above. Although no data are present, the \fBd_size\fR value is set to the size
from the section header. When a program is creating a new section of type
\fBSHT_NOBITS\fR, it should use \fBelf_newdata()\fR to add data buffers to the
section. These empty data buffers should have the \fBd_size\fR members set to
the desired size and the \fBd_buf\fR members set to \fI NULL\fR.
.SH EXAMPLES
.LP
\fBExample 1 \fRA sample program of calling \fBelf_getdata()\fR.
.sp
.LP
The following fragment obtains the string table that holds section names
(ignoring error checking). See \fBelf_strptr\fR(3ELF) for a variation of string
table handling.

.sp
.in +2
.nf
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
.in -2

.sp
.LP
The \fBe_shstrndx\fR member in an \fBELF\fR 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, \fBdata->d_buf\fR points at the first byte of the string
table, and \fBdata->d_size\fR holds the string table's size in bytes.

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE  ATTRIBUTE VALUE
_
Interface Stability     Stable
_
MT-Level        MT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBelf\fR(3ELF), \fBelf32_getehdr\fR(3ELF), \fBelf64_getehdr\fR(3ELF),
\fBelf32_getshdr\fR(3ELF), \fBelf64_getshdr\fR(3ELF),
\fBelf32_xlatetof\fR(3ELF), \fBelf64_xlatetof\fR(3ELF), \fBelf_cntl\fR(3ELF),
\fBelf_fill\fR(3ELF), \fBelf_flagdata\fR(3ELF), \fBelf_getscn\fR(3ELF),
\fBelf_rawfile\fR(3ELF), \fBelf_strptr\fR(3ELF), \fBelf_version\fR(3ELF),
\fBlibelf\fR(3LIB), \fBattributes\fR(5)