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

NAME

6       gelf,  gelf_checksum, gelf_fsize, gelf_getcap, gelf_getclass, gelf_get‐
7       dyn,    gelf_getehdr,    gelf_getmove,    gelf_getphdr,    gelf_getrel,
8       gelf_getrela,  gelf_getshdr,  gelf_getsym,  gelf_getsyminfo,  gelf_get‐
9       symshndx, gelf_newehdr, gelf_newphdr, gelf_update_cap, gelf_update_dyn,
10       gelf_update_ehdr,         gelf_update_getmove,        gelf_update_move,
11       gelf_update_phdr, gelf_update_rel, gelf_update_rela,  gelf_update_shdr,
12       gelf_update_sym,       gelf_update_symshndx,       gelf_update_syminfo,
13       gelf_xlatetof, gelf_xlatetom - generic class-independent ELF interface
14

SYNOPSIS

16       cc [ flag... ] file...  −lelf [ library... ]
17       #include <gelf.h>
18
19       long gelf_checksum(Elf *elf);
20
21
22       size_t gelf_fsize(Elf *elf, Elf_Type type, size_t cnt, unsigned ver);
23
24
25       int gelf_getcap(Elf_Data *src, int ndx, GElf_Cap *dst);
26
27
28       int gelf_getclass(Elf *elf);
29
30
31       GElf_Dyn *gelf_getdyn(Elf_Data *src, int ndx, GElf_Dyn *dst);
32
33
34       GElf_Ehdr *gelf_getehdr(Elf *elf, GElf_Ehdr *dst);
35
36
37       GElf_Move *gelf_getmove(Elf_Data *src, int ndx, GElf_Move *dst);
38
39
40       GElf_Phdr *gelf_getphdr(Elf *elf, int ndx, GElf_Phdr *dst);
41
42
43       GElf_Rel *gelf_getrel(Elf_Data *src, int ndx, GElf_Rel *dst);
44
45
46       GElf_Rela *gelf_getrela(Elf_Data *src, int ndx, GElf_Rela *dst);
47
48
49       GElf_Shdr *gelf_getshdr(Elf_Scn *scn, GElf_Shdr *dst);
50
51
52       GElf_Sym *gelf_getsym(Elf_Data *src, int ndx, GElf_Sym *dst);
53
54
55       GElf_Syminfo *gelf_getsyminfo(Elf_Data *src, int ndx, GElf_Syminfo *dst);
56
57
58       GElf_Sym *gelf_getsymshndx(Elf_Data *symsrc, Elf_Data *shndxsrc,
59            int ndx, GElf_Sym *symdst, Elf32_Word *shndxdst);
60
61
62       unsigned long gelf_newehdr(Elf *elf, int class);
63
64
65       unsigned long gelf_newphdr(Elf *elf, size_t phnum);
66
67
68       int gelf_update_cap(Elf_Data *dst, int ndx, GElf_Cap *src);
69
70
71       int gelf_update_dyn(Elf_Data *dst, int ndx, GElf_Dyn *src);
72
73
74       int gelf_update_ehdr(Elf *elf, GElf_Ehdr *src);
75
76
77       int gelf_update_move(Elf_Data *dst, int ndx, GElf_Move *src);
78
79
80       int gelf_update_phdr(Elf *elf, int ndx, GElf_Phdr *src);
81
82
83       int gelf_update_rel(Elf_Data *dst, int ndx, GElf_Rel *src);
84
85
86       int gelf_update_rela(Elf_Data *dst, int ndx, GElf_Rela *src);
87
88
89       int gelf_update_shdr(Elf_Scn *dst, GElf_Shdr *src);
90
91
92       int gelf_update_sym(Elf_Data *dst, int ndx, GElf_Sym *src);
93
94
95       int gelf_update_syminfo(Elf_Data *dst, int ndx, GElf_Syminfo *src);
96
97
98       int gelf_update_symshndx(Elf_Data *symdst, Elf_Data *shndxdst, int ndx,
99            GElf_Sym *symsrc, Elf32_Word shndxsrc);
100
101
102       Elf_Data *gelf_xlatetof(Elf *elf, Elf_Data *dst, const Elf_Data *src,
103            unsigned encode);
104
105
106       Elf_Data *gelf_xlatetom(Elf *elf, Elf_Data *dst, const Elf_Data *src,
107            unsigned encode);
108
109

