contrib/elftoolchain/libelf/elf_getscn.3

   1 .\" Copyright (c) 2006-2008,2018 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: elf_getscn.3 3639 2018-10-14 14:07:02Z jkoshy $
  25 .\"
  26 .Dd September 24, 2018
  27 .Dt ELF_GETSCN 3
  28 .Os
  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 As a consequence,
  90 .Fn elf_nextscn
  91 will never return a pointer to the empty section at index zero
  92 .Dv ( SHN_UNDEF ) .
  93 Argument
  94 .Ar scn
  95 is allowed to be NULL, in which case this function will return a
  96 pointer to the section descriptor at index 1.
  97 If no further sections are present, function
  98 .Fn elf_nextscn
  99 will return a NULL pointer.
 100 .Sh RETURN VALUES
 101 Functions
 102 .Fn elf_getscn ,
 103 .Fn elf_newscn
 104 and
 105 .Fn elf_nextscn
 106 return a valid pointer to a section descriptor if successful, or
 107 NULL if an error occurs.
 108 .Pp
 109 Function
 110 .Fn elf_ndxscn
 111 returns a valid section table index if successful, or
 112 .Dv SHN_UNDEF
 113 if an error occurs.
 114 .Sh ERRORS
 115 These functions may fail with the following errors:
 116 .Bl -tag -width "[ELF_E_RESOURCE]"
 117 .It Bq Er ELF_E_ARGUMENT
 118 Arguments
 119 .Ar elf
 120 or
 121 .Ar scn
 122 were NULL.
 123 .It Bq Er ELF_E_ARGUMENT
 124 Argument
 125 .Ar index
 126 exceeded the current number of sections in the ELF object.
 127 .It Bq Er ELF_E_ARGUMENT
 128 Argument
 129 .Ar elf
 130 was not a descriptor for an ELF file.
 131 .It Bq Er ELF_E_ARGUMENT
 132 Section descriptor
 133 .Ar scn
 134 was not associated with ELF descriptor
 135 .Ar elf .
 136 .It Bq Er ELF_E_CLASS
 137 Descriptor
 138 .Ar elf
 139 was of an unknown ELF class.
 140 .It Bq Er ELF_E_SECTION
 141 Argument
 142 .Ar elf
 143 specified extended section numbering in the ELF header with the section header at
 144 index
 145 .Dv SHN_UNDEF
 146 not being of type
 147 .Dv SHT_NULL .
 148 .El
 149 .Sh SEE ALSO
 150 .Xr elf 3 ,
 151 .Xr elf_flagdata 3 ,
 152 .Xr elf_flagscn 3 ,
 153 .Xr elf_getdata 3 ,
 154 .Xr elf_getshdr 3 ,
 155 .Xr gelf 3