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