DESCRIPTION

111       GElf is a generic,  ELF  class-independent  API  for  manipulating  ELF
112       object  files.  GElf  provides  a single, common interface for handling
113       32-bit and 64-bit ELF format object files. GElf is a translation  layer
114       between  the  application  and  the  class-dependent  parts  of the ELF
115       library. Thus, the application can use GElf, which in turn,  will  call
116       the  corresponding elf32_ or elf64_ functions on behalf of the applica‐
117       tion. The data structures returned are all large enough to hold  32-bit
118       and 64-bit data.
119
120
121       GElf provides a simple, class-independent layer of indirection over the
122       class-dependent ELF32 and ELF64 API's. GElf is stateless,  and  may  be
123       used along side the ELF32 and ELF64 API's.
124
125
126       GElf  always returns a copy of the underlying ELF32 or ELF64 structure,
127       and therefore the programming practice of using the address of  an  ELF
128       header  as  the base offset for the ELF's mapping into memory should be
129       avoided. Also, data accessed by type-casting the Elf_Data buffer  to  a
130       class-dependent type and treating it like an array, for example, a sym‐
131       bol table, will not work under GElf, and the gelf_get functions must be
132       used instead. See the EXAMPLE section.
133
134
135       Programs  that  create  or  modify ELF files using libelf(3LIB) need to
136       perform an extra step when using GElf.  Modifications  to  GElf  values
137       must  be explicitly flushed to the underlying ELF32 or ELF64 structures
138       by way of the gelf_update_ interfaces. Use of elf_update or elf_flagelf
139       and the like remains the same.
140
141
142       The  sizes  of  versioning structures remain the same between ELF32 and
143       ELF64. The GElf API only defines types for versioning,  rather  than  a
144       functional  API. The processing of versioning information will stay the
145       same in the GElf environment as it was in the class-dependent ELF envi‐
146       ronment.
147
148   List of Functions
149       gelf_checksum()           An   analog   to   elf32_checksum(3ELF)   and
150                                 elf64_checksum(3ELF).
151
152
153       gelf_fsize()              An   analog    to    elf32_fsize(3ELF)    and
154                                 elf64_fsize(3ELF).
155
156
157       gelf_getcap()             Retrieves the Elf32_Cap or Elf64_Cap informa‐
158                                 tion from the capability table at  the  given
159                                 index.  dst  points to the location where the
160                                 GElf_Cap capability entry is stored.
161
162
163       gelf_getclass()           Returns one of the constants ELFCLASS32, ELF‐
164                                 CLASS64 or ELFCLASSNONE.
165
166
167       gelf_getdyn()             Retrieves the Elf32_Dyn or Elf64_Dyn informa‐
168                                 tion from the  dynamic  table  at  the  given
169                                 index.  dst  points to the location where the
170                                 GElf_Dyn dynamic entry is stored.
171
172
173       gelf_getehdr()            An   analog   to   elf32_getehdr(3ELF)    and
174                                 elf64_getehdr(3ELF).  dst points to the loca‐
175                                 tion where the GElf_Ehdr header is stored.
176
177
178       gelf_getmove()            Retrieves the Elf32_Move or Elf64_Move infor‐
179                                 mation  from  the  move  table  at  the given
180                                 index. dst points to the location  where  the
181                                 GElf_Move move entry is stored.
182
183
184       gelf_getphdr()            An     analog    toelf32_getphdr(3ELF)    and
185                                 elf64_getphdr(3ELF). dst points to the  loca‐
186                                 tion  where  the  GElf_Phdr program header is
187                                 stored.
188
189
190       gelf_getrel()             Retrieves the Elf32_Rel or Elf64_Rel informa‐
191                                 tion  from  the relocation table at the given
192                                 index. dst points to the location  where  the
193                                 GElf_Rel relocation entry is stored.
194
195
196       gelf_getrela()            Retrieves the Elf32_Rela or Elf64_Rela infor‐
197                                 mation from the relocation table at the given
198                                 index.  dst  points to the location where the
199                                 GElf_Rela relocation entry is stored.
200
201
202       gelf_getshdr()            An   analog   to   elf32_getshdr(3ELF)    and
203                                 elf64_getshdr(3ELF).  dst points to the loca‐
204                                 tion where the GElf_Shdr  section  header  is
205                                 stored.
206
207
208       gelf_getsym()             Retrieves the Elf32_Sym or Elf64_Sym informa‐
209                                 tion from  the  symbol  table  at  the  given
210                                 index.  dst  points to the location where the
211                                 GElf_Sym symbol entry is stored.
212
213
214       gelf_getsyminfo()         Retrieves the Elf32_Syminfo or  Elf64_Syminfo
215                                 information  from the relocation table at the
216                                 given index. dst points to the location where
217                                 the  GElf_Syminfo symbol information entry is
218                                 stored.
219
220
221       gelf_getsymshndx()        Provides an extension to  gelf_getsym()  that
222                                 retrieves the Elf32_Sym or Elf64_Sym informa‐
223                                 tion, and the section index from  the  symbol
224                                 table at the given index ndx.
225
226                                 The   symbols   section  index  is  typically
227                                 recorded in the st_shndx field of the symbols
228                                 structure.  However, a file that requires ELF
229                                 Extended Sections may record an  st_shndx  of
230                                 SHN_XINDEX  indicating that the section index
231                                 must   be   obtained   from   an   associated
232                                 SHT_SYMTAB_SHNDX section entry. If xshndx and
233                                 shndxdata are non-null, the value recorded at
234                                 index   ndx  of  the  SHT_SYMTAB_SHNDX  table
235                                 pointed to by shndxdata is returned  in  xsh‐
236                                 ndx. See USAGE.
237
238
239       gelf_newehdr()            An    analog   to   elf32_newehdr(3ELF)   and
240                                 elf64_newehdr(3ELF).
241
242
243       gelf_newphdr()            An   analog   to   elf32_newphdr(3ELF)    and
244                                 elf64_newphdr(3ELF).
245
246
247       gelf_update_cap()         Copies the GElf_Cap information back into the
248                                 underlying Elf32_Cap or  Elf64_Cap  structure
249                                 at the given index.
250
251
252       gelf_update_dyn()         Copies the GElf_Dyn information back into the
253                                 underlying Elf32_Dyn or  Elf64_Dyn  structure
254                                 at the given index.
255
256
257       gelf_update_ehdr()        Copies  the  contents  of  the  GElf_Ehdr ELF
258                                 header  to  the  underlying   Elf32_Ehdr   or
259                                 Elf64_Ehdr structure.
260
261
262       gelf_update_move()        Copies  the  GElf_Move  information back into
263                                 the  underlying  Elf32_Move   or   Elf64_Move
264                                 structure at the given index.
265
266
267       gelf_update_phdr()        Copies  of  the contents of GElf_Phdr program
268                                 header  to  underlying  the   Elf32_Phdr   or
269                                 Elf64_Phdr structure.
270
271
272       gelf_update_rel()         Copies the GElf_Rel information back into the
273                                 underlying Elf32_Rel or  Elf64_Rel  structure
274                                 at the given index.
275
276
277       gelf_update_rela()        Copies  the  GElf_Rela  information back into
278                                 the  underlying  Elf32_Rela   or   Elf64_Rela
279                                 structure at the given index.
280
281
282       gelf_update_shdr()        Copies  of  the contents of GElf_Shdr section
283                                 header  to  underlying  the   Elf32_Shdr   or
284                                 Elf64_Shdr structure.
285
286
287       gelf_update_sym()         Copies the GElf_Sym information back into the
288                                 underlying Elf32_Sym or  Elf64_Sym  structure
289                                 at the given index.
290
291
292       gelf_update_syminfo()     Copies the GElf_Syminfo information back into
293                                 the underlying Elf32_Syminfo or Elf64_Syminfo
294                                 structure at the given index.
295
296
297       gelf_update_symshndx()    Provides  an  extension  to gelf_update_sym()
298                                 that copies  the  GElf_Sym  information  back
299                                 into  the Elf32_Sym or Elf64_Sym structure at
300                                 the given index ndx, and copies the  extended
301                                 xshndx  section  index into the Elf32_Word at
302                                 the given index ndx in the  buffer  described
303                                 by shndxdata. See USAGE.
304
305
306       gelf_xlatetof()           An   analog   to   elf32_xlatetof(3ELF)   and
307                                 elf64_xlatetof(3ELF)
308
309
310       gelf_xlatetom()           An   analog   to   elf32_xlatetom(3ELF)   and
311                                 elf64_xlatetom(3ELF)
312
313

