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