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