external/bsd/elftoolchain/dist/libelf/gelf.3

   1 .\"     $NetBSD: gelf.3,v 1.2 2014/03/09 16:58:04 christos Exp $
   2 .\"
   3 .\" Copyright (c) 2006,2008 Joseph Koshy.  All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" This software is provided by Joseph Koshy ``as is'' and
  15 .\" any express or implied warranties, including, but not limited to, the
  16 .\" implied warranties of merchantability and fitness for a particular purpose
  17 .\" are disclaimed.  in no event shall Joseph Koshy be liable
  18 .\" for any direct, indirect, incidental, special, exemplary, or consequential
  19 .\" damages (including, but not limited to, procurement of substitute goods
  20 .\" or services; loss of use, data, or profits; or business interruption)
  21 .\" however caused and on any theory of liability, whether in contract, strict
  22 .\" liability, or tort (including negligence or otherwise) arising in any way
  23 .\" out of the use of this software, even if advised of the possibility of
  24 .\" such damage.
  25 .\"
  26 .\" Id: gelf.3 189 2008-07-20 10:38:08Z jkoshy
  27 .\"
  28 .Dd September 1, 2006
  29 .Os
  30 .Dt GELF 3
  31 .Sh NAME
  32 .Nm GElf
  33 .Nd class-independent API for ELF manipulation
  34 .Sh LIBRARY
  35 .Lb libelf
  36 .Sh SYNOPSIS
  37 .In gelf.h
  38 .Sh DESCRIPTION
  39 This manual page describes a class independent API for manipulating
  40 ELF objects.
  41 This API allows an application to operate on ELF descriptors without
  42 needing to the know the ELF class of the descriptor.
  43 .Pp
  44 The GElf API may be used alongside the ELF API without restriction.
  45 .Ss GElf Data Structures
  46 The GElf API defines the following class-independent data structures:
  47 .Bl -tag -width GElf_Sxword
  48 .It Vt GElf_Addr
  49 A representation of ELF addresses.
  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
 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
 131 .It "Allocating ELF Data Structures"
 132 .Bl -tag -compact
 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
 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
 149 .It Fn gelf_getdyn
 150 Retrieve an ELF
 151 .Sy .dynamic
 152 table entry.
 153 .It Fn gelf_getehdr
 154 Retrieve an ELF Executable Header from the underlying ELF descriptor.
 155 .It Fn gelf_getphdr
 156 Retrieve an ELF Program Header Table entry from the underlying ELF descriptor.
 157 .It Fn gelf_getrel
 158 Retrieve an ELF relocation entry.
 159 .It Fn gelf_getrela
 160 Retrieve an ELF relocation entry with addend.
 161 .It Fn gelf_getshdr
 162 Retrieve an ELF Section Header Table entry from the underlying ELF descriptor.
 163 .It Fn gelf_getsym
 164 Retrieve an ELF symbol table entry.
 165 .El
 166 .It Queries
 167 .Bl -tag -compact
 168 .It Fn gelf_checksum
 169 Retrieves the ELF checksum for an ELF descriptor.
 170 .It Fn gelf_fsize
 171 Retrieves the size of the file representation of an ELF type.
 172 .It Fn gelf_getclass
 173 Retrieves the ELF class of an ELF descriptor.
 174 .El
 175 .It "Updating ELF Data"
 176 .Bl -tag -compact -width ".Fn gelf_update_shdr"
 177 .It Fn gelf_update_dyn
 178 Copy back an ELF
 179 .Sy .dynamic
 180 Table entry.
 181 .It Fn gelf_update_phdr
 182 Copy back an ELF Program Header Table entry.
 183 .It Fn gelf_update_rel
 184 Copy back an ELF relocation entry.
 185 .It Fn gelf_update_rela
 186 Copy back an ELF relocation with addend entry.
 187 .It Fn gelf_update_shdr
 188 Copy back an ELF Section Header Table entry.
 189 .It Fn gelf_update_sym
 190 Copy back an ELF symbol table entry.
 191 .El
 192 .El
 193 .Sh SEE ALSO
 194 .Xr elf 3 ,
 195 .Xr elf 5
 196 .Sh HISTORY
 197 The GELF(3) API first appeared in System V Release 4.
 198 This implementation of the API first appeared in
 199 .Fx 7.0 .
 200 .Sh AUTHORS
 201 The GElf API was implemented by
 202 .An "Joseph Koshy"
 203 .Aq jkoshy@FreeBSD.org .