1 | .\" Copyright (c) 2006-2008,2011 Joseph Koshy. All rights reserved. |
---|
2 | .\" |
---|
3 | .\" Redistribution and use in source and binary forms, with or without |
---|
4 | .\" modification, are permitted provided that the following conditions |
---|
5 | .\" are met: |
---|
6 | .\" 1. Redistributions of source code must retain the above copyright |
---|
7 | .\" notice, this list of conditions and the following disclaimer. |
---|
8 | .\" 2. Redistributions in binary form must reproduce the above copyright |
---|
9 | .\" notice, this list of conditions and the following disclaimer in the |
---|
10 | .\" documentation and/or other materials provided with the distribution. |
---|
11 | .\" |
---|
12 | .\" This software is provided by Joseph Koshy ``as is'' and |
---|
13 | .\" any express or implied warranties, including, but not limited to, the |
---|
14 | .\" implied warranties of merchantability and fitness for a particular purpose |
---|
15 | .\" are disclaimed. in no event shall Joseph Koshy be liable |
---|
16 | .\" for any direct, indirect, incidental, special, exemplary, or consequential |
---|
17 | .\" damages (including, but not limited to, procurement of substitute goods |
---|
18 | .\" or services; loss of use, data, or profits; or business interruption) |
---|
19 | .\" however caused and on any theory of liability, whether in contract, strict |
---|
20 | .\" liability, or tort (including negligence or otherwise) arising in any way |
---|
21 | .\" out of the use of this software, even if advised of the possibility of |
---|
22 | .\" such damage. |
---|
23 | .\" |
---|
24 | .\" $Id: elf.3 1730 2011-08-14 10:03:34Z jkoshy $ |
---|
25 | .\" |
---|
26 | .Dd August 14, 2011 |
---|
27 | .Os |
---|
28 | .Dt ELF 3 |
---|
29 | .Sh NAME |
---|
30 | .Nm elf |
---|
31 | .Nd API for manipulating ELF objects |
---|
32 | .Sh LIBRARY |
---|
33 | .Lb libelf |
---|
34 | .Sh SYNOPSIS |
---|
35 | .In libelf.h |
---|
36 | .Sh DESCRIPTION |
---|
37 | The |
---|
38 | .Lb libelf |
---|
39 | provides functions that allow an application to read and manipulate |
---|
40 | ELF object files, and to read |
---|
41 | .Xr ar 1 |
---|
42 | archives. |
---|
43 | The library allows the manipulation of ELF objects in a byte ordering |
---|
44 | and word-size independent way, allowing an application to read and |
---|
45 | create ELF objects for 32 and 64 bit architectures and for little- |
---|
46 | and big-endian machines. |
---|
47 | The library is capable of processing ELF objects that use extended |
---|
48 | section numbering. |
---|
49 | .Pp |
---|
50 | This manual page serves to provide an overview of the functionality in |
---|
51 | the ELF library. |
---|
52 | Further information may found in the manual pages for individual |
---|
53 | .Xr ELF 3 |
---|
54 | functions that comprise the library. |
---|
55 | .Ss ELF Concepts |
---|
56 | As described in |
---|
57 | .Xr elf 5 , |
---|
58 | ELF files contain several data structures that are laid out in a |
---|
59 | specific way. |
---|
60 | ELF files begin with an |
---|
61 | .Dq Executable Header , |
---|
62 | and may contain an optional |
---|
63 | .Dq Program Header Table , |
---|
64 | and optional data in the form of ELF |
---|
65 | .Dq sections . |
---|
66 | A |
---|
67 | .Dq Section Header Table |
---|
68 | describes the content of the data in these sections. |
---|
69 | .Pp |
---|
70 | ELF objects have an associated |
---|
71 | .Dq "ELF class" |
---|
72 | which denotes the natural machine word size for the architecture |
---|
73 | the object is associated with. |
---|
74 | Objects for 32 bit architectures have an ELF class of |
---|
75 | .Dv ELFCLASS32 . |
---|
76 | Objects for 64 bit architectures have an ELF class of |
---|
77 | .Dv ELFCLASS64 . |
---|
78 | .Pp |
---|
79 | ELF objects also have an associated |
---|
80 | .Dq endianness |
---|
81 | which denotes the endianness of the machine architecture associated |
---|
82 | with the object. |
---|
83 | This may be |
---|
84 | .Dv ELFDATA2LSB |
---|
85 | for little-endian architectures and |
---|
86 | .Dv ELFDATA2MSB |
---|
87 | for big-endian architectures. |
---|
88 | .Pp |
---|
89 | ELF objects are also associated with an API version number. |
---|
90 | This version number determines the layout of the individual components |
---|
91 | of an ELF file and the semantics associated with these. |
---|
92 | .Ss Data Representation And Translation |
---|
93 | The |
---|
94 | .Xr ELF 3 |
---|
95 | library distinguishes between |
---|
96 | .Dq native |
---|
97 | representations of ELF data structures and their |
---|
98 | .Dq file |
---|
99 | representations. |
---|
100 | .Pp |
---|
101 | An application would work with ELF data in its |
---|
102 | .Dq native |
---|
103 | representation, i.e., using the native byteorder and alignment mandated |
---|
104 | by the processor the application is running on. |
---|
105 | The |
---|
106 | .Dq file |
---|
107 | representation of the same data could use a different byte ordering |
---|
108 | and follow different constraints on object alignment than these native |
---|
109 | constraints. |
---|
110 | .Pp |
---|
111 | Accordingly, the |
---|
112 | .Xr ELF 3 |
---|
113 | library offers translation facilities |
---|
114 | .Xr ( elf32_xlatetof 3 , |
---|
115 | .Xr elf32_xlatetom 3 , |
---|
116 | .Xr elf64_xlatetof 3 |
---|
117 | and |
---|
118 | .Xr elf64_xlatetom 3 ) |
---|
119 | to and from these |
---|
120 | representations and also provides higher-level APIs that retrieve and store |
---|
121 | data from the ELF object in a transparent manner. |
---|
122 | .Ss Library Working Version |
---|
123 | Conceptually, there are three version numbers associated with an |
---|
124 | application using the ELF library to manipulate ELF objects: |
---|
125 | .Bl -bullet -compact -offset indent |
---|
126 | .It |
---|
127 | The ELF version that the application was compiled against. |
---|
128 | This version determines the ABI expected by the application. |
---|
129 | .It |
---|
130 | The ELF version of the ELF object being manipulated by the |
---|
131 | application through the ELF library. |
---|
132 | .It |
---|
133 | The ELF version (or set of versions) supported by the ELF library itself. |
---|
134 | .El |
---|
135 | .Pp |
---|
136 | In order to facilitate working with ELF objects of differing versions, |
---|
137 | the ELF library requires the application to call the |
---|
138 | .Fn elf_version |
---|
139 | function before invoking many of its operations, in order to inform |
---|
140 | the library of the application's desired working version. |
---|
141 | .Pp |
---|
142 | In the current implementation, all three versions have to be |
---|
143 | .Dv EV_CURRENT . |
---|
144 | .Ss Namespace use |
---|
145 | The ELF library uses the following prefixes: |
---|
146 | .Bl -tag -width "ELF_F_*" |
---|
147 | .It Dv elf_ |
---|
148 | Used for class-independent functions. |
---|
149 | .It Dv elf32_ |
---|
150 | Used for functions working with 32 bit ELF objects. |
---|
151 | .It Dv elf64_ |
---|
152 | Used for functions working with 64 bit ELF objects. |
---|
153 | .It Dv Elf_ |
---|
154 | Used for class-independent data types. |
---|
155 | .It Dv ELF_C_ |
---|
156 | Used for command values used in a few functions. |
---|
157 | These symbols are defined as members of the |
---|
158 | .Vt Dv Elf_Cmd |
---|
159 | enumeration. |
---|
160 | .It Dv ELF_E_ |
---|
161 | Used for error numbers. |
---|
162 | .It Dv ELF_F_ |
---|
163 | Used for flags. |
---|
164 | .It Dv ELF_K_ |
---|
165 | These constants define the kind of file associated with an ELF |
---|
166 | descriptor. |
---|
167 | See |
---|
168 | .Xr elf_kind 3 . |
---|
169 | The symbols are defined by the |
---|
170 | .Vt Elf_Kind |
---|
171 | enumeration. |
---|
172 | .It Dv ELF_T_ |
---|
173 | These values are defined by the |
---|
174 | .Vt Elf_Type |
---|
175 | enumeration, and denote the types of ELF data structures |
---|
176 | that can be present in an ELF object. |
---|
177 | .El |
---|
178 | .Pp |
---|
179 | In addition, the library uses symbols with prefixes |
---|
180 | .Dv _ELF |
---|
181 | and |
---|
182 | .Dv _libelf |
---|
183 | for its internal use. |
---|
184 | .Ss Descriptors |
---|
185 | Applications communicate with the library using descriptors. |
---|
186 | These are: |
---|
187 | .Bl -tag -width ".Vt Elf_Data" |
---|
188 | .It Vt Elf |
---|
189 | An |
---|
190 | .Vt Elf |
---|
191 | descriptor represents an ELF object or an |
---|
192 | .Xr ar 1 |
---|
193 | archive. |
---|
194 | It is allocated using one of the |
---|
195 | .Fn elf_begin |
---|
196 | or |
---|
197 | .Fn elf_memory |
---|
198 | functions. |
---|
199 | An |
---|
200 | .Vt Elf |
---|
201 | descriptor can be used to read and write data to an ELF file. |
---|
202 | An |
---|
203 | .Vt Elf |
---|
204 | descriptor can be associated with zero or more |
---|
205 | .Vt Elf_Scn |
---|
206 | section descriptors. |
---|
207 | .Pp |
---|
208 | Given an ELF descriptor, the application may retrieve the ELF |
---|
209 | object's class-dependent |
---|
210 | .Dq "Executable Header" |
---|
211 | structures using the |
---|
212 | .Fn elf32_getehdr |
---|
213 | or |
---|
214 | .Fn elf64_getehdr |
---|
215 | functions. |
---|
216 | A new Ehdr structure may be allocated using the |
---|
217 | .Fn elf64_newehdr |
---|
218 | or |
---|
219 | .Fn elf64_newehdr |
---|
220 | functions. |
---|
221 | .Pp |
---|
222 | The |
---|
223 | .Dq "Program Header Table" |
---|
224 | associated with an ELF descriptor may be allocated using the |
---|
225 | .Fn elf32_getphdr |
---|
226 | or |
---|
227 | .Fn elf64_getphdr |
---|
228 | functions. |
---|
229 | A new program header table may be allocated or an existing table |
---|
230 | resized using the |
---|
231 | .Fn elf32_newphdr |
---|
232 | or |
---|
233 | .Fn elf64_newphdr |
---|
234 | functions. |
---|
235 | .Pp |
---|
236 | The |
---|
237 | .Vt Elf |
---|
238 | structure is opaque and has no members visible to the |
---|
239 | application. |
---|
240 | .\" TODO describe the Elf_Arhdr and Elf_Arsym structures. |
---|
241 | .It Vt Elf_Data |
---|
242 | An |
---|
243 | .Vt Elf_Data |
---|
244 | data structure describes an individual chunk of a ELF file as |
---|
245 | represented in memory. |
---|
246 | It has the following application-visible members: |
---|
247 | .Bl -tag -width ".Vt unsigned int d_version" -compact |
---|
248 | .It Vt "uint64_t d_align" |
---|
249 | The in-file alignment of the data buffer within its containing ELF section. |
---|
250 | This value must be non-zero and a power of two. |
---|
251 | .It Vt "void *d_buf" |
---|
252 | A pointer to data in memory. |
---|
253 | .It Vt "uint64_t d_off" |
---|
254 | The offset with the containing section where this descriptors data |
---|
255 | would be placed. |
---|
256 | This field will be computed by the library unless the application |
---|
257 | requests full control of the ELF object's layout. |
---|
258 | .It Vt "uint64_t d_size" |
---|
259 | The number of bytes of data in this descriptor. |
---|
260 | .It Vt "Elf_Type d_type" |
---|
261 | The ELF type (see below) of the data in this descriptor. |
---|
262 | .It Vt "unsigned int d_version" |
---|
263 | The operating version for the data in this buffer. |
---|
264 | .El |
---|
265 | .Pp |
---|
266 | .Vt Elf_Data |
---|
267 | descriptors are usually associated with |
---|
268 | .Vt Elf_Scn |
---|
269 | descriptors. |
---|
270 | Existing data descriptors associated with an ELF section may be |
---|
271 | structures are retrieved using the |
---|
272 | .Fn elf_getdata |
---|
273 | and |
---|
274 | .Fn elf_rawdata |
---|
275 | functions. |
---|
276 | The |
---|
277 | .Fn elf_newdata |
---|
278 | function may be used to attach new data descriptors to an ELF section. |
---|
279 | .It Vt Elf_Scn |
---|
280 | .Vt Elf_Scn |
---|
281 | descriptors represent a section in an ELF object. |
---|
282 | .Pp |
---|
283 | They are retrieved using the |
---|
284 | .Fn elf_getscn |
---|
285 | function. |
---|
286 | An application may iterate through the existing sections of an ELF |
---|
287 | object using the |
---|
288 | .Fn elf_nextscn |
---|
289 | function. |
---|
290 | New sections may be allocated using the |
---|
291 | .Fn elf_newscn |
---|
292 | function. |
---|
293 | .Pp |
---|
294 | The |
---|
295 | .Vt Elf_Scn |
---|
296 | descriptor is opaque and contains no application modifiable fields. |
---|
297 | .El |
---|
298 | .Ss Supported Elf Types |
---|
299 | The following ELF datatypes are supported by the library. |
---|
300 | .Pp |
---|
301 | .Bl -tag -width ".Dv ELF_T_SYMINFO" -compact |
---|
302 | .It Dv ELF_T_ADDR |
---|
303 | Machine addresses. |
---|
304 | .It Dv ELF_T_BYTE |
---|
305 | Byte data. |
---|
306 | The library will not attempt to translate byte data. |
---|
307 | .It Dv ELF_T_CAP |
---|
308 | Software and hardware capability records. |
---|
309 | .It Dv ELF_T_DYN |
---|
310 | Records used in a section of type |
---|
311 | .Dv SHT_DYNAMIC . |
---|
312 | .It Dv ELF_T_EHDR |
---|
313 | ELF executable header. |
---|
314 | .It Dv ELF_T_GNUHASH |
---|
315 | GNU-style hash tables. |
---|
316 | .It Dv ELF_T_HALF |
---|
317 | 16-bit unsigned words. |
---|
318 | .It Dv ELF_T_LWORD |
---|
319 | 64 bit unsigned words. |
---|
320 | .It Dv ELF_T_MOVE |
---|
321 | ELF Move records. |
---|
322 | .\".It Dv ELF_T_MOVEP |
---|
323 | .\" As yet unsupported. |
---|
324 | .It Dv ELF_T_NOTE |
---|
325 | ELF Note structures. |
---|
326 | .It Dv ELF_T_OFF |
---|
327 | File offsets. |
---|
328 | .It Dv ELF_T_PHDR |
---|
329 | ELF program header table entries. |
---|
330 | .It Dv ELF_T_REL |
---|
331 | ELF relocation entries. |
---|
332 | .It Dv ELF_T_RELA |
---|
333 | ELF relocation entries with addends. |
---|
334 | .It Dv ELF_T_SHDR |
---|
335 | ELF section header entries. |
---|
336 | .It Dv ELF_T_SWORD |
---|
337 | Signed 32-bit words. |
---|
338 | .It Dv ELF_T_SXWORD |
---|
339 | Signed 64-bit words. |
---|
340 | .It Dv ELF_T_SYMINFO |
---|
341 | ELF symbol information. |
---|
342 | .It Dv ELF_T_SYM |
---|
343 | ELF symbol table entries. |
---|
344 | .It Dv ELF_T_VDEF |
---|
345 | Symbol version definition records. |
---|
346 | .It Dv ELF_T_VNEED |
---|
347 | Symbol version requirement records. |
---|
348 | .It Dv ELF_T_WORD |
---|
349 | Unsigned 32-bit words. |
---|
350 | .It Dv ELF_T_XWORD |
---|
351 | Unsigned 64-bit words. |
---|
352 | .El |
---|
353 | .Pp |
---|
354 | The symbol |
---|
355 | .Dv ELF_T_NUM |
---|
356 | denotes the number of Elf types known to the library. |
---|
357 | .Pp |
---|
358 | The following table shows the mapping between ELF section types |
---|
359 | defined in |
---|
360 | .Xr elf 5 |
---|
361 | and the types supported by the library. |
---|
362 | .Bl -column ".Dv SHT_PREINIT_ARRAY" ".Dv ELF_T_SYMINFO" |
---|
363 | .It Em Section Type Ta Em "Library Type" Ta Em Description |
---|
364 | .It Dv SHT_DYNAMIC Ta Dv ELF_T_DYN Ta Xo |
---|
365 | .Sq .dynamic |
---|
366 | section entries. |
---|
367 | .Xc |
---|
368 | .It Dv SHT_DYNSYM Ta Dv ELF_T_SYM Ta Symbols for dynamic linking. |
---|
369 | .It Dv SHT_FINI_ARRAY Ta Dv ELF_T_ADDR Ta Termination function pointers. |
---|
370 | .It Dv SHT_GROUP Ta Dv ELF_T_WORD Ta Section group marker. |
---|
371 | .It Dv SHT_HASH Ta Dv ELF_T_HASH Ta Symbol hashes. |
---|
372 | .It Dv SHT_INIT_ARRAY Ta Dv ELF_T_ADDR Ta Initialization function pointers. |
---|
373 | .It Dv SHT_NOBITS Ta Dv ELF_T_BYTE Ta Xo |
---|
374 | Empty sections. |
---|
375 | See |
---|
376 | .Xr elf 5 . |
---|
377 | .Xc |
---|
378 | .It Dv SHT_NOTE Ta Dv ELF_T_NOTE Ta ELF note records. |
---|
379 | .It Dv SHT_PREINIT_ARRAY Ta Dv ELF_T_ADDR Ta Pre-initialization function pointers. |
---|
380 | .It Dv SHT_PROGBITS Ta Dv ELF_T_BYTE Ta Machine code. |
---|
381 | .It Dv SHT_REL Ta Dv ELF_T_REL Ta ELF relocation records. |
---|
382 | .It Dv SHT_RELA Ta Dv ELF_T_RELA Ta Relocation records with addends. |
---|
383 | .It Dv SHT_STRTAB Ta Dv ELF_T_BYTE Ta String tables. |
---|
384 | .It Dv SHT_SYMTAB Ta Dv ELF_T_SYM Ta Symbol tables. |
---|
385 | .It Dv SHT_SYMTAB_SHNDX Ta Dv ELF_T_WORD Ta Used with extended section numbering. |
---|
386 | .It Dv SHT_GNU_verdef Ta Dv ELF_T_VDEF Ta Symbol version definitions. |
---|
387 | .It Dv SHT_GNU_verneed Ta Dv ELF_T_VNEED Ta Symbol versioning requirements. |
---|
388 | .It Dv SHT_GNU_versym Ta Dv ELF_T_HALF Ta Version symbols. |
---|
389 | .It Dv SHT_SUNW_move Ta Dv ELF_T_MOVE Ta ELF move records. |
---|
390 | .It Dv SHT_SUNW_syminfo Ta Dv ELF_T_SYMINFO Ta Additional symbol flags. |
---|
391 | .El |
---|
392 | .TE |
---|
393 | .Ss Functional Grouping |
---|
394 | This section contains a brief overview of the available functionality |
---|
395 | in the ELF library. |
---|
396 | Each function listed here is described further in its own manual page. |
---|
397 | .Bl -tag -width indent |
---|
398 | .It "Archive Access" |
---|
399 | .Bl -tag -compact |
---|
400 | .It Fn elf_getarsym |
---|
401 | Retrieve the archive symbol table. |
---|
402 | .It Fn elf_getarhdr |
---|
403 | Retrieve the archive header for an object. |
---|
404 | .It Fn elf_getbase |
---|
405 | Retrieve the offset of a member inside an archive. |
---|
406 | .It Fn elf_next |
---|
407 | Iterate through an |
---|
408 | .Xr ar 1 |
---|
409 | archive. |
---|
410 | .It Fn elf_rand |
---|
411 | Random access inside an |
---|
412 | .Xr ar 1 |
---|
413 | archive. |
---|
414 | .El |
---|
415 | .It "Data Structures" |
---|
416 | .Bl -tag -compact |
---|
417 | .It Fn elf_getdata |
---|
418 | Retrieve translated data for an ELF section. |
---|
419 | .It Fn elf_getscn |
---|
420 | Retrieve the section descriptor for a named section. |
---|
421 | .It Fn elf_ndxscn |
---|
422 | Retrieve the index for a section. |
---|
423 | .It Fn elf_newdata |
---|
424 | Add a new |
---|
425 | .Vt Elf_Data |
---|
426 | descriptor to an ELF section. |
---|
427 | .It Fn elf_newscn |
---|
428 | Add a new section descriptor to an ELF descriptor. |
---|
429 | .It Fn elf_nextscn |
---|
430 | Iterate through the sections in an ELF object. |
---|
431 | .It Fn elf_rawdata |
---|
432 | Retrieve untranslated data for an ELF sectino. |
---|
433 | .It Fn elf_rawfile |
---|
434 | Return a pointer to the untranslated file contents for an ELF object. |
---|
435 | .It Fn elf32_getehdr , Fn elf64_getehdr |
---|
436 | Retrieve the Executable Header in an ELF object. |
---|
437 | .It Fn elf32_getphdr , Fn elf64_getphdr |
---|
438 | Retrieve the Program Header Table in an ELF object. |
---|
439 | .It Fn elf32_getshdr , Fn elf64_getshdr |
---|
440 | Retrieve the ELF section header associated with an |
---|
441 | .Vt Elf_Scn |
---|
442 | descriptor. |
---|
443 | .It Fn elf32_newehdr , Fn elf64_newehdr |
---|
444 | Allocate an Executable Header in an ELF object. |
---|
445 | .It Fn elf32_newphdr , Fn elf64_newphdr |
---|
446 | Allocate or resize the Program Header Table in an ELF object. |
---|
447 | .El |
---|
448 | .It "Data Translation" |
---|
449 | .Bl -tag -compact |
---|
450 | .It Fn elf32_xlatetof , Fn elf64_xlatetof |
---|
451 | Translate an ELF data structure from its native representation to its |
---|
452 | file representation. |
---|
453 | .It Fn elf32_xlatetom , Fn elf64_xlatetom |
---|
454 | Translate an ELF data structure from its file representation to a |
---|
455 | native representation. |
---|
456 | .El |
---|
457 | .It "Error Reporting" |
---|
458 | .Bl -tag -compact |
---|
459 | .It Fn elf_errno |
---|
460 | Retrieve the current error. |
---|
461 | .It Fn elf_errmsg |
---|
462 | Retrieve a human readable description of the current error. |
---|
463 | .El |
---|
464 | .It "Initialization" |
---|
465 | .Bl -tag -compact |
---|
466 | .It Fn elf_begin |
---|
467 | Opens an |
---|
468 | .Xr ar 1 |
---|
469 | archive or ELF object given a file descriptor. |
---|
470 | .It Fn elf_end |
---|
471 | Close an ELF descriptor and release all its resources. |
---|
472 | .It Fn elf_memory |
---|
473 | Opens an |
---|
474 | .Xr ar 1 |
---|
475 | archive or ELF object present in a memory arena. |
---|
476 | .It Fn elf_version |
---|
477 | Sets the operating version. |
---|
478 | .El |
---|
479 | .It "IO Control" |
---|
480 | .Bl -tag -width ".Fn elf_setshstrndx" -compact |
---|
481 | .It Fn elf_cntl |
---|
482 | Manage the association between and ELF descriptor and its underlying file. |
---|
483 | .It Fn elf_flagdata |
---|
484 | Mark an |
---|
485 | .Vt Elf_Data |
---|
486 | descriptor as dirty. |
---|
487 | .It Fn elf_flagehdr |
---|
488 | Mark the ELF Executable Header in an ELF descriptor as dirty. |
---|
489 | .It Fn elf_flagphdr |
---|
490 | Mark the ELF Program Header Table in an ELF descriptor as dirty. |
---|
491 | .It Fn elf_flagscn |
---|
492 | Mark an |
---|
493 | .Vt Elf_Scn |
---|
494 | descriptor as dirty. |
---|
495 | .It Fn elf_flagshdr |
---|
496 | Mark an ELF Section Header as dirty. |
---|
497 | .It Fn elf_setshstrndx |
---|
498 | Set the index of the section name string table for the ELF object. |
---|
499 | .It Fn elf_update |
---|
500 | Recompute ELF object layout and optionally write the modified object |
---|
501 | back to the underlying file. |
---|
502 | .El |
---|
503 | .It "Queries" |
---|
504 | .Bl -tag -width ".Fn elf_getshstrndx" -compact |
---|
505 | .It Fn elf32_checksum , Fn elf64_checkum |
---|
506 | Compute checksum of an ELF object. |
---|
507 | .It Fn elf_getident |
---|
508 | Retrieve the identification bytes for an ELF object. |
---|
509 | .It Fn elf_getshnum |
---|
510 | Retrieve the number of sections in an ELF object. |
---|
511 | .It Fn elf_getshstrndx |
---|
512 | Retrieve the section index of the section name string table in |
---|
513 | an ELF object. |
---|
514 | .It Fn elf_hash |
---|
515 | Compute the ELF hash value of a string. |
---|
516 | .It Fn elf_kind |
---|
517 | Query the kind of object associated with an ELF descriptor. |
---|
518 | .It Fn elf32_fsize , Fn elf64_fsize |
---|
519 | Return the size of the file representation of an ELF type. |
---|
520 | .El |
---|
521 | .El |
---|
522 | .Ss Controlling ELF Object Layout |
---|
523 | In the usual mode of operation, library will compute section |
---|
524 | offsets and alignments based on the contents of an ELF descriptor's |
---|
525 | sections without need for further intervention by the |
---|
526 | application. |
---|
527 | .Pp |
---|
528 | However, if the application wishes to take complete charge of the |
---|
529 | layout of the ELF file, it may set the |
---|
530 | .Dv ELF_F_LAYOUT |
---|
531 | flag on an ELF descriptor using |
---|
532 | .Xr elf_flagelf 3 , |
---|
533 | following which the library will use the data offsets and alignments |
---|
534 | specified by the application when laying out the file. |
---|
535 | Application control of file layout is described further in the |
---|
536 | .Xr elf_update 3 |
---|
537 | manual page. |
---|
538 | .Pp |
---|
539 | Gaps in between sections will be filled with the fill character |
---|
540 | set by function |
---|
541 | .Fn elf_fill . |
---|
542 | .Ss Error Handling |
---|
543 | In case an error is encountered, these library functions set an |
---|
544 | internal error number and signal the presence of the error by |
---|
545 | returning an special return value. |
---|
546 | The application can check the |
---|
547 | current error number by calling |
---|
548 | .Xr elf_errno 3 . |
---|
549 | A human readable description of the recorded error is available by |
---|
550 | calling |
---|
551 | .Xr elf_errmsg 3 . |
---|
552 | .Ss Memory Management Rules |
---|
553 | The library keeps track of all |
---|
554 | .Vt Elf_Scn |
---|
555 | and |
---|
556 | .Vt Elf_Data |
---|
557 | descriptors associated with an ELF descriptor and recovers them |
---|
558 | when the descriptor is closed using |
---|
559 | .Xr elf_end 3 . |
---|
560 | Thus the application must not call |
---|
561 | .Xr free 3 |
---|
562 | on data structures allocated by the ELF library. |
---|
563 | .Pp |
---|
564 | Conversely the library will not |
---|
565 | free data that it has not allocated. |
---|
566 | As an example, an application may call |
---|
567 | .Xr elf_newdata 3 |
---|
568 | to allocate a new |
---|
569 | .Vt Elf_Data |
---|
570 | descriptor and can set the |
---|
571 | .Va d_off |
---|
572 | member of the descriptor to point to a region of memory allocated |
---|
573 | using |
---|
574 | .Xr malloc 3 . |
---|
575 | It is the applications responsibility to free this arena, though the |
---|
576 | library will reclaim the space used by the |
---|
577 | .Vt Elf_Data |
---|
578 | descriptor itself. |
---|
579 | .Sh SEE ALSO |
---|
580 | .Xr gelf 3 , |
---|
581 | .Xr elf 5 |
---|
582 | .Sh HISTORY |
---|
583 | The original ELF(3) API was developed for Unix System V. |
---|
584 | The current implementation of the ELF(3) API appeared in |
---|
585 | .Fx 7.0 . |
---|
586 | .Sh AUTHORS |
---|
587 | The ELF library was written by |
---|
588 | .An "Joseph Koshy" |
---|
589 | .Aq jkoshy@FreeBSD.org . |
---|