elf_getscn(S)

elf_getscn, elf_ndxscn, elf_newscn, elf_nextscn -- get section information

Syntax

cc [flag . . . ] file . . . -lelf [library] . . .


#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

elf_getscn- get a section descriptor

elf_ndxscn- return the section table index for a section

elf_newscn- create a new section

elf_nextscn- return the section description of the next section

These functions provide indexed and sequential access to the sections associated with the ELF descriptor elf. If the program is building a new file, it is responsible for creating the file's ELF header before creating sections; see elf_getehdr(S).

elf_getscn(S) returns a section descriptor, given an index into the file's section header table. Note the first ``real'' section has index 1. Although a program can get a section descriptor for the section whose index is 0 (SHN_UNDEF, the undefined section), the section has no data and the section header is ``empty'' (though present). elf_getscn( ) returns a null pointer if the specified section does not exist, an error occurs, or elf is null.

elf_newscn(S) creates a new section and appends it to the list for elf. Because the SHN_UNDEF section is required and not ``interesting'' to applications, the library creates it automatically. Thus the first call to elf_newscn( ) for an ELF descriptor with no existing sections returns the descriptor for section 1. elf_newscn( ) returns a null pointer if an error occurs or elf is null.

After creating a new section descriptor, the program can use elf_getshdr(S) to retrieve the newly created, ``clean'' section header. The new section descriptor has no associated data (see elf_getdata(S)). When creating a new section in this way, the library updates the e_shnum member of the ELF header and sets the ELF_F_DIRTY bit for the section (see elf_flag(S)). If the program is building a new file, it must create the file's ELF header. (See elf_getehdr( )) before creating new sections.

elf_nextscn(S) takes an existing section descriptor, scn, and returns a section descriptor for the next higher section. One may use a null scn to get a section descriptor for the section whose index is 1 (skipping the section whose index is SHN_UNDEF). elf_nextscn( ) returns a null pointer if no further sections are present or an error occurs.

elf_ndxscn(S) takes an existing section descriptor, scn, and returns its section table index. If scn is null or an error occurs, elf_ndxscn( ) returns SHN_UNDEF.

Return values

This function returns the section descriptor or NULL, except for elf_ndxscn( ), which returns the section table index.

Diagnostics

Error conditions are identified through the routine elf_error(S).

Examples

An example of sequential access appears below. Each pass through the loop processes the next section in the file; the loop terminates when all sections have been processed.

   scn = 0;
   while ((scn = elf_nextscn(elf, scn)) != 0)
   {
   	/* process section */
   }

Standards conformance

elf_getscn(S), elf_ndxscn(S), elf_newscn(S), and elf_nextscn(S) are not part of any currently supported standard; they were developed by UNIX System Laboratories, Inc. and are maintained by The SCO Group.