external/bsd/elftoolchain/dist/libelf/gelf_getsymshndx.3

   1 .\"     $NetBSD: gelf_getsymshndx.3,v 1.2 2014/03/09 16:58:04 christos Exp $
   2 .\"
   3 .\" Copyright (c) 2006,2008 Joseph Koshy.  All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" This software is provided by Joseph Koshy ``as is'' and
  15 .\" any express or implied warranties, including, but not limited to, the
  16 .\" implied warranties of merchantability and fitness for a particular purpose
  17 .\" are disclaimed.  in no event shall Joseph Koshy be liable
  18 .\" for any direct, indirect, incidental, special, exemplary, or consequential
  19 .\" damages (including, but not limited to, procurement of substitute goods
  20 .\" or services; loss of use, data, or profits; or business interruption)
  21 .\" however caused and on any theory of liability, whether in contract, strict
  22 .\" liability, or tort (including negligence or otherwise) arising in any way
  23 .\" out of the use of this software, even if advised of the possibility of
  24 .\" such damage.
  25 .\"
  26 .\" Id: gelf_getsymshndx.3 189 2008-07-20 10:38:08Z jkoshy
  27 .\"
  28 .Dd November 5, 2006
  29 .Os
  30 .Dt GELF_GETSYMSHNDX 3
  31 .Sh NAME
  32 .Nm gelf_getsymshndx ,
  33 .Nm gelf_update_symshndx
  34 .Nd read and update symbol information using extended section indices
  35 .Sh LIBRARY
  36 .Lb libelf
  37 .Sh SYNOPSIS
  38 .In gelf.h
  39 .Ft "GElf_Sym *"
  40 .Fo gelf_getsymshndx
  41 .Fa "Elf_Data *symdata"
  42 .Fa "Elf_Data *xndxdata"
  43 .Fa "int ndx"
  44 .Fa "GElf_Sym *sym"
  45 .Fa "Elf32_Word *xndxptr"
  46 .Fc
  47 .Ft int
  48 .Fo gelf_update_symshndx
  49 .Fa "Elf_Data *symdata"
  50 .Fa "Elf_Data *xndxdata"
  51 .Fa "int ndx"
  52 .Fa "GElf_Sym *sym"
  53 .Fa "Elf32_Word xndx"
  54 .Fc
  55 .Sh DESCRIPTION
  56 These functions are analogous to
  57 .Fn gelf_getsym
  58 and
  59 .Fn gelf_update_sym
  60 respectively, but are capable of handling symbol tables using extended
  61 section numbering.
  62 .Pp
  63 Argument
  64 .Ar symdata
  65 is an
  66 .Vt Elf_Data
  67 descriptor associated with a section of type
  68 .Dv SHT_SYMTAB .
  69 Argument
  70 .Ar xndxdata
  71 is an
  72 .Vt Elf_Data
  73 descriptor associated with a section of type
  74 .Dv SHT_SYMTAB_SHNDX .
  75 Argument
  76 .Ar ndx
  77 is the index of the symbol table entry being retrieved or updated.
  78 Argument
  79 .Ar sym
  80 is a pointer to a class-independent
  81 .Vt GElf_Sym
  82 structure.
  83 .Vt GElf_Sym
  84 structures are described in detail in
  85 .Xr gelf 3 .
  86 .Pp
  87 Function
  88 .Fn gelf_getsymshndx
  89 retrieves symbol information at index
  90 .Ar ndx
  91 from the data descriptor specified by argument
  92 .Ar symdata
  93 and stores in class-independent form in argument
  94 .Ar sym .
  95 In addition it retrieves the extended section index for the
  96 symbol from data buffer
  97 .Ar xndxdata
  98 and stores it into the location pointed to by argument
  99 .Ar xndxptr .
 100 .Pp
 101 Function
 102 .Fn gelf_update_symshndx
 103 updates the underlying symbol table entry in data
 104 descriptor
 105 .Ar symdata
 106 with the information in argument
 107 .Ar sym .
 108 In addition it sets the extended section index in
 109 data buffer
 110 .Ar xndxdata
 111 to the value of argument
 112 .Ar xndx .
 113 .Sh RETURN VALUES
 114 Function
 115 .Fn gelf_getsymshndx
 116 returns the value of argument
 117 .Ar sym
 118 if successful, or NULL in case of an error.
 119 .Pp
 120 Function
 121 .Fn gelf_update_symshndx
 122 returns a non-zero value if successful, or zero in case of an error.
 123 .Sh ERRORS
 124 These functions may fail with the following errors:
 125 .Bl -tag -width "[ELF_E_RESOURCE]"
 126 .It Bq Er ELF_E_ARGUMENT
 127 Arguments
 128 .Ar symdata ,
 129 .Ar xndxdata ,
 130 .Ar xndxptr
 131 or
 132 .Ar sym
 133 were NULL.
 134 .It Bq Er ELF_E_ARGUMENT
 135 Argument
 136 .Ar ndx
 137 was less than zero, or too large for either of descriptors
 138 .Ar symdata
 139 or
 140 .Ar xndxdata .
 141 .It Bq Er ELF_E_ARGUMENT
 142 Data descriptor
 143 .Ar symdata
 144 was not associated with a section of type
 145 .Dv SHT_SYMTAB .
 146 .It Bq Er ELF_E_ARGUMENT
 147 Data descriptor
 148 .Ar xndxdata
 149 was not associated with a section of type
 150 .Dv SHT_SYMTAB_SHNDX .
 151 .It Bq Er ELF_E_ARGUMENT
 152 Data descriptor
 153 .Ar symdata
 154 and
 155 .Ar xndxdata
 156 were associated with different ELF objects.
 157 .El
 158 .Sh SEE ALSO
 159 .Xr elf 3 ,
 160 .Xr elf_getdata 3 ,
 161 .Xr elf_getscn 3 ,
 162 .Xr gelf 3 ,
 163 .Xr gelf_getsym 3 ,
 164 .Xr gelf_update_sym 3