RETURN VALUES

315       Upon  failure,  all  GElf  functions  return  0  and set elf_errno. See
316       elf_errno(3ELF)
317

EXAMPLES

319       Example 1 Printing the ELF Symbol Table
320
321         #include <stdio.h>
322         #include <sys/types.h>
323         #include <sys/stat.h>
324         #include <fcntl.h>
325         #include <libelf.h>
326         #include <gelf.h>
327
328         void
329         main(int argc, char **argv)
330         {
331             Elf         *elf;
332             Elf_Scn     *scn = NULL;
333             GElf_Shdr   shdr;
334             Elf_Data    *data;
335             int         fd, ii, count;
336
337             elf_version(EV_CURRENT);
338
339             fd = open(argv[1], O_RDONLY);
340             elf = elf_begin(fd, ELF_C_READ, NULL);
341
342             while ((scn = elf_nextscn(elf, scn)) != NULL) {
343                 gelf_getshdr(scn, &shdr);
344                 if (shdr.sh_type == SHT_SYMTAB) {
345                     /* found a symbol table, go print it. */
346                     break;
347                 }
348             }
349
350             data = elf_getdata(scn, NULL);
351             count = shdr.sh_size / shdr.sh_entsize;
352
353             /* print the symbol names */
354             for (ii = 0; ii < count; ++ii) {
355                 GElf_Sym sym;
356                 gelf_getsym(data, ii, &sym);
357                 printf("%s\n", elf_strptr(elf, shdr.sh_link, sym.st_name));
358             }
359             elf_end(elf);
360             close(fd);
361         }
362
363

