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

   1 .\"     $NetBSD: elf_getdata.3,v 1.2 2014/03/09 16:58:04 christos Exp $
   2 .\"
   3 .\" Copyright (c) 2006,2008,2010-2011 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: elf_getdata.3 1766 2011-08-22 06:01:03Z jkoshy
  27 .\"
  28 .Dd January 26, 2011
  29 .Os
  30 .Dt ELF_GETDATA 3
  31 .Sh NAME
  32 .Nm elf_getdata ,
  33 .Nm elf_newdata ,
  34 .Nm elf_rawdata
  35 .Nd iterate through or allocate section data
  36 .Sh LIBRARY
  37 .Lb libelf
  38 .Sh SYNOPSIS
  39 .In libelf.h
  40 .Ft "Elf_Data *"
  41 .Fn elf_getdata "Elf_Scn *scn" "Elf_Data *data"
  42 .Ft "Elf_Data *"
  43 .Fn elf_newdata "Elf_Scn *scn"
  44 .Ft "Elf_Data *"
  45 .Fn elf_rawdata "Elf_Scn *scn" "Elf_Data *data"
  46 .Sh DESCRIPTION
  47 These functions are used to access and manipulate data descriptors
  48 associated with section descriptors.
  49 Data descriptors used by the ELF library are described in
  50 .Xr elf 3 .
  51 .Pp
  52 Function
  53 .Fn elf_getdata
  54 will return the next data descriptor associated with section descriptor
  55 .Ar scn .
  56 The returned data descriptor will be setup to contain translated data.
  57 Argument
  58 .Ar data
  59 may be
  60 .Dv NULL ,
  61 in which case the function returns the first data descriptor
  62 associated with section
  63 .Ar scn .
  64 If argument
  65 .Ar data
  66 is not
  67 .Dv NULL ,
  68 it must be a pointer to a data descriptor associated with
  69 section descriptor
  70 .Ar scn ,
  71 and function
  72 .Fn elf_getdata
  73 will return a pointer to the next data descriptor for the section,
  74 or
  75 .Dv NULL
  76 when the end of the section's descriptor list is reached.
  77 .Pp
  78 Function
  79 .Fn elf_newdata
  80 will allocate a new data descriptor and append it to the list of data
  81 descriptors associated with section descriptor
  82 .Ar scn .
  83 The new data descriptor will be initialized as follows:
  84 .Bl -tag -width "d_version" -compact -offset indent
  85 .It Va d_align
  86 Set to 1.
  87 .It Va d_buf
  88 Initialized to.
  89 .Dv NULL .
  90 .It Va d_off
  91 Set to (off_t) -1.
  92 This field is under application control if the
  93 .Dv ELF_F_LAYOUT
  94 flag was set on the ELF descriptor.
  95 .It Va d_size
  96 Set to zero.
  97 .It Va d_type
  98 Initialized to
  99 .Dv ELF_T_BYTE .
 100 .It Va d_version
 101 Set to the current working version of the library, as set by
 102 .Xr elf_version 3 .
 103 .El
 104 The application must set these values as appropriate before
 105 calling
 106 .Xr elf_update 3 .
 107 Section
 108 .Ar scn
 109 must be associated with an ELF file opened for writing.
 110 If the application has not requested full control of layout by
 111 setting the
 112 .Dv ELF_F_LAYOUT
 113 flag on descriptor
 114 .Ar elf ,
 115 then the data referenced by the returned descriptor will be positioned
 116 after the existing content of the section, honoring the file alignment
 117 specified in member
 118 .Va d_align .
 119 On successful completion of a call to
 120 .Fn elf_newdata ,
 121 the ELF library will mark the section
 122 .Ar scn
 123 as
 124 .Dq dirty .
 125 .Pp
 126 Function
 127 .Fn elf_rawdata
 128 is used to step through the data descriptors associated with
 129 section
 130 .Ar scn .
 131 In contrast to function
 132 .Fn elf_getdata ,
 133 this function returns untranslated data.
 134 If argument
 135 .Ar data
 136 is
 137 .Dv NULL ,
 138 the first data descriptor associated with section
 139 .Ar scn
 140 is returned.
 141 If argument
 142 .Ar data
 143 is not
 144 .Dv NULL ,
 145 is must be a data descriptor associated with
 146 section
 147 .Ar scn ,
 148 and function
 149 .Fn elf_rawdata
 150 will return the next data descriptor in the list, or
 151 .Dv NULL
 152 if no further descriptors are present.
 153 Function
 154 .Fn elf_rawdata
 155 always returns
 156 .Vt Elf_Data
 157 structures of type
 158 .Dv ELF_T_BYTE .
 159 .Ss Special handling of zero-sized and SHT_NOBITS sections
 160 For sections of type
 161 .Dv SHT_NOBITS,
 162 and for zero-sized sections,
 163 the functions
 164 .Fn elf_getdata
 165 and
 166 .Fn elf_rawdata
 167 return a pointer to a valid
 168 .Vt Elf_Data
 169 structure that has its
 170 .Va d_buf
 171 member set to
 172 .Dv NULL
 173 and its
 174 .Va d_size
 175 member set to the size of the section.
 176 .Pp
 177 If an application wishes to create a section of type
 178 .Dv SHT_NOBITS ,
 179 it should add a data buffer to the section using function
 180 .Fn elf_newdata .
 181 It should then set the
 182 .Va d_buf
 183 and
 184 .Va d_size
 185 members of the returned
 186 .Vt Elf_Data
 187 structure to
 188 .Dv NULL
 189 and the desired size of the section respectively.
 190 .Sh RETURN VALUES
 191 These functions return a valid pointer to a data descriptor if successful, or
 192 .Dv NULL
 193 if an error occurs.
 194 .Sh ERRORS
 195 These functions may fail with the following errors:
 196 .Bl -tag -width "[ELF_E_RESOURCE]"
 197 .It Bq Er ELF_E_ARGUMENT
 198 Either of the arguments
 199 .Ar scn
 200 or
 201 .Ar data
 202 was
 203 .Dv NULL .
 204 .It Bq Er ELF_E_ARGUMENT
 205 The data descriptor referenced by argument
 206 .Ar data
 207 is not associated with section descriptor
 208 .Ar scn .
 209 .It Bq Er ELF_E_ARGUMENT
 210 The section denoted by argument
 211 .Ar scn
 212 had no data associated with it.
 213 .It Bq Er ELF_E_DATA
 214 Retrieval of data from the underlying object failed.
 215 .It Bq Er ELF_E_RESOURCE
 216 An out of memory condition was detected.
 217 .It Bq Er ELF_E_SECTION
 218 Section
 219 .Ar scn
 220 had type
 221 .Dv SHT_NULL .
 222 .It Bq Er ELF_E_SECTION
 223 The type of the section
 224 .Ar scn
 225 was not recognized by the library.
 226 .It Bq Er ELF_E_SECTION
 227 The size of the section
 228 .Ar scn
 229 is not a multiple of the file size for its section type.
 230 .It Bq Er ELF_E_SECTION
 231 The file offset for section
 232 .Ar scn
 233 is incorrect.
 234 .It Bq Er ELF_E_UNIMPL
 235 The section type associated with section
 236 .Ar scn
 237 is currently unsupported by the library.
 238 .El
 239 .Sh SEE ALSO
 240 .Xr elf 3 ,
 241 .Xr elf_flagdata 3 ,
 242 .Xr elf_flagscn 3 ,
 243 .Xr elf_getscn 3 ,
 244 .Xr elf_getshdr 3 ,
 245 .Xr elf_newscn 3 ,
 246 .Xr elf_rawfile 3 ,
 247 .Xr elf_update 3 ,
 248 .Xr elf_version 3 ,
 249 .Xr gelf 3