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