USAGE

365       ELF Extended Sections are employed to allow an ELF file to contain more
366       than 0xff00 (SHN_LORESERVE) section. See the Linker and Libraries Guide
367       for more information.
368

FILES

370       /lib/libelf.so.1       shared object
371
372
373       /lib/64/libelf.so.1    64-bit shared object
374
375

ATTRIBUTES

377       See attributes(5) for descriptions of the following attributes:
378
379
380
381
382       ┌─────────────────────────────┬─────────────────────────────┐
383       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
384       ├─────────────────────────────┼─────────────────────────────┤
385       │Interface Stability          │Stable                       │
386       ├─────────────────────────────┼─────────────────────────────┤
387       │MT Level                     │MT-Safe                      │
388       └─────────────────────────────┴─────────────────────────────┘
389

SEE ALSO

391       elf(3ELF),   elf32_checksum(3ELF),    elf32_fsize(3ELF),    elf32_gete‐
392       hdr(3ELF),    elf32_newehdr(3ELF),    elf32_getphdr(3ELF),   elf32_new‐
393       phdr(3ELF),  elf32_getshdr(3ELF),  elf32_xlatetof(3ELF),   elf32_xlate‐
394       tom(3ELF), elf_errno(3ELF), libelf(3LIB), attributes(5)
395
396
397       Linker and Libraries Guide
398
399
400
401SunOS 5.11                        8 June 2004                       gelf(3ELF)
Impressum