[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions, Volume 1


elf_getscn, elf_ndxscn, elf_newscn, elf_nextscn Subroutine

Purpose

Get section information

Library

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

Syntax


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 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 the elf32_getehdr and elf64_getehdr subroutines.

elf_getscn returns a section descriptor, given an index into the file's section header table (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_newscn 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 a descriptor for section 1.

After creating a new section descriptor, the program can use elf32_getshdr to retrieve the newly created, clean section header. The new section descriptor will have no associated data [see the elf_getdata subroutine]. 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 the elf_flagdata subroutine]. If the program is building a new file, it is responsible for creating the file's ELF header [see the elf32_getehdr and elf64_getehdr subroutines] before creating new sections.

elf_nextscn takes an existing section descriptor, scn, and returns a section descriptor for the next higher section. One may use a null scn to obtain a section descriptor for the section whose index is 1 (skipping the section whose index is SHN_UNDEF).

elf_ndxscn takes an existing section descriptor, scn, and returns its section table index.

Return Values

If the specified section does not exist, an error occurs, or elf is null, elf_getscn returns a null pointer.

If an error occurs or elf is null, elf_newscn returns a null pointer.

If no further sections are present or an error occurs, elf_nextscn returns a null pointer.

If scn is null or an error occurs, elf_ndxscn returns SHN_UNDEF.

Examples

An example of sequential access is shown 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 */
   }

Related Information

The elf_begin (elf_begin Subroutine) subroutine, elf_flagdata (elf_flagdata, elf_flagehdr, elf_flagelf, elf_flagphdr, elf_flagscn, elf_flagshdr Subroutine) subroutine, elf_getdata (elf_getdata, elf_newdata, elf_rawdata Subroutine) subroutine, elf32_getehdr (elf32_getehdr, elf32_newehdr, elf64_getehdr, elf64_newehdr Subroutine) subroutine, elf64_getehdr (elf32_getehdr, elf32_newehdr, elf64_getehdr, elf64_newehdr Subroutine) subroutine, elf32_getshdr (elf32_getshdr, elf64_getshdr Subroutine) subroutine.

Introduction to ELF Subroutines.


[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]