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).
SEE ALSO
elf(3ELF),
elf32_getehdr(3ELF),
elf_begin(3ELF),
elf_kind(3ELF),
elf_newscn(3ELF),
elf_rawfile(3ELF),
elf_update(3ELF),
libelf(3LIB),
attributes(7) Linker and Libraries Guide June 18, 2009
ELF_GETIDENT(3ELF)