Merge commit 'b31ca922c7346747131aed07c0c171ec2f573aac' into merges
[unleashed.git] / share / man / man3elf / gelf.3elf
blobcbddcc37e1520d78b0cd77f078e037637a82944d
1 '\" te
2 .\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved
3 .\" 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.
4 .\" 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.
5 .\" 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]
6 .TH GELF 3ELF "Jun 8, 2004"
7 .SH NAME
8 gelf, gelf_checksum, gelf_fsize, gelf_getcap, gelf_getclass, gelf_getdyn,
9 gelf_getehdr, gelf_getmove, gelf_getphdr, gelf_getrel, gelf_getrela,
10 gelf_getshdr, gelf_getsym, gelf_getsyminfo, gelf_getsymshndx, gelf_newehdr,
11 gelf_newphdr, gelf_update_cap, gelf_update_dyn, gelf_update_ehdr,
12 gelf_update_getmove, gelf_update_move, gelf_update_phdr, gelf_update_rel,
13 gelf_update_rela, gelf_update_shdr, gelf_update_sym, gelf_update_symshndx,
14 gelf_update_syminfo, gelf_xlatetof, gelf_xlatetom \- generic class-independent
15 ELF interface
16 .SH SYNOPSIS
17 .LP
18 .nf
19 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR...  \fB\(milelf\fR [ \fIlibrary\fR... ]
20 #include <gelf.h>
22 \fBlong\fR \fBgelf_checksum\fR(\fBElf *\fR\fIelf\fR);
23 .fi
25 .LP
26 .nf
27 \fBsize_t\fR \fBgelf_fsize\fR(\fBElf *\fR\fIelf\fR, \fBElf_Type\fR \fItype\fR, \fBsize_t\fR \fIcnt\fR, \fBunsigned\fR \fIver\fR);
28 .fi
30 .LP
31 .nf
32 \fBint\fR \fBgelf_getcap\fR(\fBElf_Data *\fR\fIsrc\fR, \fBint\fR \fIndx\fR, \fBGElf_Cap *\fR\fIdst\fR);
33 .fi
35 .LP
36 .nf
37 \fBint\fR \fBgelf_getclass\fR(\fBElf *\fR\fIelf\fR);
38 .fi
40 .LP
41 .nf
42 \fBGElf_Dyn *\fR\fBgelf_getdyn\fR(\fBElf_Data *\fR\fIsrc\fR, \fBint\fR \fIndx\fR, \fBGElf_Dyn *\fR\fIdst\fR);
43 .fi
45 .LP
46 .nf
47 \fBGElf_Ehdr *\fR\fBgelf_getehdr\fR(\fBElf *\fR\fIelf\fR, \fBGElf_Ehdr *\fR\fIdst\fR);
48 .fi
50 .LP
51 .nf
52 \fBGElf_Move *\fR\fBgelf_getmove\fR(\fBElf_Data *\fR\fIsrc\fR, \fBint\fR \fIndx\fR, \fBGElf_Move *\fR\fIdst\fR);
53 .fi
55 .LP
56 .nf
57 \fBGElf_Phdr *\fR\fBgelf_getphdr\fR(\fBElf *\fR\fIelf\fR, \fBint\fR \fIndx\fR, \fBGElf_Phdr *\fR\fIdst\fR);
58 .fi
60 .LP
61 .nf
62 \fBGElf_Rel *\fR\fBgelf_getrel\fR(\fBElf_Data *\fR\fIsrc\fR, \fBint\fR \fIndx\fR, \fBGElf_Rel *\fR\fIdst\fR);
63 .fi
65 .LP
66 .nf
67 \fBGElf_Rela *\fR\fBgelf_getrela\fR(\fBElf_Data *\fR\fIsrc\fR, \fBint\fR \fIndx\fR, \fBGElf_Rela *\fR\fIdst\fR);
68 .fi
70 .LP
71 .nf
72 \fBGElf_Shdr *\fR\fBgelf_getshdr\fR(\fBElf_Scn *\fR\fIscn\fR, \fBGElf_Shdr *\fR\fIdst\fR);
73 .fi
75 .LP
76 .nf
77 \fBGElf_Sym *\fR\fBgelf_getsym\fR(\fBElf_Data *\fR\fIsrc\fR, \fBint\fR \fIndx\fR, \fBGElf_Sym *\fR\fIdst\fR);
78 .fi
80 .LP
81 .nf
82 \fBGElf_Syminfo *\fR\fBgelf_getsyminfo\fR(\fBElf_Data *\fR\fIsrc\fR, \fBint\fR \fIndx\fR, \fBGElf_Syminfo *\fR\fIdst\fR);
83 .fi
85 .LP
86 .nf
87 \fBGElf_Sym *\fR\fBgelf_getsymshndx\fR(\fBElf_Data *\fR\fIsymsrc\fR, \fBElf_Data *\fR\fIshndxsrc\fR,
88      \fBint\fR \fIndx\fR, \fBGElf_Sym *\fR\fIsymdst\fR, \fBElf32_Word *\fR\fIshndxdst\fR);
89 .fi
91 .LP
92 .nf
93 \fBunsigned long\fR \fBgelf_newehdr\fR(\fBElf *\fR\fIelf\fR, \fBint\fR \fIclass\fR);
94 .fi
96 .LP
97 .nf
98 \fBunsigned long\fR \fBgelf_newphdr\fR(\fBElf *\fR\fIelf\fR, \fBsize_t\fR \fIphnum\fR);
99 .fi
103 \fBint\fR \fBgelf_update_cap\fR(\fBElf_Data *\fR\fIdst\fR, \fBint\fR \fIndx\fR, \fBGElf_Cap *\fR\fIsrc\fR);
108 \fBint\fR \fBgelf_update_dyn\fR(\fBElf_Data *\fR\fIdst\fR, \fBint\fR \fIndx\fR, \fBGElf_Dyn *\fR\fIsrc\fR);
113 \fBint\fR \fBgelf_update_ehdr\fR(\fBElf *\fR\fIelf\fR, \fBGElf_Ehdr *\fR\fIsrc\fR);
118 \fBint\fR \fBgelf_update_move\fR(\fBElf_Data *\fR\fIdst\fR, \fBint\fR \fIndx\fR, \fBGElf_Move *\fR\fIsrc\fR);
123 \fBint\fR \fBgelf_update_phdr\fR(\fBElf *\fR\fIelf\fR, \fBint\fR \fIndx\fR, \fBGElf_Phdr *\fR\fIsrc\fR);
128 \fBint\fR \fBgelf_update_rel\fR(\fBElf_Data *\fR\fIdst\fR, \fBint\fR \fIndx\fR, \fBGElf_Rel *\fR\fIsrc\fR);
133 \fBint\fR \fBgelf_update_rela\fR(\fBElf_Data *\fR\fIdst\fR, \fBint\fR \fIndx\fR, \fBGElf_Rela *\fR\fIsrc\fR);
138 \fBint\fR \fBgelf_update_shdr\fR(\fBElf_Scn *\fR\fIdst\fR, \fBGElf_Shdr *\fR\fIsrc\fR);
143 \fBint\fR \fBgelf_update_sym\fR(\fBElf_Data *\fR\fIdst\fR, \fBint\fR \fIndx\fR, \fBGElf_Sym *\fR\fIsrc\fR);
148 \fBint\fR \fBgelf_update_syminfo\fR(\fBElf_Data *\fR\fIdst\fR, \fBint\fR \fIndx\fR, \fBGElf_Syminfo *\fR\fIsrc\fR);
153 \fBint\fR \fBgelf_update_symshndx\fR(\fBElf_Data *\fR\fIsymdst\fR, \fBElf_Data *\fR\fIshndxdst\fR, \fBint\fR \fIndx\fR,
154      \fBGElf_Sym *\fR\fIsymsrc\fR, \fBElf32_Word\fR \fIshndxsrc\fR);
159 \fBElf_Data *\fR\fBgelf_xlatetof\fR(\fBElf *\fR\fIelf\fR, \fBElf_Data *\fR\fIdst\fR, \fBconst Elf_Data *\fR\fIsrc\fR,
160      \fBunsigned\fR \fIencode\fR);
165 \fBElf_Data *\fR\fBgelf_xlatetom\fR(\fBElf *\fR\fIelf\fR, \fBElf_Data *\fR\fIdst\fR, \fBconst Elf_Data *\fR\fIsrc\fR,
166      \fBunsigned\fR \fIencode\fR);
169 .SH DESCRIPTION
172 \fBGElf\fR is a generic, \fBELF\fR class-independent \fBAPI\fR for manipulating
173 \fBELF\fR object files. \fBGElf\fR provides a single, common interface for
174 handling 32-bit and 64-bit \fBELF\fR format object files. \fBGElf\fR is a
175 translation layer between the application and the class-dependent parts of the
176 \fBELF\fR library. Thus, the application can use \fBGElf\fR, which in turn,
177 will call the corresponding \fBelf32_\fR or \fBelf64_\fR functions on behalf of
178 the application. The data structures returned are all large enough to hold
179 32-bit and 64-bit data.
182 \fBGElf\fR provides a simple, class-independent layer of indirection over the
183 class-dependent \fBELF32\fR and \fBELF64\fR \fBAPI\fR's. \fBGElf\fR is
184 stateless, and may be used along side the \fBELF32\fR and \fBELF64\fR
185 \fBAPI\fR's.
188 \fBGElf\fR always returns a copy of the underlying \fBELF32\fR or \fBELF64\fR
189 structure, and therefore the programming practice of using the address of an
190 \fBELF\fR header as the base offset for the \fBELF\fR's mapping into memory
191 should be avoided. Also, data accessed by type-casting the \fBElf_Data\fR
192 buffer to a class-dependent type and treating it like an array, for example, a
193 symbol table, will not work under \fBGElf\fR, and the \fBgelf_get\fR functions
194 must be used instead. See the EXAMPLE section.
197 Programs that create or modify \fBELF\fR files using \fBlibelf\fR(3LIB) need to
198 perform an extra step when using \fBGElf\fR. Modifications to \fBGElf\fR values
199 must be explicitly flushed to the underlying \fBELF32\fR or \fBELF64\fR
200 structures by way of the \fBgelf_update_\fR interfaces. Use of \fBelf_update\fR
201 or \fBelf_flagelf\fR and the like remains the same.
204 The sizes of versioning structures remain the same between \fBELF32\fR and
205 \fBELF64\fR. The \fBGElf\fR \fBAPI\fR only defines types for versioning, rather
206 than a functional \fBAPI\fR. The processing of versioning information will stay
207 the same in the \fBGElf\fR environment as it was in the class-dependent
208 \fBELF\fR environment.
209 .SS "List of Functions"
211 .ne 2
213 \fB\fBgelf_checksum()\fR\fR
215 .RS 26n
216 An analog to \fBelf32_checksum\fR(3ELF) and \fBelf64_checksum\fR(3ELF).
220 .ne 2
222 \fB\fBgelf_fsize()\fR\fR
224 .RS 26n
225 An analog to \fBelf32_fsize\fR(3ELF) and \fBelf64_fsize\fR(3ELF).
229 .ne 2
231 \fB\fBgelf_getcap()\fR\fR
233 .RS 26n
234 Retrieves the \fBElf32_Cap\fR or \fBElf64_Cap\fR information from the
235 capability table at the given index. \fBdst\fR points to the location where the
236 \fBGElf_Cap\fR capability entry is stored.
240 .ne 2
242 \fB\fBgelf_getclass()\fR\fR
244 .RS 26n
245 Returns one of the constants \fBELFCLASS32\fR, \fBELFCLASS64\fR or
246 \fBELFCLASSNONE\fR.
250 .ne 2
252 \fB\fBgelf_getdyn()\fR\fR
254 .RS 26n
255 Retrieves the \fBElf32_Dyn\fR or \fBElf64_Dyn\fR information from the dynamic
256 table at the given index. \fBdst\fR points to the location where the
257 \fBGElf_Dyn\fR dynamic entry is stored.
261 .ne 2
263 \fB\fBgelf_getehdr()\fR\fR
265 .RS 26n
266 An analog to \fBelf32_getehdr\fR(3ELF) and \fBelf64_getehdr\fR(3ELF). \fBdst\fR
267 points to the location where the \fBGElf_Ehdr\fR header is stored.
271 .ne 2
273 \fB\fBgelf_getmove()\fR\fR
275 .RS 26n
276 Retrieves the \fBElf32_Move\fR or \fBElf64_Move\fR information from the move
277 table at the given index. \fBdst\fR points to the location where the
278 \fBGElf_Move\fR move entry is stored.
282 .ne 2
284 \fB\fBgelf_getphdr()\fR\fR
286 .RS 26n
287 An analog to \fBelf32_getphdr\fR(3ELF) and \fBelf64_getphdr\fR(3ELF). \fBdst\fR
288 points to the location where the \fBGElf_Phdr\fR program header is stored.
292 .ne 2
294 \fB\fBgelf_getrel()\fR\fR
296 .RS 26n
297 Retrieves the \fBElf32_Rel\fR or \fBElf64_Rel\fR information from the
298 relocation table at the given index. \fBdst\fR points to the location where the
299 \fBGElf_Rel\fR relocation entry is stored.
303 .ne 2
305 \fB\fBgelf_getrela()\fR\fR
307 .RS 26n
308 Retrieves the \fBElf32_Rela\fR or \fBElf64_Rela\fR information from the
309 relocation table at the given index. \fBdst\fR points to the location where the
310 \fBGElf_Rela\fR relocation entry is stored.
314 .ne 2
316 \fB\fBgelf_getshdr()\fR\fR
318 .RS 26n
319 An analog to \fBelf32_getshdr\fR(3ELF) and \fBelf64_getshdr\fR(3ELF). \fBdst\fR
320 points to the location where the \fBGElf_Shdr\fR section header is stored.
324 .ne 2
326 \fB\fBgelf_getsym()\fR\fR
328 .RS 26n
329 Retrieves the \fBElf32_Sym\fR or \fBElf64_Sym\fR information from the symbol
330 table at the given index. \fBdst\fR points to the location where the
331 \fBGElf_Sym\fR symbol entry is stored.
335 .ne 2
337 \fB\fBgelf_getsyminfo()\fR\fR
339 .RS 26n
340 Retrieves the \fBElf32_Syminfo\fR or \fBElf64_Syminfo\fR information from the
341 relocation table at the given index. \fBdst\fR points to the location where the
342 \fBGElf_Syminfo\fR symbol information entry is stored.
346 .ne 2
348 \fB\fBgelf_getsymshndx()\fR\fR
350 .RS 26n
351 Provides an extension to \fBgelf_getsym()\fR that retrieves the \fBElf32_Sym\fR
352 or \fBElf64_Sym\fR information, and the section index from the symbol table at
353 the given index \fIndx\fR.
355 The symbols section index is typically recorded in the \fBst_shndx\fR field of
356 the symbols structure. However, a file that requires \fBELF\fR Extended
357 Sections may record an \fBst_shndx\fR of \fBSHN_XINDEX\fR indicating that the
358 section index must be obtained from an associated \fBSHT_SYMTAB_SHNDX\fR
359 section entry. If \fIxshndx\fR and \fIshndxdata\fR are non-null, the value
360 recorded at index \fIndx\fR of the \fBSHT_SYMTAB_SHNDX\fR table pointed to by
361 \fIshndxdata\fR is returned in \fIxshndx\fR. See USAGE.
365 .ne 2
367 \fB\fBgelf_newehdr()\fR\fR
369 .RS 26n
370 An analog to \fBelf32_newehdr\fR(3ELF) and \fBelf64_newehdr\fR(3ELF).
374 .ne 2
376 \fB\fBgelf_newphdr()\fR\fR
378 .RS 26n
379 An analog to \fBelf32_newphdr\fR(3ELF) and \fBelf64_newphdr\fR(3ELF).
383 .ne 2
385 \fB\fBgelf_update_cap()\fR\fR
387 .RS 26n
388 Copies the \fBGElf_Cap\fR information back into the underlying \fBElf32_Cap\fR
389 or \fBElf64_Cap\fR structure at the given index.
393 .ne 2
395 \fB\fBgelf_update_dyn()\fR\fR
397 .RS 26n
398 Copies the \fBGElf_Dyn\fR information back into the underlying \fBElf32_Dyn\fR
399 or \fBElf64_Dyn\fR structure at the given index.
403 .ne 2
405 \fB\fBgelf_update_ehdr()\fR\fR
407 .RS 26n
408 Copies the contents of the \fBGElf_Ehdr\fR \fBELF\fR header to the underlying
409 \fBElf32_Ehdr\fR or \fBElf64_Ehdr\fR structure.
413 .ne 2
415 \fB\fBgelf_update_move()\fR\fR
417 .RS 26n
418 Copies the \fBGElf_Move\fR information back into the underlying
419 \fBElf32_Move\fR or \fBElf64_Move\fR structure at the given index.
423 .ne 2
425 \fB\fBgelf_update_phdr()\fR\fR
427 .RS 26n
428 Copies of the contents of \fBGElf_Phdr\fR program header to underlying the
429 \fBElf32_Phdr\fR or \fBElf64_Phdr\fR structure.
433 .ne 2
435 \fB\fBgelf_update_rel()\fR\fR
437 .RS 26n
438 Copies the \fBGElf_Rel\fR information back into the underlying \fBElf32_Rel\fR
439 or \fBElf64_Rel\fR structure at the given index.
443 .ne 2
445 \fB\fBgelf_update_rela()\fR\fR
447 .RS 26n
448 Copies the \fBGElf_Rela\fR information back into the underlying
449 \fBElf32_Rela\fR or \fBElf64_Rela\fR structure at the given index.
453 .ne 2
455 \fB\fBgelf_update_shdr()\fR\fR
457 .RS 26n
458 Copies of the contents of \fBGElf_Shdr\fR section header to underlying the
459 \fBElf32_Shdr\fR or \fBElf64_Shdr\fR structure.
463 .ne 2
465 \fB\fBgelf_update_sym()\fR\fR
467 .RS 26n
468 Copies the \fBGElf_Sym\fR information back into the underlying \fBElf32_Sym\fR
469 or \fBElf64_Sym\fR structure at the given index.
473 .ne 2
475 \fB\fBgelf_update_syminfo()\fR\fR
477 .RS 26n
478 Copies the \fBGElf_Syminfo\fR information back into the underlying
479 \fBElf32_Syminfo\fR or \fBElf64_Syminfo\fR structure at the given index.
483 .ne 2
485 \fB\fBgelf_update_symshndx()\fR\fR
487 .RS 26n
488 Provides an extension to \fBgelf_update_sym()\fR that copies the \fBGElf_Sym\fR
489 information back into the \fBElf32_Sym\fR or \fBElf64_Sym\fR structure at the
490 given index \fIndx\fR, and copies the extended \fIxshndx\fR section index into
491 the \fBElf32_Word\fR at the given index \fIndx\fR in the buffer described by
492 \fBshndxdata\fR. See USAGE.
496 .ne 2
498 \fB\fBgelf_xlatetof()\fR\fR
500 .RS 26n
501 An analog to \fBelf32_xlatetof\fR(3ELF) and \fBelf64_xlatetof\fR(3ELF)
505 .ne 2
507 \fB\fBgelf_xlatetom()\fR\fR
509 .RS 26n
510 An analog to \fBelf32_xlatetom\fR(3ELF) and \fBelf64_xlatetom\fR(3ELF)
513 .SH RETURN VALUES
516 Upon failure, all \fBGElf\fR functions return \fB0\fR and set \fIelf_errno\fR.
517 See \fBelf_errno\fR(3ELF)
518 .SH EXAMPLES
520 \fBExample 1 \fRPrinting the ELF Symbol Table
522 .in +2
524 #include <stdio.h>
525 #include <sys/types.h>
526 #include <sys/stat.h>
527 #include <fcntl.h>
528 #include <libelf.h>
529 #include <gelf.h>
531 void
532 main(int argc, char **argv)
534     Elf         *elf;
535     Elf_Scn     *scn = NULL;
536     GElf_Shdr   shdr;
537     Elf_Data    *data;
538     int         fd, ii, count;
540     elf_version(EV_CURRENT);
542     fd = open(argv[1], O_RDONLY);
543     elf = elf_begin(fd, ELF_C_READ, NULL);
545     while ((scn = elf_nextscn(elf, scn)) != NULL) {
546         gelf_getshdr(scn, &shdr);
547         if (shdr.sh_type == SHT_SYMTAB) {
548             /* found a symbol table, go print it. */
549             break;
550         }
551     }
553     data = elf_getdata(scn, NULL);
554     count = shdr.sh_size / shdr.sh_entsize;
556     /* print the symbol names */
557     for (ii = 0; ii < count; ++ii) {
558         GElf_Sym sym;
559         gelf_getsym(data, ii, &sym);
560         printf("%s\en", elf_strptr(elf, shdr.sh_link, sym.st_name));
561     }
562     elf_end(elf);
563     close(fd);
566 .in -2
568 .SH USAGE
571 ELF Extended Sections are employed to allow an ELF file to contain more than
572 \fB0xff00\fR (\fBSHN_LORESERVE\fR) section. See the \fILinker and Libraries
573 Guide\fR for more information.
574 .SH FILES
576 .ne 2
578 \fB\fB/lib/libelf.so.1\fR\fR
580 .RS 23n
581 shared object
585 .ne 2
587 \fB\fB/lib/64/libelf.so.1\fR\fR
589 .RS 23n
590 64-bit shared object
593 .SH ATTRIBUTES
596 See \fBattributes\fR(5) for descriptions of the following attributes:
601 box;
602 c | c
603 l | l .
604 ATTRIBUTE TYPE  ATTRIBUTE VALUE
606 Interface Stability     Stable
608 MT Level        MT-Safe
611 .SH SEE ALSO
614 \fBelf\fR(3ELF), \fBelf32_checksum\fR(3ELF), \fBelf32_fsize\fR(3ELF),
615 \fBelf32_getehdr\fR(3ELF), \fBelf32_newehdr\fR(3ELF),
616 \fBelf32_getphdr\fR(3ELF), \fBelf32_newphdr\fR(3ELF),
617 \fBelf32_getshdr\fR(3ELF), \fBelf32_xlatetof\fR(3ELF),
618 \fBelf32_xlatetom\fR(3ELF), \fBelf_errno\fR(3ELF), \fBlibelf\fR(3LIB),
619 \fBattributes\fR(5)
622 \fILinker and Libraries Guide\fR