Tribblix: manual page: elf

ELF_GETIDENT(3ELF) ELF Library Functions ELF_GETIDENT(3ELF)

NAME

elf_getident, elf_getphdrnum, elf_getshdrnum, elf_getshdrstrndx,
elf_getphnum, elf_getshnum, elf_getshstrndx - retrieve ELF header
data

SYNOPSIS

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

char *elf_getident(Elf *elf, size_t *dst);

int elf_getphdrnum(Elf *elf, size_t *dst);

int elf_getshdrnum(Elf *elf, size_t *dst);

int elf_getshdrstrndx(Elf *elf, size_t *dst);

Obsolete Interfaces

int elf_getphnum(Elf *elf, size_t *dst);

int elf_getshnum(Elf *elf, size_t *dst);

int elf_getshstrndx(Elf *elf, size_t *dst);

DESCRIPTION

As elf(3ELF) explains, ELF provides a framework for various classes
of files, where basic objects might have 32 or 64 bits. To
accommodate these differences, without forcing the larger sizes on
smaller machines, the initial bytes in an ELF file hold
identification information common to all file classes. The e_ident of
every ELF header has EI_NIDENT bytes with interpretations described
in the following table.

e_ident Index Value Purpose

EI_MAG0 ELFMAG0 File identification
EI_MAG1 ELFMAG1
EI_MAG2 ELFMAG2
EI_MAG3 ELFMAG3

EI_CLASS ELFCLASSNONE File class
ELFCLASS32
ELFCLASS64

EI_DATA ELFDATANONE Data encoding
ELFDATA2LSB
ELFDATA2MSB

EI_VERSION EV_CURRENT File version

7-15 0 Unused, set to zero

Other kinds of files might have identification data, though they
would not conform to e_ident. See elf_kind(3ELF) for information on
other kinds of files.

The elf_getident() function returns a pointer to the initial bytes of
the file. If the library recognizes the file, a conversion from the
file image to the memory image can occur. The identification bytes
are guaranteed to be unmodified, though the size of the unmodified
area depends on the file type. If the dst argument is non-null, the
library stores the number of identification bytes in the location to
which dst points. If no data are present, elf is NULL, or an error
occurs, the return value is a null pointer, with 0 stored through
dst, if dst is non-null.

The elf_getphdrnum() function obtains the number of program headers
recorded in the ELF file. The number of sections in a file is
typically recorded in the e_phnum field of the ELF header. A file
that requires the ELF extended program header records the value
PN_XNUM in the e_phnum field and records the number of sections in
the sh_info field of section header 0. See USAGE. The dst argument
points to the location where the number of sections is stored. If elf
is NULL or an error occurs, elf_getphdrnum() returns -1.

The elf_getshdrnum() function obtains the number of sections recorded
in the ELF file. The number of sections in a file is typically
recorded in the e_shnum field of the ELF header. A file that requires
ELF extended section records the value 0 in the e_shnum field and
records the number of sections in the sh_size field of section header
0. See USAGE. The dst argument points to the location where the
number of sections is stored. If a call to elf_newscn(3ELF) that uses
the same elf descriptor is performed, the value obtained by
elf_getshnum() is valid only after a successful call to
elf_update(3ELF). If elf is NULL or an error occurs, elf_getshdrnum()
returns -1.

The elf_getshdrstrndx() function obtains the section index of the
string table associated with the section headers in the ELF file. The
section header string table index is typically recorded in the
e_shstrndx field of the ELF header. A file that requires ELF extended
section records the value SHN_XINDEX in the e_shstrndx field and
records the string table index in the sh_link field of section header
0. See USAGE. The dst argument points to the location where the
section header string table index is stored. If elf is NULL or an
error occurs, elf_getshdrstrndx() returns -1.

The elf_getphnum(), elf_getshnum(), and elf_getshstrndx() functions
behave in a manner similar to elf_getphdrnum(), elf_getshdrnum(), and
elf_getshdrstrndx(), respectively, except that they return 0 if elf
is NULL or an error occurs. Because these return values differ from
those used by some other systems, they are therefore non-portable and
their use is discouraged. The elf_getphdrnum(), elf_getshdrnum(), and
elf_getshdrstrndx() functions should be used instead.

USAGE

ELF extended sections allow an ELF file to contain more than 0xff00
(SHN_LORESERVE) section. ELF extended program headers allow an ELF
file to contain 0xffff (PN_XNUM) or more program headers. See the
Linker and Libraries Guide for more information.

RETURN VALUES

Upon successful completion, the elf_getident() function returns 1.
Otherwise, it return 0.

Upon successful completion, the elf_getphdrnum(), elf_getshdrnum(),
and elf_getshdrstrndx() functions return 0. Otherwise, they return
-1.

Upon successful completion, the elf_getphnum(), elf_getshnum(), and
elf_getshstrndx() functions return 1. Otherwise, they return 0.

ATTRIBUTES

See attributes(7) for descriptions of the following attributes:

+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | See below. |
+--------------------+-----------------+
|MT-Level | MT-Safe |
+--------------------+-----------------+

The elf_getident(), elf_getphdrnum(), elf_getshdrnum(), and
elf_getshdrstrndx() functions are Committed. The elf_getphnum(),
elf_getshnum(), and elf_getshstrndx() functions are Committed
(Obsolete).