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