elf_getscn(3ELF)					       ELF Library Functions						  elf_getscn(3ELF)

NAME

       elf_getscn, elf_ndxscn, elf_newscn, elf_nextscn - get section information

SYNOPSIS

       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

       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 elf32_getehdr(3ELF).

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

       The  elf_newscn()  function  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. If an error occurs or elf is NULL, elf_newscn() returns a null pointer.

       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 elf_getdata(3ELF)). 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_flagdata(3ELF)). If the program is building a
       new file, it is responsible for creating the file's ELF header (see elf32_getehdr(3ELF)) before creating new sections.

       The elf_nextscn() function 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). If no fur-
       ther sections are present or an error occurs, elf_nextscn() returns a null pointer.

       The elf_ndxscn() function 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.

EXAMPLES

       Example 1 A sample of calling elf_getscn() function.

       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 */
	 }

ATTRIBUTES

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Stable			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       elf(3ELF), elf32_getehdr(3ELF), elf32_getshdr(3ELF), elf_begin(3ELF), elf_flagdata(3ELF), elf_getdata(3ELF), libelf(3LIB), attributes(5)

SunOS 5.11							    11 Jul 2001 						  elf_getscn(3ELF)