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