ELF_GETSCN(3) | Library Functions Manual | ELF_GETSCN(3)

# NAME

`elf_getscn`, `elf_ndxscn`, `elf_newscn`, `elf_nextscn` — get/allocate section information for an ELF object

# SYNOPSIS

ELF Access Library (libelf, -lelf)
`#include <libelf.h>`

Elf_Scn *
`elf_getscn`(Elf *elf, size_t index);

size_t
`elf_ndxscn`(Elf_Scn *scn);

Elf_Scn *
`elf_newscn`(Elf *elf);

Elf_Scn *
`elf_nextscn`(Elf *elf, Elf_Scn *scn);

# DESCRIPTION

These functions are used to iterate through the sections associated with an ELF descriptor.

Function `elf_getscn`() will return a section descriptor for the section at index index in the object denoted by ELF descriptor elf. An error will be signalled if the specified section does not exist.

Function `elf_ndxscn`() returns the section table index associated with section descriptor scn.

Function `elf_newscn`() creates a new section and appends it to the list of sections associated with descriptor elf. The library will automatically increment the e_shnum field of the ELF header associated with descriptor elf, and will set the `ELF_F_DIRTY` flag on the returned section descriptor. For ELF descriptors opened for writing, the ELF library will automatically create an empty section at index zero (`SHN_UNDEF`) on the first call to `elf_newscn`().

Function `elf_nextscn`() takes a section descriptor scn and returns a pointer to the section descriptor at the next higher index. As a consequence, `elf_nextscn`() will never return a pointer to the empty section at index zero (`SHN_UNDEF`). Argument scn is allowed to be NULL, in which case this function will return a pointer to the section descriptor at index 1. If no further sections are present, function `elf_nextscn`() will return a NULL pointer.

# RETURN VALUES

Functions `elf_getscn`(), `elf_newscn`() and `elf_nextscn`() return a valid pointer to a section descriptor if successful, or NULL if an error occurs.

Function `elf_ndxscn`() returns a valid section table index if successful, or `SHN_UNDEF` if an error occurs.

# ERRORS

These functions may fail with the following errors:

[`ELF_E_ARGUMENT`]
  Arguments elf or scn were NULL.
[`ELF_E_ARGUMENT`]
  Argument index exceeded the current number of sections in the ELF object.
[`ELF_E_ARGUMENT`]
  Argument elf was not a descriptor for an ELF file.
[`ELF_E_ARGUMENT`]
  Section descriptor scn was not associated with ELF descriptor elf.
[`ELF_E_CLASS`]
  Descriptor elf was of an unknown ELF class.
[`ELF_E_SECTION`]
  Argument elf specified extended section numbering in the ELF header with the section header at index `SHN_UNDEF` not being of type `SHT_NULL`.

# SEE ALSO

elf(3), elf_flagdata(3), elf_flagscn(3), elf_getdata(3), elf_getshdr(3), gelf(3)

September 24, 2018 | Debian