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$
 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"
201  .Aq jkoshy@FreeBSD.org .