lib/libelf/elf_getdata.3

   1 .\" Copyright (c) 2006 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 .\" $FreeBSD$
  25 .\"
  26 .Dd August 26, 2006
  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 .Sh RETURN VALUES
 146 These functions return a valid pointer to a data descriptor if successful, or
 147 NULL if an error occurs.
 148 .Sh ERRORS
 149 These functions may fail with the following errors:
 150 .Bl -tag -width "[ELF_E_RESOURCE]"
 151 .It Bq Er ELF_E_ARGUMENT
 152 Arguments
 153 .Ar scn
 154 was NULL.
 155 .It Bq Er ELF_E_ARGUMENT
 156 Data descriptor
 157 .Ar data
 158 was not associated with section descriptor
 159 .Ar scn .
 160 .It Bq Er ELF_E_RESOURCE
 161 An out of memory condition was detected.
 162 .El
 163 .Sh SEE ALSO
 164 .Xr elf 3 ,
 165 .Xr elf_flagdata 3 ,
 166 .Xr elf_flagscn 3 ,
 167 .Xr elf_getscn 3 ,
 168 .Xr elf_getshdr 3 ,
 169 .Xr elf_newscn 3 ,
 170 .Xr elf_update 3 ,
 171 .Xr elf_version 3 ,
 172 .Xr gelf 3