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.3 3743 2019-06-12 19:36:30Z jkoshy $ 25.\" 26.Dd October 23, 2020 27.Dt GELF 3 28.Os 29.Sh NAME 30.Nm gelf 31.Nd class-independent API for ELF manipulation 32.Sh LIBRARY 33.Lb libelf 34.Sh SYNOPSIS 35.In gelf.h 36.Sh DESCRIPTION 37This manual page describes a class independent API for manipulating 38ELF objects. 39This API allows an application to operate on ELF descriptors without 40needing to the know the ELF class of the descriptor. 41.Pp 42The GElf API may be used alongside the ELF API without restriction. 43.Ss GElf Data Structures 44The GElf API defines the following class-independent data structures: 45.Bl -tag -width GElf_Sxword 46.It Vt GElf_Addr 47A representation of ELF addresses. 48.It Vt GElf_Chdr 49A class-independent representation of an ELF Compression Header. 50.It Vt GElf_Dyn 51A class-independent representation of ELF 52.Sy .dynamic 53section entries. 54.It Vt GElf_Ehdr 55A class-independent representation of an ELF Executable Header. 56.It Vt GElf_Half 57An unsigned 16 bit quantity. 58.It Vt GElf_Off 59A class-independent representation of a ELF offset. 60.It Vt GElf_Phdr 61A class-independent representation of an ELF Program Header Table 62entry. 63.It Vt GElf_Rel 64A class-independent representation of an ELF relocation entry. 65.It Vt GElf_Rela 66A class-independent representation of an ELF relocation entry with 67addend. 68.It Vt GElf_Shdr 69A class-independent representation of an ELF Section Header Table 70entry. 71.It Vt GElf_Sword 72A signed 32 bit quantity. 73.It Vt GElf_Sxword 74A signed 64 bit quantity. 75.It Vt GElf_Sym 76A class-independent representation of an ELF symbol table entry. 77.It Vt GElf_Word 78An unsigned 32 bit quantity. 79.It Vt GElf_Xword 80An unsigned 64 bit quantity. 81.El 82.Pp 83These data structures are sized to be compatible with the 84corresponding 64 bit ELF structures, and have the same internal 85structure as their 64 bit class-dependent counterparts. 86Class-dependent ELF structures are described in 87.Xr elf 5 . 88.Ss GElf Programming Model 89GElf functions always return a 90.Em copy 91of the underlying (class-dependent) ELF data structure. 92The programming model with GElf is as follows: 93.Bl -enum 94.It 95An application will retrieve data from an ELF descriptor using a 96.Fn gelf_get_* 97function. 98This will copy out data into a private 99.Vt GElf_* 100data structure. 101.It 102The application will work with its private copy of the GElf 103structure. 104.It 105Once done, the application copies the new values back to the 106underlying ELF data structure using the 107.Fn gelf_update_* 108functions. 109.It 110The application will then use the 111.Fn elf_flag* 112APIs to indicate to the ELF library that an ELF data structure is dirty. 113.El 114.Pp 115When updating an underlying 32 bit ELF data structure, the GElf 116routines will signal an error if a GElf value is out of range 117for the underlying ELF data type. 118.Ss Namespace use 119The GElf interface uses the following symbols: 120.Bl -tag -width indent 121.It GElf_* 122Class-independent data types. 123.It gelf_* 124For functions defined in the API set. 125.El 126.Ss GElf Programming APIs 127This section provides an overview of the GElf programming APIs. 128Further information is provided in the manual page of each function 129listed here. 130.Bl -tag -width indent 131.It "Allocating ELF Data Structures" 132.Bl -tag -compact -width indent 133.It Fn gelf_newehdr 134Allocate a new ELF Executable Header. 135.It Fn gelf_newphdr 136Allocate a new ELF Program Header Table. 137.El 138.It "Data Translation" 139.Bl -tag -compact -width indent 140.It Fn gelf_xlatetof 141Translate the native representation of an ELF data structure to its 142file representation. 143.It Fn gelf_xlatetom 144Translate from the file representation of an ELF data structure to a 145native representation. 146.El 147.It "Retrieving ELF Data" 148.Bl -tag -compact -width indent 149.It Fn gelf_getchdr 150Retrieve an ELF Compression Header from the underlying ELF descriptor. 151.It Fn gelf_getdyn 152Retrieve an ELF 153.Sy .dynamic 154table entry. 155.It Fn gelf_getehdr 156Retrieve an ELF Executable Header from the underlying ELF descriptor. 157.It Fn gelf_getphdr 158Retrieve an ELF Program Header Table entry from the underlying ELF descriptor. 159.It Fn gelf_getrel 160Retrieve an ELF relocation entry. 161.It Fn gelf_getrela 162Retrieve an ELF relocation entry with addend. 163.It Fn gelf_getshdr 164Retrieve an ELF Section Header Table entry from the underlying ELF descriptor. 165.It Fn gelf_getsym 166Retrieve an ELF symbol table entry. 167.El 168.It Queries 169.Bl -tag -compact -width indent 170.It Fn gelf_checksum 171Retrieves the ELF checksum for an ELF descriptor. 172.It Fn gelf_fsize 173Retrieves the size of the file representation of an ELF type. 174.It Fn gelf_getclass 175Retrieves the ELF class of an ELF descriptor. 176.El 177.It "Updating ELF Data" 178.Bl -tag -compact -width ".Fn gelf_update_shdr" 179.It Fn gelf_update_dyn 180Copy back an ELF 181.Sy .dynamic 182Table entry. 183.It Fn gelf_update_phdr 184Copy back an ELF Program Header Table entry. 185.It Fn gelf_update_rel 186Copy back an ELF relocation entry. 187.It Fn gelf_update_rela 188Copy back an ELF relocation with addend entry. 189.It Fn gelf_update_shdr 190Copy back an ELF Section Header Table entry. 191.It Fn gelf_update_sym 192Copy back an ELF symbol table entry. 193.El 194.El 195.Sh SEE ALSO 196.Xr elf 3 , 197.Xr elf 5 198.Sh HISTORY 199The 200.Nm 201API first appeared in 202.At V.4 . 203This implementation of the API first appeared in 204.Fx 7.0 . 205.Sh AUTHORS 206The GElf API was implemented by 207.An Joseph Koshy Aq Mt jkoshy@FreeBSD.org . 208