Tribblix: manual page: gelf.3elf

GELF(3ELF) ELF Library Functions GELF(3ELF)

NAME

gelf, gelf_checksum, gelf_fsize, gelf_getcap, gelf_getclass,
gelf_getdyn, gelf_getehdr, gelf_getmove, gelf_getphdr, gelf_getrel,
gelf_getrela, gelf_getshdr, gelf_getsym, gelf_getsyminfo,
gelf_getsymshndx, gelf_newehdr, gelf_newphdr, gelf_update_cap,
gelf_update_dyn, gelf_update_ehdr, gelf_update_getmove,
gelf_update_move, gelf_update_phdr, gelf_update_rel,
gelf_update_rela, gelf_update_shdr, gelf_update_sym,
gelf_update_symshndx, gelf_update_syminfo, gelf_xlatetof,
gelf_xlatetom - generic class-independent ELF interface

SYNOPSIS

cc [ flag... ] file... -lelf [ library... ]
#include <gelf.h>

long gelf_checksum(Elf *elf);

size_t gelf_fsize(Elf *elf, Elf_Type type, size_t cnt, unsigned ver);

int gelf_getcap(Elf_Data *src, int ndx, GElf_Cap *dst);

int gelf_getclass(Elf *elf);

GElf_Dyn *gelf_getdyn(Elf_Data *src, int ndx, GElf_Dyn *dst);

GElf_Ehdr *gelf_getehdr(Elf *elf, GElf_Ehdr *dst);

GElf_Move *gelf_getmove(Elf_Data *src, int ndx, GElf_Move *dst);

GElf_Phdr *gelf_getphdr(Elf *elf, int ndx, GElf_Phdr *dst);

GElf_Rel *gelf_getrel(Elf_Data *src, int ndx, GElf_Rel *dst);

GElf_Rela *gelf_getrela(Elf_Data *src, int ndx, GElf_Rela *dst);

GElf_Shdr *gelf_getshdr(Elf_Scn *scn, GElf_Shdr *dst);

GElf_Sym *gelf_getsym(Elf_Data *src, int ndx, GElf_Sym *dst);

GElf_Syminfo *gelf_getsyminfo(Elf_Data *src, int ndx, GElf_Syminfo *dst);

GElf_Sym *gelf_getsymshndx(Elf_Data *symsrc, Elf_Data *shndxsrc,
int ndx, GElf_Sym *symdst, Elf32_Word *shndxdst);

unsigned long gelf_newehdr(Elf *elf, int class);

unsigned long gelf_newphdr(Elf *elf, size_t phnum);

int gelf_update_cap(Elf_Data *dst, int ndx, GElf_Cap *src);

int gelf_update_dyn(Elf_Data *dst, int ndx, GElf_Dyn *src);

int gelf_update_ehdr(Elf *elf, GElf_Ehdr *src);

int gelf_update_move(Elf_Data *dst, int ndx, GElf_Move *src);

int gelf_update_phdr(Elf *elf, int ndx, GElf_Phdr *src);

int gelf_update_rel(Elf_Data *dst, int ndx, GElf_Rel *src);

int gelf_update_rela(Elf_Data *dst, int ndx, GElf_Rela *src);

int gelf_update_shdr(Elf_Scn *dst, GElf_Shdr *src);

int gelf_update_sym(Elf_Data *dst, int ndx, GElf_Sym *src);

int gelf_update_syminfo(Elf_Data *dst, int ndx, GElf_Syminfo *src);

int gelf_update_symshndx(Elf_Data *symdst, Elf_Data *shndxdst, int ndx,
GElf_Sym *symsrc, Elf32_Word shndxsrc);

Elf_Data *gelf_xlatetof(Elf *elf, Elf_Data *dst, const Elf_Data *src,
unsigned encode);

Elf_Data *gelf_xlatetom(Elf *elf, Elf_Data *dst, const Elf_Data *src,
unsigned encode);

