lib/libelf/gelf_getsymshndx.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 November 5, 2006
  27 .Os
  28 .Dt GELF_GETSYMSHNDX 3
  29 .Sh NAME
  30 .Nm gelf_getsymshndx ,
  31 .Nm gelf_update_symshndx
  32 .Nd read and update symbol information using extended section indices
  33 .Sh LIBRARY
  34 .Lb libelf
  35 .Sh SYNOPSIS
  36 .In gelf.h
  37 .Ft "GElf_Sym *"
  38 .Fo gelf_getsymshndx
  39 .Fa "Elf_Data *symdata"
  40 .Fa "Elf_Data *xndxdata"
  41 .Fa "int ndx"
  42 .Fa "GElf_Sym *sym"
  43 .Fa "Elf32_Word *xndxptr"
  44 .Fc
  45 .Ft int
  46 .Fo gelf_update_symshndx
  47 .Fa "Elf_Data *symdata"
  48 .Fa "Elf_Data *xndxdata"
  49 .Fa "int ndx"
  50 .Fa "GElf_Sym *sym"
  51 .Fa "Elf32_Word xndx"
  52 .Fc
  53 .Sh DESCRIPTION
  54 These functions are analogous to
  55 .Fn gelf_getsym
  56 and
  57 .Fn gelf_update_sym
  58 respectively, but are capable of handling symbol tables using extended
  59 section numbering.
  60 .Pp
  61 Argument
  62 .Ar symdata
  63 is an
  64 .Vt Elf_Data
  65 descriptor associated with a section of type
  66 .Dv SHT_SYMTAB .
  67 Argument
  68 .Ar xndxdata
  69 is an
  70 .Vt Elf_Data
  71 descriptor associated with a section of type
  72 .Dv SHT_SYMTAB_SHNDX .
  73 Argument
  74 .Ar ndx
  75 is the index of the symbol table entry being retrieved or updated.
  76 Argument
  77 .Ar sym
  78 is a pointer to a class-independent
  79 .Vt GElf_Sym
  80 structure.
  81 .Vt GElf_Sym
  82 structures are described in detail in
  83 .Xr gelf 3 .
  84 .Pp
  85 Function
  86 .Fn gelf_getsymshndx
  87 retrieves symbol information at index
  88 .Ar ndx
  89 from the data descriptor specified by argument
  90 .Ar symdata
  91 and stores in class-independent form in argument
  92 .Ar sym .
  93 In addition it retrieves the extended section index for the
  94 symbol from data buffer
  95 .Ar xndxdata
  96 and stores it into the location pointed to by argument
  97 .Ar xndxptr .
  98 .Pp
  99 Function
 100 .Fn gelf_update_symshndx
 101 updates the underlying symbol table entry in data
 102 descriptor
 103 .Ar symdata
 104 with the information in argument
 105 .Ar sym .
 106 In addition it sets the extended section index in
 107 data buffer
 108 .Ar xndxdata
 109 to the value of argument
 110 .Ar xndx .
 111 .Sh RETURN VALUES
 112 Function
 113 .Fn gelf_getsymshndx
 114 returns the value of argument
 115 .Ar sym
 116 if successful, or NULL in case of an error.
 117 .Pp
 118 Function
 119 .Fn gelf_update_symshndx
 120 returns a non-zero value if successful, or zero in case of an error.
 121 .Sh ERRORS
 122 These functions may fail with the following errors:
 123 .Bl -tag -width "[ELF_E_RESOURCE]"
 124 .It Bq Er ELF_E_ARGUMENT
 125 Arguments
 126 .Ar symdata ,
 127 .Ar xndxdata ,
 128 .Ar xndxptr
 129 or
 130 .Ar sym
 131 were NULL.
 132 .It Bq Er ELF_E_ARGUMENT
 133 Argument
 134 .Ar ndx
 135 was less than zero, or too large for either of descriptors
 136 .Ar symdata
 137 or
 138 .Ar xndxdata .
 139 .It Bq Er ELF_E_ARGUMENT
 140 Data descriptor
 141 .Ar symdata
 142 was not associated with a section of type
 143 .Dv SHT_SYMTAB .
 144 .It Bq Er ELF_E_ARGUMENT
 145 Data descriptor
 146 .Ar xndxdata
 147 was not associated with a section of type
 148 .Dv SHT_SYMTAB_SHNDX .
 149 .It Bq Er ELF_E_ARGUMENT
 150 Data descriptor
 151 .Ar symdata
 152 and
 153 .Ar xndxdata
 154 were associated with different ELF objects.
 155 .El
 156 .Sh SEE ALSO
 157 .Xr elf 3 ,
 158 .Xr elf_getdata 3 ,
 159 .Xr elf_getscn 3 ,
 160 .Xr gelf 3 ,
 161 .Xr gelf_getsym 3 ,
 162 .Xr gelf_update_sym 3