lib/libelf/gelf_xlatetof.3

   1 .\" Copyright (c) 2006,2008 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 July 24, 2006
  27 .Os
  28 .Dt GELF_XLATETOF 3
  29 .Sh NAME
  30 .Nm elf32_xlate ,
  31 .Nm elf64_xlate ,
  32 .Nm gelf_xlate
  33 .Nd translate data between files and memory
  34 .Sh LIBRARY
  35 .Lb libelf
  36 .Sh SYNOPSIS
  37 .In libelf.h
  38 .Ft "Elf_Data *"
  39 .Fn elf32_xlatetof "Elf_Data *dst" "Elf_Data *src" "unsigned int encode"
  40 .Ft "Elf_Data *"
  41 .Fn elf32_xlatetom "Elf_Data *dst" "Elf_Data *src" "unsigned int encode"
  42 .Ft "Elf_Data *"
  43 .Fn elf64_xlatetof "Elf_Data *dst" "Elf_Data *src" "unsigned int encode"
  44 .Ft "Elf_Data *"
  45 .Fn elf64_xlatetom "Elf_Data *dst" "Elf_Data *src" "unsigned int encode"
  46 .In gelf.h
  47 .Ft "Elf_Data *"
  48 .Fo gelf_xlatetof
  49 .Fa "Elf *elf"
  50 .Fa "Elf_Data *dst"
  51 .Fa "Elf_Data *src"
  52 .Fa "unsigned int encode"
  53 .Fc
  54 .Ft "Elf_Data *"
  55 .Fo gelf_xlatetom
  56 .Fa "Elf *elf"
  57 .Fa "Elf_Data *dst"
  58 .Fa "Elf_Data *src"
  59 .Fa "unsigned int encode"
  60 .Fc
  61 .Sh DESCRIPTION
  62 These functions translate between the file and memory representations
  63 of ELF data structures.
  64 The in-memory representation of an ELF data structure would confirm to
  65 the byte ordering and data alignment restrictions dictated by the host
  66 processor.
  67 A file representation of the same data structure could use a non-native byte
  68 ordering and in addition may be laid out differently with the file.
  69 .Pp
  70 Functions
  71 .Fn elf32_xlatetom ,
  72 .Fn elf64_xlatetom ,
  73 and
  74 .Fn gelf_xlatetom
  75 translate data from file representations to native, in-memory representations.
  76 Functions
  77 .Fn elf32_xlatetof ,
  78 .Fn elf64_xlatetof ,
  79 and
  80 .Fn gelf_xlatetof
  81 translate data from in-memory representations to file representations.
  82 .Pp
  83 Argument
  84 .Ar src
  85 denotes an
  86 .Vt Elf_Data
  87 descriptor describing the source to be translated.
  88 The following elements of the descriptor need to be set before
  89 invoking these functions:
  90 .Bl -hang -offset indent
  91 .It Va d_buf
  92 Set to a valid pointer value denoting the beginning of the data area
  93 to be translated.
  94 .It Va d_size
  95 Set to the total size in bytes of the source data area to be
  96 translated.
  97 .It Va d_type
  98 Set to the type of the source data being translated.
  99 This value is one of the values defined in the
 100 .Vt Elf_Type
 101 enumeration.
 102 The
 103 .Vt Elf_Type
 104 enumeration is described in
 105 .Xr elf 3 .
 106 .It Va d_version
 107 Set to the version number of the ELF data structures being
 108 translated.
 109 Currently only version
 110 .Dv EV_CURRENT
 111 is supported.
 112 .El
 113 .Pp
 114 Argument
 115 .Ar dst
 116 describes the destination buffer.
 117 The following elements of the
 118 .Vt Elf_Data
 119 descriptor need to be set before invoking these functions:
 120 .Bl -hang -offset indent
 121 .It Va d_buf
 122 Set to a valid pointer value that denotes the start of the destination
 123 buffer that will hold translated data.
 124 This value may be the same as that of the source buffer, in which case
 125 an in-place conversion will be attempted.
 126 .It Va d_size
 127 Set to the size of the destination buffer in bytes.
 128 This value will be modified if the function call succeeds.
 129 .It Va d_version
 130 Set to the desired version number of the destination.
 131 Currently only version
 132 .Dv EV_CURRENT
 133 is supported.
 134 .El
 135 .Pp
 136 These translations routines allow the source and destination buffers
 137 to coincide, in which case an in-place translation will be done
 138 if the destination is large enough to hold the translated data.
 139 Other kinds of overlap between the source and destination buffers
 140 are not permitted.
 141 .Pp
 142 On successful completion of the translation request the following
 143 fields of the
 144 .Ar dst
 145 descriptor would be modified:
 146 .Bl -hang -offset indent
 147 .It Va d_size
 148 Set to the size in bytes of the translated data.
 149 .It Va d_type
 150 Set to the
 151 .Va d_type
 152 value of the source data descriptor.
 153 .El
 154 .Pp
 155 Argument
 156 .Ar encode
 157 specifies the encoding in which the file objects are represented.
 158 It must be one of:
 159 .Bl -hang -offset indent
 160 .It Dv ELFDATANONE
 161 File objects use the library's native byte ordering.
 162 .It Dv ELFDATA2LSB
 163 File objects use a little-endian ordering.
 164 .It Dv ELFDATA2MSB
 165 File objects use a big-endian ordering.
 166 .El
 167 .Pp
 168 The functions
 169 .Fn gelf_xlatetof
 170 and
 171 .Fn gelf_xlatetom
 172 select the appropriate 32 or 64 bit translations based on the class of argument
 173 .Ar elf .
 174 .Sh RETURN VALUES
 175 These functions return argument
 176 .Ar dst
 177 if successful, or NULL in case of an error.
 178 .Sh EXAMPLES
 179 TODO
 180 .Sh ERRORS
 181 These functions may fail with the following errors:
 182 .Bl -tag -width "[ELF_E_RESOURCE]"
 183 .It Bq Er ELF_E_ARGUMENT
 184 One of arguments
 185 .Ar src ,
 186 .Ar dst
 187 or
 188 .Ar elf
 189 was NULL.
 190 .It Bq Er ELF_E_ARGUMENT
 191 Arguments
 192 .Ar src
 193 and
 194 .Ar dst
 195 were equal.
 196 .It Bq Er ELF_E_ARGUMENT
 197 The desired encoding parameter was not one of
 198 .Dv ELFDATANONE ,
 199 .Dv ELFDATA2LSB
 200 or
 201 .Dv ELFDATA2MSB .
 202 .It Bq Er ELF_E_ARGUMENT
 203 The
 204 .Ar d_type
 205 field of argument
 206 .Ar src
 207 specified an unsupported type.
 208 .It Bq Er ELF_E_DATA
 209 The
 210 .Ar src
 211 argument specified a buffer size that was not an integral multiple of
 212 its underlying type.
 213 .It Bq Er ELF_E_DATA
 214 The
 215 .Ar dst
 216 argument specified a buffer size that was too small.
 217 .It Bq Er ELF_E_DATA
 218 Argument
 219 .Ar dst
 220 specified a destination buffer that overlaps with the source
 221 buffer.
 222 .It Bq Er ELF_E_DATA
 223 The destination buffer for a conversion to memory had an alignment
 224 inappropriate for the underlying ELF type.
 225 .It Bq Er ELF_E_DATA
 226 The source buffer for a conversion to file had an alignment
 227 inappropriate for the underlying ELF type.
 228 .It Bq Er ELF_E_UNIMPL
 229 The version numbers for arguments
 230 .Ar dst
 231 and
 232 .Ar src
 233 were not identical.
 234 .It Bq Er ELF_E_UNIMPL
 235 The argument
 236 .Ar src
 237 requested conversion for a type which is not currently
 238 supported.
 239 .It Bq Er ELF_E_VERSION
 240 Argument
 241 .Ar src
 242 specified an unsupported version number.
 243 .El
 244 .Sh SEE ALSO
 245 .Xr elf 3 ,
 246 .Xr elf_getdata 3 ,
 247 .Xr gelf 3