DESCRIPTION

GElf is a generic, ELF class-independent API for manipulating ELF
object files. GElf provides a single, common interface for handling
32-bit and 64-bit ELF format object files. GElf is a translation
layer between the application and the class-dependent parts of the
ELF library. Thus, the application can use GElf, which in turn, will
call the corresponding elf32_ or elf64_ functions on behalf of the
application. The data structures returned are all large enough to
hold 32-bit and 64-bit data.

GElf provides a simple, class-independent layer of indirection over
the class-dependent ELF32 and ELF64 API's. GElf is stateless, and may
be used along side the ELF32 and ELF64 API's.

GElf always returns a copy of the underlying ELF32 or ELF64
structure, and therefore the programming practice of using the
address of an ELF header as the base offset for the ELF's mapping
into memory should be avoided. Also, data accessed by type-casting
the Elf_Data buffer to a class-dependent type and treating it like an
array, for example, a symbol table, will not work under GElf, and the
gelf_get functions must be used instead. See the EXAMPLE section.

Programs that create or modify ELF files using libelf(3LIB) need to
perform an extra step when using GElf. Modifications to GElf values
must be explicitly flushed to the underlying ELF32 or ELF64
structures by way of the gelf_update_ interfaces. Use of elf_update
or elf_flagelf and the like remains the same.

The sizes of versioning structures remain the same between ELF32 and
ELF64. The GElf API only defines types for versioning, rather than a
functional API. The processing of versioning information will stay
the same in the GElf environment as it was in the class-dependent ELF
environment.

List of Functions

gelf_checksum()
An analog to elf32_checksum(3ELF) and
elf64_checksum(3ELF).

gelf_fsize()
An analog to elf32_fsize(3ELF) and
elf64_fsize(3ELF).

gelf_getcap()
Retrieves the Elf32_Cap or Elf64_Cap
information from the capability table at
the given index. dst points to the location
where the GElf_Cap capability entry is
stored.

gelf_getclass()
Returns one of the constants ELFCLASS32,
ELFCLASS64 or ELFCLASSNONE.

gelf_getdyn()
Retrieves the Elf32_Dyn or Elf64_Dyn
information from the dynamic table at the
given index. dst points to the location
where the GElf_Dyn dynamic entry is stored.

gelf_getehdr()
An analog to elf32_getehdr(3ELF) and
elf64_getehdr(3ELF). dst points to the
location where the GElf_Ehdr header is
stored.

gelf_getmove()
Retrieves the Elf32_Move or Elf64_Move
information from the move table at the
given index. dst points to the location
where the GElf_Move move entry is stored.

gelf_getphdr()
An analog to elf32_getphdr(3ELF) and
elf64_getphdr(3ELF). dst points to the
location where the GElf_Phdr program header
is stored.

gelf_getrel()
Retrieves the Elf32_Rel or Elf64_Rel
information from the relocation table at
the given index. dst points to the location
where the GElf_Rel relocation entry is
stored.

gelf_getrela()
Retrieves the Elf32_Rela or Elf64_Rela
information from the relocation table at
the given index. dst points to the location
where the GElf_Rela relocation entry is
stored.

gelf_getshdr()
An analog to elf32_getshdr(3ELF) and
elf64_getshdr(3ELF). dst points to the
location where the GElf_Shdr section header
is stored.

gelf_getsym()
Retrieves the Elf32_Sym or Elf64_Sym
information from the symbol table at the
given index. dst points to the location
where the GElf_Sym symbol entry is stored.

gelf_getsyminfo()
Retrieves the Elf32_Syminfo or
Elf64_Syminfo information from the
relocation table at the given index. dst
points to the location where the
GElf_Syminfo symbol information entry is
stored.

gelf_getsymshndx()
Provides an extension to gelf_getsym() that
retrieves the Elf32_Sym or Elf64_Sym
information, and the section index from the
symbol table at the given index ndx.

