1elf_getdata(3ELF)            ELF Library Functions           elf_getdata(3ELF)
2
3
4

NAME

6       elf_getdata, elf_newdata, elf_rawdata - get section data
7

SYNOPSIS

9       cc [ flag ... ] file ... -lelf [ library ... ]
10       #include <libelf.h>
11
12       Elf_Data *elf_getdata(Elf_Scn *scn, Elf_Data *data);
13
14
15       Elf_Data *elf_newdata(Elf_Scn *scn);
16
17
18       Elf_Data *elf_rawdata(Elf_Scn *scn, Elf_Data *data);
19
20

DESCRIPTION

22       These  functions  access and manipulate the data associated with a sec‐
23       tion descriptor, scn. When reading an existing  file,  a  section  will
24       have a single data buffer associated with it. A program may build a new
25       section in pieces, however, composing the new data from  multiple  data
26       buffers.  For this reason, the data for a section should be viewed as a
27       list of buffers, each of which is available through a data descriptor.
28
29
30       The elf_getdata() function lets a program step through a section's data
31       list.  If  the  incoming  data  descriptor, data, is null, the function
32       returns the first buffer associated with the section.  Otherwise,  data
33       should be a data descriptor associated with scn, and the function gives
34       the program access to the next data element for the section. If scn  is
35       null or an error occurs, elf_getdata() returns a null pointer.
36
37
38       The  elf_getdata()  function  translates the data from file representa‐
39       tions  into  memory  representations  (see  elf32_xlatetof(3ELF))   and
40       presents  objects  with  memory data types to the program, based on the
41       file's class (see elf(3ELF)). The working library version (see elf_ver‐
42       sion(3ELF)) specifies what version of the memory structures the program
43       wishes elf_getdata() to present.
44
45
46       The elf_newdata() function creates a new data descriptor for a section,
47       appending  it to any data elements already associated with the section.
48       As described below, the new data descriptor appears  empty,  indicating
49       the  element  holds  no  data.  For  convenience, the descriptor's type
50       (d_type below) is set to ELF_T_BYTE, and the version (d_version  below)
51       is  set  to the working version. The program is responsible for setting
52       (or changing) the descriptor members as needed. This  function  implic‐
53       itly  sets  the  ELF_F_DIRTY  bit for the section's data (see elf_flag‐
54       data(3ELF)). If  scn is null or an error occurs, elf_newdata()  returns
55       a null pointer.
56
57
58       The elf_rawdata() function differs from elf_getdata() by returning only
59       uninterpreted bytes, regardless of the section type. This function typ‐
60       ically  should  be  used  only  to retrieve a section image from a file
61       being read, and then only when a program must avoid the automatic  data
62       translation  described below. Moreover, a program may not close or dis‐
63       able (see elf_cntl(3ELF))  the  file  descriptor  associated  with  elf
64       before  the initial raw operation, because elf_rawdata() might read the
65       data from the file to ensure it doesn't interfere  with  elf_getdata().
66       See elf_rawfile(3ELF) for a related facility that applies to the entire
67       file. When elf_getdata() provides the right  translation,  its  use  is
68       recommended  over  elf_rawdata().  If  scn  is null or an error occurs,
69       elf_rawdata() returns a null pointer.
70
71
72       The Elf_Data structure includes the following members:
73
74         void        *d_buf;
75         Elf_Type    d_type;
76         size_t      d_size;
77         off_t       d_off;
78         size_t      d_align;
79         unsigned    d_version;
80
81
82
83       These members are available for direct  manipulation  by  the  program.
84       Descriptions appear below.
85
86       d_buf        A  pointer to the data buffer resides here. A data element
87                    with no data has a null pointer.
88
89
90       d_type       This member's value specifies the  type  of  the  data  to
91                    which  d_buf  points.  A  section's type determines how to
92                    interpret the section contents, as summarized below.
93
94
95       d_size       This member holds the total size, in bytes, of the  memory
96                    occupied  by  the  data.  This may differ from the size as
97                    represented in the file. The size will be zero if no  data
98                    exist.  (See  the  discussion of SHT_NOBITS below for more
99                    information.)
100
101
102       d_off        This member gives the offset, within the section, at which
103                    the  buffer resides. This offset is relative to the file's
104                    section, not the memory object's.
105
106
107       d_align      This member holds the buffer's  required  alignment,  from
108                    the  beginning  of  the  section. That is, d_off will be a
109                    multiple of this member's value. For example, if this mem‐
110                    ber's  value  is  4,  the  beginning of the buffer will be
111                    four-byte aligned within the section. Moreover, the entire
112                    section  will  be  aligned  to  the  maximum  of  its con‐
113                    stituents, thus ensuring appropriate alignment for a  buf‐
114                    fer within the section and within the file.
115
116
117       d_version    This member holds the version number of the objects in the
118                    buffer. When the library originally read the data from the
119                    object  file,  it  used the working version to control the
120                    translation to memory objects.
121
122
123   Data Alignment
124       As mentioned above, data buffers within a section have explicit  align‐
125       ment  constraints.  Consequently,  adjacent  buffers sometimes will not
126       abut, causing ``holes'' within a section. Programs that  create  output
127       files have two ways of dealing with these holes.
128
129
130       First,  the  program  can use elf_fill() to tell the library how to set
131       the intervening bytes. When the library must generate gaps in the file,
132       it  uses the fill byte to initialize the data there. The library's ini‐
133       tial fill value is 0, and elf_fill() lets the application change that.
134
135
136       Second, the application can generate its own data buffers to occupy the
137       gaps,  filling  the  gaps with values appropriate for the section being
138       created. A program might even use different fill values  for  different
139       sections.  For  example, it could set text sections' bytes to no-opera‐
140       tion instructions, while filling data section holes  with  zero.  Using
141       this  technique, the library finds no holes to fill, because the appli‐
142       cation eliminated them.
143
144   Section and Memory Types
145       The elf_getdata() function interprets sections' data according  to  the
146       section  type,  as  noted  in  the  section  header  available  through
147       elf32_getshdr(). The following table shows the section  types  and  how
148       the  library represents them with memory data types for the 32-bit file
149       class. Other classes would have similar  tables.  By  implication,  the
150       memory data types control translation by elf32_xlatetof(3ELF)
151
152
153
154
155          Section Type           Elf_Type            32-bit Type
156       SHT_DYNAMIC          ELF_T_DYN             Elf32_Dyn
157       SHT_DYNSYM           ELF_T_SYM             Elf32_Sym
158       SHT_FINI_ARRAY       ELF_T_ADDR            Elf32_Addr
159       SHT_GROUP            ELF_T_WORD            Elf32_Word
160       SHT_HASH             ELF_T_WORD            Elf32_Word
161       SHT_INIT_ARRAY       ELF_T_ADDR            Elf32_Addr
162       SHT_NOBITS           ELF_T_BYTE            unsigned char
163       SHT_NOTE             ELF_T_NOTE            unsigned char
164       SHT_NULL             none                  none
165       SHT_PREINIT_ARRAY    ELF_T_ADDR            Elf32_Addr
166       SHT_PROGBITS         ELF_T_BYTE            unsigned char
167       SHT_REL              ELF_T_REL             Elf32_Rel
168       SHT_RELA             ELF_T_RELA            Elf32_Rela
169       SHT_STRTAB           ELF_T_BYTE            unsigned char
170       SHT_SYMTAB           ELF_T_SYM             Elf32_Sym
171       SHT_SUNW_comdat      ELF_T_BYTE            unsigned char
172       SHT_SUNW_move        ELF_T_MOVE            Elf32_Move (sparc)
173       SHT_SUNW_move        ELF_T_MOVEP           Elf32_Move (ia32)
174       SHT_SUNW_syminfo     ELF_T_SYMINFO         Elf32_Syminfo
175       SHT_SUNW_verdef      ELF_T_VDEF            Elf32_Verdef
176       SHT_SUNW_verneed     ELF_T_VNEED           Elf32_Verneed
177       SHT_SUNW_versym      ELF_T_HALF            Elf32_Versym
178       other                ELF_T_BYTE            unsigned char
179
180
181
182       The elf_rawdata() function creates a buffer with type ELF_T_BYTE.
183
184
185       As  mentioned above, the program's working version controls what struc‐
186       tures the library creates for the application.  The  library  similarly
187       interprets  section  types according to the versions. If a section type
188       belongs to a version newer than the application's working version,  the
189       library  does  not  translate the section data. Because the application
190       cannot know the data format in  this  case,  the  library  presents  an
191       untranslated  buffer of type ELF_T_BYTE, just as it would for an unrec‐
192       ognized section type.
193
194
195       A section with a special type, SHT_NOBITS,  occupies  no  space  in  an
196       object  file,  even  when the section header indicates a non-zero size.
197       elf_getdata() and elf_rawdata() work on such  a  section,  setting  the
198       data  structure  to  have  a null buffer pointer and the type indicated
199       above. Although no data are present, the d_size value  is  set  to  the
200       size  from the section header. When a program is creating a new section
201       of type SHT_NOBITS, it should use elf_newdata() to add data buffers  to
202       the  section.  These  empty data buffers should have the d_size members
203       set to the desired size and the d_buf members set to  NULL.
204

