contrib/elftoolchain/libelf/gelf.3

   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 3743 2019-06-12 19:36:30Z jkoshy $
  25 .\"
  26 .Dd October 23, 2020
  27 .Dt GELF 3
  28 .Os
  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_Chdr
  49 A class-independent representation of an ELF Compression Header.
  50 .It Vt GElf_Dyn
  51 A class-independent representation of ELF
  52 .Sy .dynamic
  53 section entries.
  54 .It Vt GElf_Ehdr
  55 A class-independent representation of an ELF Executable Header.
  56 .It Vt GElf_Half
  57 An unsigned 16 bit quantity.
  58 .It Vt GElf_Off
  59 A class-independent representation of a ELF offset.
  60 .It Vt GElf_Phdr
  61 A class-independent representation of an ELF Program Header Table
  62 entry.
  63 .It Vt GElf_Rel
  64 A class-independent representation of an ELF relocation entry.
  65 .It Vt GElf_Rela
  66 A class-independent representation of an ELF relocation entry with
  67 addend.
  68 .It Vt GElf_Shdr
  69 A class-independent representation of an ELF Section Header Table
  70 entry.
  71 .It Vt GElf_Sword
  72 A signed 32 bit quantity.
  73 .It Vt GElf_Sxword
  74 A signed 64 bit quantity.
  75 .It Vt GElf_Sym
  76 A class-independent representation of an ELF symbol table entry.
  77 .It Vt GElf_Word
  78 An unsigned 32 bit quantity.
  79 .It Vt GElf_Xword
  80 An unsigned 64 bit quantity.
  81 .El
  82 .Pp
  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
  87 .Xr elf 5 .
  88 .Ss GElf Programming Model
  89 GElf functions always return a
  90 .Em copy
  91 of the underlying (class-dependent) ELF data structure.
  92 The programming model with GElf is as follows:
  93 .Bl -enum
  94 .It
  95 An application will retrieve data from an ELF descriptor using a
  96 .Fn gelf_get_*
  97 function.
  98 This will copy out data into a private
  99 .Vt GElf_*
 100 data structure.
 101 .It
 102 The application will work with its private copy of the GElf
 103 structure.
 104 .It
 105 Once done, the application copies the new values back to the
 106 underlying ELF data structure using the
 107 .Fn gelf_update_*
 108 functions.
 109 .It
 110 The application will then use the
 111 .Fn elf_flag*
 112 APIs to indicate to the ELF library that an ELF data structure is dirty.
 113 .El
 114 .Pp
 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.
 118 .Ss Namespace use
 119 The GElf interface uses the following symbols:
 120 .Bl -tag -width indent
 121 .It GElf_*
 122 Class-independent data types.
 123 .It gelf_*
 124 For functions defined in the API set.
 125 .El
 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
 129 listed here.
 130 .Bl -tag -width indent
 131 .It "Allocating ELF Data Structures"
 132 .Bl -tag -compact -width indent
 133 .It Fn gelf_newehdr
 134 Allocate a new ELF Executable Header.
 135 .It Fn gelf_newphdr
 136 Allocate a new ELF Program Header Table.
 137 .El
 138 .It "Data Translation"
 139 .Bl -tag -compact -width indent
 140 .It Fn gelf_xlatetof
 141 Translate the native representation of an ELF data structure to its
 142 file representation.
 143 .It Fn gelf_xlatetom
 144 Translate from the file representation of an ELF data structure to a
 145 native representation.
 146 .El
 147 .It "Retrieving ELF Data"
 148 .Bl -tag -compact -width indent
 149 .It Fn gelf_getchdr
 150 Retrieve an ELF Compression Header from the underlying ELF descriptor.
 151 .It Fn gelf_getdyn
 152 Retrieve an ELF
 153 .Sy .dynamic
 154 table entry.
 155 .It Fn gelf_getehdr
 156 Retrieve an ELF Executable Header from the underlying ELF descriptor.
 157 .It Fn gelf_getphdr
 158 Retrieve an ELF Program Header Table entry from the underlying ELF descriptor.
 159 .It Fn gelf_getrel
 160 Retrieve an ELF relocation entry.
 161 .It Fn gelf_getrela
 162 Retrieve an ELF relocation entry with addend.
 163 .It Fn gelf_getshdr
 164 Retrieve an ELF Section Header Table entry from the underlying ELF descriptor.
 165 .It Fn gelf_getsym
 166 Retrieve an ELF symbol table entry.
 167 .El
 168 .It Queries
 169 .Bl -tag -compact -width indent
 170 .It Fn gelf_checksum
 171 Retrieves the ELF checksum for an ELF descriptor.
 172 .It Fn gelf_fsize
 173 Retrieves the size of the file representation of an ELF type.
 174 .It Fn gelf_getclass
 175 Retrieves the ELF class of an ELF descriptor.
 176 .El
 177 .It "Updating ELF Data"
 178 .Bl -tag -compact -width ".Fn gelf_update_shdr"
 179 .It Fn gelf_update_dyn
 180 Copy back an ELF
 181 .Sy .dynamic
 182 Table entry.
 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.
 193 .El
 194 .El
 195 .Sh SEE ALSO
 196 .Xr elf 3 ,
 197 .Xr elf 5
 198 .Sh HISTORY
 199 The
 200 .Nm
 201 API first appeared in
 202 .At V.4 .
 203 This implementation of the API first appeared in
 204 .Fx 7.0 .
 205 .Sh AUTHORS
 206 The GElf API was implemented by
 207 .An Joseph Koshy Aq Mt jkoshy@FreeBSD.org .