contrib/elftoolchain/libelf/gelf_xlatetof.3

   1 .\" Copyright (c) 2006,2008,2018 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: gelf_xlatetof.3 3639 2018-10-14 14:07:02Z jkoshy $
  25 .\"
  26 .Dd October 11, 2018
  27 .Dt GELF_XLATETOF 3
  28 .Os
  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 file_encoding"
  40 .Ft "Elf_Data *"
  41 .Fn elf32_xlatetom "Elf_Data *dst" "Elf_Data *src" "unsigned int file_encoding"
  42 .Ft "Elf_Data *"
  43 .Fn elf64_xlatetof "Elf_Data *dst" "Elf_Data *src" "unsigned int file_encoding"
  44 .Ft "Elf_Data *"
  45 .Fn elf64_xlatetom "Elf_Data *dst" "Elf_Data *src" "unsigned int file_encoding"
  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 file_encoding"
  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 file_encoding"
  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 conform to
  65 the byte ordering and data alignment restrictions dictated by the host
  66 processor.
  67 As described in
  68 .Xr elf 3 ,
  69 the file representation of this data structure could use a different byte
  70 ordering from that of the host, or could use a different layout within
  71 the file.
  72 .Pp
  73 Functions
  74 .Fn elf32_xlatetom ,
  75 .Fn elf64_xlatetom ,
  76 and
  77 .Fn gelf_xlatetom
  78 translate data from file representations to native, in-memory representations.
  79 Functions
  80 .Fn elf32_xlatetof ,
  81 .Fn elf64_xlatetof ,
  82 and
  83 .Fn gelf_xlatetof
  84 translate data from in-memory representations to file representations.
  85 .Pp
  86 Argument
  87 .Ar src
  88 denotes an
  89 .Vt Elf_Data
  90 descriptor describing the source to be translated.
  91 The following elements of the descriptor need to be set before
  92 invoking these functions:
  93 .Bl -hang -offset indent
  94 .It Va d_buf
  95 Set to a valid pointer value denoting the beginning of the data area
  96 to be translated.
  97 .It Va d_size
  98 Set to the total size in bytes of the source data area to be
  99 translated.
 100 .It Va d_type
 101 Set to the type of the source data being translated.
 102 This value is one of the values defined in the
 103 .Vt Elf_Type
 104 enumeration.
 105 The
 106 .Vt Elf_Type
 107 enumeration is described in
 108 .Xr elf 3 .
 109 .It Va d_version
 110 Set to the version number of the ELF data structures being
 111 translated.
 112 Currently only version
 113 .Dv EV_CURRENT
 114 is supported.
 115 .El
 116 .Pp
 117 Argument
 118 .Ar dst
 119 describes the destination buffer.
 120 The following elements of the
 121 .Vt Elf_Data
 122 descriptor need to be set before invoking these functions:
 123 .Bl -hang -offset indent
 124 .It Va d_buf
 125 Set to a valid pointer value that denotes the start of the destination
 126 buffer that will hold translated data.
 127 This value may be the same as that of the source buffer, in which case
 128 an in-place conversion will be attempted.
 129 .It Va d_size
 130 Set to the size of the destination buffer in bytes.
 131 This value will be modified if the function call succeeds.
 132 .It Va d_version
 133 Set to the desired version number of the destination.
 134 Currently only version
 135 .Dv EV_CURRENT
 136 is supported.
 137 .El
 138 .Pp
 139 These translations routines allow the source and destination buffers
 140 to coincide, in which case an in-place translation will be done
 141 if the destination is large enough to hold the translated data.
 142 Other kinds of overlap between the source and destination buffers
 143 are not permitted.
 144 .Pp
 145 On successful completion of the translation request the following
 146 fields of the
 147 .Ar dst
 148 descriptor would be modified:
 149 .Bl -hang -offset indent
 150 .It Va d_size
 151 Set to the size in bytes of the translated data.
 152 .It Va d_type
 153 Set to the
 154 .Va d_type
 155 value of the source data descriptor.
 156 .El
 157 .Pp
 158 Argument
 159 .Ar file_encoding
 160 specifies the encoding in which the file objects are represented.
 161 It must be one of:
 162 .Bl -hang -offset indent
 163 .It Dv ELFDATANONE
 164 File objects use the library's native byte ordering.
 165 .It Dv ELFDATA2LSB
 166 File objects use a little-endian ordering.
 167 .It Dv ELFDATA2MSB
 168 File objects use a big-endian ordering.
 169 .El
 170 .Pp
 171 The functions
 172 .Fn gelf_xlatetof
 173 and
 174 .Fn gelf_xlatetom
 175 select the appropriate translation scheme based on the properties of
 176 argument
 177 .Ar elf .
 178 .Sh RETURN VALUES
 179 These functions return argument
 180 .Ar dst
 181 if successful, or NULL in case of an error.
 182 .Sh EXAMPLES
 183 To translate a
 184 .Vt GElf_Rel
 185 structure to its LSB file representation use:
 186 .Bd -literal -offset indent
 187 Elf_Data dst, src;
 188 GElf_Rel rel;
 189 Elf *e;
 190
 191 e = ...; /* See elf_begin(3). */
 192
 193 /* Set up the 'src' descriptor. */
 194 memset(&src, 0, sizeof src);
 195 src.d_buf = &rel;
 196 src.d_size = sizeof(rel);
 197 src.d_type = ELF_T_REL;
 198 src.d_version = EV_CURRENT;
 199
 200 /* Set up the 'dst' descriptor. */
 201 memset(&dst, 0, sizeof dst);
 202 dst.d_buf = filebuf;
 203 dst.d_size = gelf_fsize(e, ELF_T_REL, 1, EV_CURRENT);
 204 dst.d_version = EV_CURRENT;
 205
 206 if (gelf_xlatetof(e, &dst, &src, ELFDATA2LSB) == NULL) {
 207         printf("error: %s", elf_errmsg(0));
 208 }
 209 .Ed
 210 .Sh ERRORS
 211 These functions may fail with the following errors:
 212 .Bl -tag -width "[ELF_E_RESOURCE]"
 213 .It Bq Er ELF_E_ARGUMENT
 214 One of arguments
 215 .Ar src ,
 216 .Ar dst
 217 or
 218 .Ar elf
 219 was NULL.
 220 .It Bq Er ELF_E_ARGUMENT
 221 Arguments
 222 .Ar src
 223 and
 224 .Ar dst
 225 were equal.
 226 .It Bq Er ELF_E_ARGUMENT
 227 The desired encoding parameter was not one of
 228 .Dv ELFDATANONE ,
 229 .Dv ELFDATA2LSB
 230 or
 231 .Dv ELFDATA2MSB .
 232 .It Bq Er ELF_E_ARGUMENT
 233 The
 234 .Ar d_type
 235 field of argument
 236 .Ar src
 237 specified an unsupported type.
 238 .It Bq Er ELF_E_DATA
 239 The
 240 .Ar src
 241 argument specified a buffer size that was not an integral multiple of
 242 its underlying type.
 243 .It Bq Er ELF_E_DATA
 244 The
 245 .Ar dst
 246 argument specified a buffer size that was too small.
 247 .It Bq Er ELF_E_DATA
 248 Argument
 249 .Ar dst
 250 specified a destination buffer that overlaps with the source
 251 buffer.
 252 .It Bq Er ELF_E_DATA
 253 The destination buffer for a conversion to memory had an alignment
 254 inappropriate for the underlying ELF type.
 255 .It Bq Er ELF_E_DATA
 256 The source buffer for a conversion to file had an alignment
 257 inappropriate for the underlying ELF type.
 258 .It Bq Er ELF_E_UNIMPL
 259 The version numbers for arguments
 260 .Ar dst
 261 and
 262 .Ar src
 263 were not identical.
 264 .It Bq Er ELF_E_UNIMPL
 265 The argument
 266 .Ar src
 267 requested conversion for a type which is not currently
 268 supported.
 269 .It Bq Er ELF_E_VERSION
 270 Argument
 271 .Ar src
 272 specified an unsupported version number.
 273 .El
 274 .Sh SEE ALSO
 275 .Xr elf 3 ,
 276 .Xr elf_getdata 3 ,
 277 .Xr gelf 3