1 .\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved.
3 .\" Redistribution and use in source and binary forms, with or without
4 .\" modification, are permitted provided that the following conditions
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.
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
24 .\" $Id: gelf.3 3743 2019-06-12 19:36:30Z jkoshy $
31 .Nd class-independent API for ELF manipulation
37 This manual page describes a class independent API for manipulating
39 This API allows an application to operate on ELF descriptors without
40 needing to the know the ELF class of the descriptor.
42 The GElf API may be used alongside the ELF API without restriction.
43 .Ss GElf Data Structures
44 The GElf API defines the following class-independent data structures:
45 .Bl -tag -width GElf_Sxword
47 A representation of ELF addresses.
49 A class-independent representation of an ELF Compression Header.
51 A class-independent representation of ELF
55 A class-independent representation of an ELF Executable Header.
57 An unsigned 16 bit quantity.
59 A class-independent representation of a ELF offset.
61 A class-independent representation of an ELF Program Header Table
64 A class-independent representation of an ELF relocation entry.
66 A class-independent representation of an ELF relocation entry with
69 A class-independent representation of an ELF Section Header Table
72 A signed 32 bit quantity.
74 A signed 64 bit quantity.
76 A class-independent representation of an ELF symbol table entry.
78 An unsigned 32 bit quantity.
80 An unsigned 64 bit quantity.
83 These data structures are sized to be compatible with the
84 corresponding 64 bit ELF structures, and have the same internal
85 structure as their 64 bit class-dependent counterparts.
86 Class-dependent ELF structures are described in
88 .Ss GElf Programming Model
89 GElf functions always return a
91 of the underlying (class-dependent) ELF data structure.
92 The programming model with GElf is as follows:
95 An application will retrieve data from an ELF descriptor using a
98 This will copy out data into a private
102 The application will work with its private copy of the GElf
105 Once done, the application copies the new values back to the
106 underlying ELF data structure using the
110 The application will then use the
112 APIs to indicate to the ELF library that an ELF data structure is dirty.
115 When updating an underlying 32 bit ELF data structure, the GElf
116 routines will signal an error if a GElf value is out of range
117 for the underlying ELF data type.
119 The GElf interface uses the following symbols:
120 .Bl -tag -width indent
122 Class-independent data types.
124 For functions defined in the API set.
126 .Ss GElf Programming APIs
127 This section provides an overview of the GElf programming APIs.
128 Further information is provided in the manual page of each function
130 .Bl -tag -width indent
131 .It "Allocating ELF Data Structures"
132 .Bl -tag -compact -width indent
134 Allocate a new ELF Executable Header.
136 Allocate a new ELF Program Header Table.
138 .It "Data Translation"
139 .Bl -tag -compact -width indent
141 Translate the native representation of an ELF data structure to its
144 Translate from the file representation of an ELF data structure to a
145 native representation.
147 .It "Retrieving ELF Data"
148 .Bl -tag -compact -width indent
150 Retrieve an ELF Compression Header from the underlying ELF descriptor.
156 Retrieve an ELF Executable Header from the underlying ELF descriptor.
158 Retrieve an ELF Program Header Table entry from the underlying ELF descriptor.
160 Retrieve an ELF relocation entry.
162 Retrieve an ELF relocation entry with addend.
164 Retrieve an ELF Section Header Table entry from the underlying ELF descriptor.
166 Retrieve an ELF symbol table entry.
169 .Bl -tag -compact -width indent
171 Retrieves the ELF checksum for an ELF descriptor.
173 Retrieves the size of the file representation of an ELF type.
175 Retrieves the ELF class of an ELF descriptor.
177 .It "Updating ELF Data"
178 .Bl -tag -compact -width ".Fn gelf_update_shdr"
179 .It Fn gelf_update_dyn
183 .It Fn gelf_update_phdr
184 Copy back an ELF Program Header Table entry.
185 .It Fn gelf_update_rel
186 Copy back an ELF relocation entry.
187 .It Fn gelf_update_rela
188 Copy back an ELF relocation with addend entry.
189 .It Fn gelf_update_shdr
190 Copy back an ELF Section Header Table entry.
191 .It Fn gelf_update_sym
192 Copy back an ELF symbol table entry.
201 API first appeared in
203 This implementation of the API first appeared in
206 The GElf API was implemented by
207 .An Joseph Koshy Aq Mt jkoshy@FreeBSD.org .