lib/libelf/gelf.3

   1 .\" Copyright (c) 2006 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 .\" $FreeBSD$
  25 .\"
  26 .Dd September 1, 2006
  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_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 -width 8n
 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 -width 2n
 129 .It "Allocating ELF Data Structures"
 130 .Bl -tag -width 19n -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 -width 19n -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 -width 19n -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 -width 19n -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 -width 19n -compact
 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 .