1.\" $NetBSD: gelf.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.3 189 2008-07-20 10:38:08Z jkoshy 27.\" 28.Dd September 1, 2006 29.Os 30.Dt GELF 3 31.Sh NAME 32.Nm GElf 33.Nd class-independent API for ELF manipulation 34.Sh LIBRARY 35.Lb libelf 36.Sh SYNOPSIS 37.In gelf.h 38.Sh DESCRIPTION 39This manual page describes a class independent API for manipulating 40ELF objects. 41This API allows an application to operate on ELF descriptors without 42needing to the know the ELF class of the descriptor. 43.Pp 44The GElf API may be used alongside the ELF API without restriction. 45.Ss GElf Data Structures 46The GElf API defines the following class-independent data structures: 47.Bl -tag -width GElf_Sxword 48.It Vt GElf_Addr 49A representation of ELF addresses. 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 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 131.It "Allocating ELF Data Structures" 132.Bl -tag -compact 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 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 149.It Fn gelf_getdyn 150Retrieve an ELF 151.Sy .dynamic 152table entry. 153.It Fn gelf_getehdr 154Retrieve an ELF Executable Header from the underlying ELF descriptor. 155.It Fn gelf_getphdr 156Retrieve an ELF Program Header Table entry from the underlying ELF descriptor. 157.It Fn gelf_getrel 158Retrieve an ELF relocation entry. 159.It Fn gelf_getrela 160Retrieve an ELF relocation entry with addend. 161.It Fn gelf_getshdr 162Retrieve an ELF Section Header Table entry from the underlying ELF descriptor. 163.It Fn gelf_getsym 164Retrieve an ELF symbol table entry. 165.El 166.It Queries 167.Bl -tag -compact 168.It Fn gelf_checksum 169Retrieves the ELF checksum for an ELF descriptor. 170.It Fn gelf_fsize 171Retrieves the size of the file representation of an ELF type. 172.It Fn gelf_getclass 173Retrieves the ELF class of an ELF descriptor. 174.El 175.It "Updating ELF Data" 176.Bl -tag -compact -width ".Fn gelf_update_shdr" 177.It Fn gelf_update_dyn 178Copy back an ELF 179.Sy .dynamic 180Table entry. 181.It Fn gelf_update_phdr 182Copy back an ELF Program Header Table entry. 183.It Fn gelf_update_rel 184Copy back an ELF relocation entry. 185.It Fn gelf_update_rela 186Copy back an ELF relocation with addend entry. 187.It Fn gelf_update_shdr 188Copy back an ELF Section Header Table entry. 189.It Fn gelf_update_sym 190Copy back an ELF symbol table entry. 191.El 192.El 193.Sh SEE ALSO 194.Xr elf 3 , 195.Xr elf 5 196.Sh HISTORY 197The GELF(3) API first appeared in System V Release 4. 198This implementation of the API first appeared in 199.Fx 7.0 . 200.Sh AUTHORS 201The GElf API was implemented by 202.An "Joseph Koshy" 203.Aq jkoshy@FreeBSD.org . 204