lib/libelf/elf_getdata.3

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