1elf_getdata(3ELF) ELF Library Functions elf_getdata(3ELF)
2
6 elf_getdata, elf_newdata, elf_rawdata - get section data
7
9 cc [ flag ... ] file ... -lelf [ library ... ]
10 #include <libelf.h>
11 Elf_Data *elf_getdata(Elf_Scn *scn, Elf_Data *data);
13 Elf_Data *elf_newdata(Elf_Scn *scn);
16 Elf_Data *elf_rawdata(Elf_Scn *scn, Elf_Data *data);
19
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 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 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 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 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 The Elf_Data structure includes the following members:
73 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 These members are available for direct manipulation by the program.
84 Descriptions appear below.
85 d_buf A pointer to the data buffer resides here. A data element
87 with no data has a null pointer.
88 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 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 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 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 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 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 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 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 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 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 The elf_rawdata() function creates a buffer with type ELF_T_BYTE.
183 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 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
206 Example 1 A sample program of calling elf_getdata().
207 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 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 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
237 See attributes(5) for descriptions of the following attributes:
238 ┌─────────────────────────────┬─────────────────────────────┐
243 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
244 ├─────────────────────────────┼─────────────────────────────┤
245 │Interface Stability │Stable │
246 ├─────────────────────────────┼─────────────────────────────┤
247 │MT-Level │MT-Safe │
248 └─────────────────────────────┴─────────────────────────────┘
249
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)
256SunOS 5.11 11 Jul 2001 elf_getdata(3ELF)