EXAMPLES

206       Example 1 A sample program of calling elf_getdata().
207
208
209       The following fragment obtains the  string  table  that  holds  section
210       names  (ignoring  error checking). See elf_strptr(3ELF) for a variation
211       of string table handling.
212
213
214         ehdr = elf32_getehdr(elf);
215         scn = elf_getscn(elf, (size_t)ehdr->e_shstrndx);
216         shdr = elf32_getshdr(scn);
217         if (shdr->sh_type != SHT_STRTAB)
218         {
219         /* not a string table */
220         }
221         data = 0;
222         if ((data = elf_getdata(scn, data)) == 0 || data->d_size == 0)
223         {
224         /* error or no data */
225         }
226
227
228
229       The e_shstrndx member in an ELF header holds the section table index of
230       the  string  table. The program gets a section descriptor for that sec‐
231       tion, verifies it is a string table, and then retrieves the data.  When
232       this  fragment  finishes,  data->d_buf  points at the first byte of the
233       string table, and data->d_size holds the string table's size in bytes.
234
235

ATTRIBUTES

237       See attributes(5) for descriptions of the following attributes:
238
239
240
241
242       ┌─────────────────────────────┬─────────────────────────────┐
243       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
244       ├─────────────────────────────┼─────────────────────────────┤
245       │Interface Stability          │Stable                       │
246       ├─────────────────────────────┼─────────────────────────────┤
247       │MT-Level                     │MT-Safe                      │
248       └─────────────────────────────┴─────────────────────────────┘
249

SEE ALSO

251       elf(3ELF),   elf32_getehdr(3ELF),    elf64_getehdr(3ELF),    elf32_get‐
252       shdr(3ELF),          elf64_getshdr(3ELF),         elf32_xlatetof(3ELF),
253       elf64_xlatetof(3ELF),   elf_cntl(3ELF),    elf_fill(3ELF),    elf_flag‐
254       data(3ELF),   elf_getscn(3ELF),   elf_rawfile(3ELF),  elf_strptr(3ELF),
255       elf_version(3ELF), libelf(3LIB), attributes(5)
256
257
258
259SunOS 5.11                        11 Jul 2001                elf_getdata(3ELF)
Impressum