The symbols section index is typically
recorded in the st_shndx field of the
symbols structure. However, a file that
requires ELF Extended Sections may record
an st_shndx of SHN_XINDEX indicating that
the section index must be obtained from an
associated SHT_SYMTAB_SHNDX section entry.
If xshndx and shndxdata are non-null, the
value recorded at index ndx of the
SHT_SYMTAB_SHNDX table pointed to by
shndxdata is returned in xshndx. See USAGE.

gelf_newehdr()
An analog to elf32_newehdr(3ELF) and
elf64_newehdr(3ELF).

gelf_newphdr()
An analog to elf32_newphdr(3ELF) and
elf64_newphdr(3ELF).

gelf_update_cap()
Copies the GElf_Cap information back into
the underlying Elf32_Cap or Elf64_Cap
structure at the given index.

gelf_update_dyn()
Copies the GElf_Dyn information back into
the underlying Elf32_Dyn or Elf64_Dyn
structure at the given index.

gelf_update_ehdr()
Copies the contents of the GElf_Ehdr ELF
header to the underlying Elf32_Ehdr or
Elf64_Ehdr structure.

gelf_update_move()
Copies the GElf_Move information back into
the underlying Elf32_Move or Elf64_Move
structure at the given index.

gelf_update_phdr()
Copies of the contents of GElf_Phdr program
header to underlying the Elf32_Phdr or
Elf64_Phdr structure.

gelf_update_rel()
Copies the GElf_Rel information back into
the underlying Elf32_Rel or Elf64_Rel
structure at the given index.

gelf_update_rela()
Copies the GElf_Rela information back into
the underlying Elf32_Rela or Elf64_Rela
structure at the given index.

gelf_update_shdr()
Copies of the contents of GElf_Shdr section
header to underlying the Elf32_Shdr or
Elf64_Shdr structure.

gelf_update_sym()
Copies the GElf_Sym information back into
the underlying Elf32_Sym or Elf64_Sym
structure at the given index.

gelf_update_syminfo()
Copies the GElf_Syminfo information back
into the underlying Elf32_Syminfo or
Elf64_Syminfo structure at the given index.

gelf_update_symshndx()
Provides an extension to gelf_update_sym()
that copies the GElf_Sym information back
into the Elf32_Sym or Elf64_Sym structure
at the given index ndx, and copies the
extended xshndx section index into the
Elf32_Word at the given index ndx in the
buffer described by shndxdata. See USAGE.

gelf_xlatetof()
An analog to elf32_xlatetof(3ELF) and
elf64_xlatetof(3ELF)

gelf_xlatetom()
An analog to elf32_xlatetom(3ELF) and
elf64_xlatetom(3ELF)

RETURN VALUES

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

EXAMPLES

Example 1: Printing the ELF Symbol Table

#include <stdio.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <libelf.h>
#include <gelf.h>

void
main(int argc, char **argv)
{
Elf *elf;
Elf_Scn *scn = NULL;
GElf_Shdr shdr;
Elf_Data *data;
int fd, ii, count;

elf_version(EV_CURRENT);

fd = open(argv[1], O_RDONLY);
elf = elf_begin(fd, ELF_C_READ, NULL);

while ((scn = elf_nextscn(elf, scn)) != NULL) {
gelf_getshdr(scn, &shdr);
if (shdr.sh_type == SHT_SYMTAB) {
/* found a symbol table, go print it. */
break;
}
}

data = elf_getdata(scn, NULL);
count = shdr.sh_size / shdr.sh_entsize;

/* print the symbol names */
for (ii = 0; ii < count; ++ii) {
GElf_Sym sym;
gelf_getsym(data, ii, &sym);
printf("%s\n", elf_strptr(elf, shdr.sh_link, sym.st_name));
}
elf_end(elf);
close(fd);
}

USAGE

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

FILES

/lib/libelf.so.1
shared object

/lib/64/libelf.so.1
64-bit shared object

ATTRIBUTES