external/bsd/libelf/dist/elf_getdata.3

   1 .\"     $NetBSD$
   2 .\"
   3 .\" Copyright (c) 2006 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 .\" $FreeBSD: src/lib/libelf/elf_getdata.3,v 1.2.10.1.2.1 2009/10/25 01:10:29 kensmith Exp $
  27 .\"
  28 .Dd August 26, 2006
  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 NULL, in which case the function returns the first data descriptor
  60 associated with section
  61 .Ar scn .
  62 If argument
  63 .Ar data
  64 is not NULL, it must be a pointer to a data descriptor associated with
  65 section descriptor
  66 .Ar scn ,
  67 and function
  68 .Fn elf_getdata
  69 will return a pointer to the next data descriptor for the section,
  70 or NULL when the end of the section's descriptor list is reached.
  71 .Pp
  72 Function
  73 .Fn elf_newdata
  74 will allocate a new data descriptor and append it to the list of data
  75 descriptors associated with section descriptor
  76 .Ar scn .
  77 The new data descriptor will be initialized as follows:
  78 .Bl -tag -width "d_version" -compact -offset indent
  79 .It Va d_align
  80 Set to 1.
  81 .It Va d_buf
  82 Initialized to NULL.
  83 .It Va d_off
  84 Set to (off_t) -1.
  85 This field is under application control if the
  86 .Dv ELF_F_LAYOUT
  87 flag was set on the ELF descriptor.
  88 .It Va d_size
  89 Set to zero.
  90 .It Va d_type
  91 Initialized to
  92 .Dv ELF_T_BYTE .
  93 .It Va d_version
  94 Set to the current working version of the library, as set by
  95 .Xr elf_version 3 .
  96 .El
  97 The application must set these values as appropriate before
  98 calling
  99 .Xr elf_update 3 .
 100 Section
 101 .Ar scn
 102 must be associated with an ELF file opened for writing.
 103 If the application has not requested full control of layout by
 104 setting the
 105 .Dv ELF_F_LAYOUT
 106 flag on descriptor
 107 .Ar elf ,
 108 then the data referenced by the returned descriptor will be positioned
 109 after the existing content of the section, honoring the file alignment
 110 specified in member
 111 .Va d_align .
 112 On successful completion of a call to
 113 .Fn elf_newdata ,
 114 the ELF library will mark the section
 115 .Ar scn
 116 as
 117 .Dq dirty .
 118 .Pp
 119 Function
 120 .Fn elf_rawdata
 121 is used to step through the data descriptors associated with
 122 section
 123 .Ar scn .
 124 In contrast to function
 125 .Fn elf_getdata ,
 126 this function returns untranslated data.
 127 If argument
 128 .Ar data
 129 is NULL, the first data descriptor associated with section
 130 .Ar scn
 131 is returned.
 132 If argument
 133 .Ar data
 134 is not NULL, is must be a data descriptor associated with
 135 section
 136 .Ar scn ,
 137 and function
 138 .Fn elf_rawdata
 139 will return the next data descriptor in the list, or NULL
 140 if no further descriptors are present.
 141 Function
 142 .Fn elf_rawdata
 143 always returns
 144 .Vt Elf_Data
 145 structures of type
 146 .Dv ELF_T_BYTE .
 147 .Sh RETURN VALUES
 148 These functions return a valid pointer to a data descriptor if successful, or
 149 NULL if an error occurs.
 150 .Sh ERRORS
 151 These functions may fail with the following errors:
 152 .Bl -tag -width "[ELF_E_RESOURCE]"
 153 .It Bq Er ELF_E_ARGUMENT
 154 Arguments
 155 .Ar scn
 156 was NULL.
 157 .It Bq Er ELF_E_ARGUMENT
 158 Data descriptor
 159 .Ar data
 160 was not associated with section descriptor
 161 .Ar scn .
 162 .It Bq Er ELF_E_RESOURCE
 163 An out of memory condition was detected.
 164 .El
 165 .Sh SEE ALSO
 166 .Xr elf 3 ,
 167 .Xr elf_flagdata 3 ,
 168 .Xr elf_flagscn 3 ,
 169 .Xr elf_getscn 3 ,
 170 .Xr elf_getshdr 3 ,
 171 .Xr elf_newscn 3 ,
 172 .Xr elf_update 3 ,
 173 .Xr elf_version 3 ,
 174 .Xr gelf 3