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