lib/libelf/elf_getscn.3

   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