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