1  .\" Copyright (c) 2006-2008 Joseph Koshy.  All rights reserved.
  2  .\"
  3  .\" Redistribution and use in source and binary forms, with or without
  4  .\" modification, are permitted provided that the following conditions
  5  .\" are met:
  6  .\" 1. Redistributions of source code must retain the above copyright
  7  .\"    notice, this list of conditions and the following disclaimer.
  8  .\" 2. Redistributions in binary form must reproduce the above copyright
  9  .\"    notice, this list of conditions and the following disclaimer in the
 10  .\"    documentation and/or other materials provided with the distribution.
 11  .\"
 12  .\" This software is provided by Joseph Koshy ``as is'' and
 13  .\" any express or implied warranties, including, but not limited to, the
 14  .\" implied warranties of merchantability and fitness for a particular purpose
 15  .\" are disclaimed.  in no event shall Joseph Koshy be liable
 16  .\" for any direct, indirect, incidental, special, exemplary, or consequential
 17  .\" damages (including, but not limited to, procurement of substitute goods
 18  .\" or services; loss of use, data, or profits; or business interruption)
 19  .\" however caused and on any theory of liability, whether in contract, strict
 20  .\" liability, or tort (including negligence or otherwise) arising in any way
 21  .\" out of the use of this software, even if advised of the possibility of
 22  .\" such damage.
 23  .\"
 24  .\" $Id$
 25  .\"
 26  .Dd October 22, 2007
 27  .Os
 28  .Dt ELF_GETSCN 3
 29  .Sh NAME
 30  .Nm elf_getscn ,
 31  .Nm elf_ndxscn ,
 32  .Nm elf_newscn ,
 33  .Nm elf_nextscn
 34  .Nd get/allocate section information for an ELF object
 35  .Sh LIBRARY
 36  .Lb libelf
 37  .Sh SYNOPSIS
 38  .In libelf.h
 39  .Ft "Elf_Scn *"
 40  .Fn elf_getscn "Elf *elf" "size_t index"
 41  .Ft size_t
 42  .Fn elf_ndxscn "Elf_Scn *scn"
 43  .Ft "Elf_Scn *"
 44  .Fn elf_newscn "Elf *elf"
 45  .Ft "Elf_Scn *"
 46  .Fn elf_nextscn "Elf *elf" "Elf_Scn *scn"
 47  .Sh DESCRIPTION
 48  These functions are used to iterate through the sections associated
 49  with an ELF descriptor.
 50  .Pp
 51  Function
 52  .Fn elf_getscn
 53  will return a section descriptor for the section at index
 54  .Ar index
 55  in the object denoted by ELF descriptor
 56  .Ar elf .
 57  An error will be signalled if the specified section does not
 58  exist.
 59  .Pp
 60  Function
 61  .Fn elf_ndxscn
 62  returns the section table index associated with section descriptor
 63  .Ar scn .
 64  .Pp
 65  Function
 66  .Fn elf_newscn
 67  creates a new section and appends it to the list of sections
 68  associated with descriptor
 69  .Ar elf .
 70  The library will automatically increment the
 71  .Va e_shnum
 72  field of the ELF header associated with descriptor
 73  .Ar elf ,
 74  and will set the
 75  .Dv ELF_F_DIRTY
 76  flag on the returned section descriptor.
 77  For ELF descriptors opened for writing, the ELF library will
 78  automatically create an empty section at index zero
 79  .Dv ( SHN_UNDEF )
 80  on the first call to
 81  .Fn elf_newscn .
 82  .Pp
 83  Function
 84  .Fn elf_nextscn
 85  takes a section descriptor
 86  .Ar scn
 87  and returns a pointer to the section descriptor at the next higher
 88  index.
 89  Argument
 90  .Ar scn
 91  is allowed to be NULL, in which case this function will return a
 92  pointer to the section descriptor at index 1.
 93  If no further sections are present, function
 94  .Fn elf_nextscn
 95  will return a NULL pointer.
 96  .Sh RETURN VALUES
 97  Functions
 98  .Fn elf_getscn ,
 99  .Fn elf_newscn
100  and
101  .Fn elf_nextscn
102  return a valid pointer to a section descriptor if successful, or
103  NULL if an error occurs.
104  .Pp
105  Function
106  .Fn elf_ndxscn
107  returns a valid section table index if successful, or
108  .Dv SHN_UNDEF
109  if an error occurs.
110  .Sh ERRORS
111  These functions may fail with the following errors:
112  .Bl -tag -width "[ELF_E_RESOURCE]"
113  .It Bq Er ELF_E_ARGUMENT
114  Arguments
115  .Ar elf
116  or
117  .Ar scn
118  were NULL.
119  .It Bq Er ELF_E_ARGUMENT
120  Argument
121  .Ar index
122  exceeded the current number of sections in the ELF object.
123  .It Bq Er ELF_E_ARGUMENT
124  Argument
125  .Ar elf
126  was not a descriptor for an ELF file.
127  .It Bq Er ELF_E_ARGUMENT
128  Section descriptor
129  .Ar scn
130  was not associated with ELF descriptor
131  .Ar elf .
132  .It Bq Er ELF_E_CLASS
133  Descriptor
134  .Ar elf
135  was of an unknown ELF class.
136  .It Bq Er ELF_E_SECTION
137  Argument
138  .Ar elf
139  specified extended section numbering in the ELF header with the section header at
140  index
141  .Dv SHN_UNDEF
142  not being of type
143  .Dv SHT_NULL .
144  .El
145  .Sh SEE ALSO
146  .Xr elf 3 ,
147  .Xr elf_flagdata 3 ,
148  .Xr elf_flagscn 3 ,
149  .Xr elf_getdata 3 ,
150  .Xr elf_getshdr 3 ,
151  .Xr gelf 3