.\" Copyright (c) 2006-2008,2018 Joseph Koshy.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" This software is provided by Joseph Koshy ``as is'' and
.\" any express or implied warranties, including, but not limited to, the
.\" implied warranties of merchantability and fitness for a particular purpose
.\" are disclaimed.  in no event shall Joseph Koshy be liable
.\" for any direct, indirect, incidental, special, exemplary, or consequential
.\" damages (including, but not limited to, procurement of substitute goods
.\" or services; loss of use, data, or profits; or business interruption)
.\" however caused and on any theory of liability, whether in contract, strict
.\" liability, or tort (including negligence or otherwise) arising in any way
.\" out of the use of this software, even if advised of the possibility of
.\" such damage.
.\"
.\" $Id: elf_getscn.3,v 1.1 2019/02/01 05:27:37 jsg Exp $
.\"
.Dd September 24, 2018
.Dt ELF_GETSCN 3
.Os
.Sh NAME
.Nm elf_getscn ,
.Nm elf_ndxscn ,
.Nm elf_newscn ,
.Nm elf_nextscn
.Nd get/allocate section information for an ELF object
.Sh LIBRARY
.Lb libelf
.Sh SYNOPSIS
.In libelf.h
.Ft "Elf_Scn *"
.Fn elf_getscn "Elf *elf" "size_t index"
.Ft size_t
.Fn elf_ndxscn "Elf_Scn *scn"
.Ft "Elf_Scn *"
.Fn elf_newscn "Elf *elf"
.Ft "Elf_Scn *"
.Fn elf_nextscn "Elf *elf" "Elf_Scn *scn"
.Sh DESCRIPTION
These functions are used to iterate through the sections associated
with an ELF descriptor.
.Pp
Function
.Fn elf_getscn
will return a section descriptor for the section at index
.Ar index
in the object denoted by ELF descriptor
.Ar elf .
An error will be signalled if the specified section does not
exist.
.Pp
Function
.Fn elf_ndxscn
returns the section table index associated with section descriptor
.Ar scn .
.Pp
Function
.Fn elf_newscn
creates a new section and appends it to the list of sections
associated with descriptor
.Ar elf .
The library will automatically increment the
.Va e_shnum
field of the ELF header associated with descriptor
.Ar elf ,
and will set the
.Dv 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
.Dv ( SHN_UNDEF )
on the first call to
.Fn elf_newscn .
.Pp
Function
.Fn elf_nextscn
takes a section descriptor
.Ar scn
and returns a pointer to the section descriptor at the next higher
index.
As a consequence,
.Fn elf_nextscn
will never return a pointer to the empty section at index zero
.Dv ( SHN_UNDEF ) .
Argument
.Ar 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
.Fn elf_nextscn
will return a NULL pointer.
.Sh RETURN VALUES
Functions
.Fn elf_getscn ,
.Fn elf_newscn
and
.Fn elf_nextscn
return a valid pointer to a section descriptor if successful, or
NULL if an error occurs.
.Pp
Function
.Fn elf_ndxscn
returns a valid section table index if successful, or
.Dv SHN_UNDEF
if an error occurs.
.Sh ERRORS
These functions may fail with the following errors:
.Bl -tag -width "[ELF_E_RESOURCE]"
.It Bq Er ELF_E_ARGUMENT
Arguments
.Ar elf
or
.Ar scn
were NULL.
.It Bq Er ELF_E_ARGUMENT
Argument
.Ar index
exceeded the current number of sections in the ELF object.
.It Bq Er ELF_E_ARGUMENT
Argument
.Ar elf
was not a descriptor for an ELF file.
.It Bq Er ELF_E_ARGUMENT
Section descriptor
.Ar scn
was not associated with ELF descriptor
.Ar elf .
.It Bq Er ELF_E_CLASS
Descriptor
.Ar elf
was of an unknown ELF class.
.It Bq Er ELF_E_SECTION
Argument
.Ar elf
specified extended section numbering in the ELF header with the section header at
index
.Dv SHN_UNDEF
not being of type
.Dv SHT_NULL .
.El
.Sh SEE ALSO
.Xr elf 3 ,
.Xr elf_flagdata 3 ,
.Xr elf_flagscn 3 ,
.Xr elf_getdata 3 ,
.Xr elf_getshdr 3 ,
.Xr gelf 3