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

   1 .\"     $NetBSD: gelf_getphdr.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_getphdr.3 189 2008-07-20 10:38:08Z jkoshy
  27 .\"
  28 .Dd October 21, 2007
  29 .Os
  30 .Dt GELF_GETPHDR 3
  31 .Sh NAME
  32 .Nm elf32_getphdr ,
  33 .Nm elf64_getphdr ,
  34 .Nm gelf_getphdr
  35 .Nd retrieve an ELF program header table
  36 .Sh LIBRARY
  37 .Lb libelf
  38 .Sh SYNOPSIS
  39 .In libelf.h
  40 .Ft "Elf32_Phdr *"
  41 .Fn elf32_getphdr "Elf *elf"
  42 .Ft "Elf64_Phdr *"
  43 .Fn elf64_getphdr "Elf *elf"
  44 .In gelf.h
  45 .Ft "GElf_Phdr *"
  46 .Fn gelf_getphdr "Elf *elf" "int index" "GElf_Phdr *dst"
  47 .Sh DESCRIPTION
  48 These functions retrieve and translate ELF program header information
  49 from an ELF descriptor, if this information exists.
  50 .Pp
  51 Functions
  52 .Fn elf32_getphdr
  53 and
  54 .Fn elf64_getphdr
  55 return a pointer to an array of translated
  56 .Vt Elf32_Phdr
  57 and
  58 .Vt Elf64_Phdr
  59 descriptors respectively.
  60 These descriptors are described in
  61 .Xr elf 5 .
  62 The number of entries in this array may be determined using the
  63 .Xr elf_getphnum 3
  64 function.
  65 .Pp
  66 Function
  67 .Fn gelf_getphdr
  68 will retrieve the program header table entry at index
  69 .Ar index
  70 from ELF descriptor
  71 .Ar elf.
  72 The translated program header table entry will be written to the
  73 address pointed to be argument
  74 .Ar dst .
  75 .Pp
  76 Applications may inform the library of modifications to a program header table entry
  77 by using the
  78 .Xr elf_flagphdr 3
  79 API.
  80 Applications using the
  81 .Xr gelf 3
  82 interface need to use the
  83 .Xr gelf_update_phdr 3
  84 API to copy modifications to a program header entry back to the underlying
  85 ELF descriptor.
  86 .Sh RETURN VALUES
  87 The functions a valid pointer if successful, or NULL in case an error
  88 was encountered.
  89 .Sh ERRORS
  90 These functions may fail with the following errors:
  91 .Bl -tag -width "[ELF_E_RESOURCE]"
  92 .It Bq Er ELF_E_ARGUMENT
  93 Argument
  94 .Ar elf
  95 was NULL.
  96 .It Bq Er ELF_E_ARGUMENT
  97 Argument
  98 .Ar elf
  99 was not a descriptor for an ELF object.
 100 .It Bq Er ELF_E_ARGUMENT
 101 Argument
 102 .Ar dst
 103 was NULL.
 104 .It Bq Er ELF_E_ARGUMENT
 105 Index
 106 .Ar index
 107 was out of range.
 108 .It Bq Er ELF_E_CLASS
 109 The class of ELF descriptor
 110 .Ar elf
 111 did not match the expected class of the function being called.
 112 .It Bq Er ELF_E_HEADER
 113 ELF descriptor
 114 .Ar elf
 115 did not possess an executable header.
 116 .It Bq Er ELF_E_HEADER
 117 ELF descriptor
 118 .Ar elf
 119 had a corrupt executable header.
 120 .It Bq Er ELF_E_RESOURCE
 121 An out of memory condition was detected.
 122 .It Bq Er ELF_E_SECTION
 123 The ELF descriptor in argument
 124 .Ar elf
 125 did not adhere to the conventions used for extended numbering.
 126 .It Bq Er ELF_VERSION
 127 ELF descriptor
 128 .Ar elf
 129 was of an unsupported version.
 130 .El
 131 .Sh SEE ALSO
 132 .Xr elf 3 ,
 133 .Xr elf32_getehdr 3 ,
 134 .Xr elf32_newphdr 3 ,
 135 .Xr elf64_getehdr 3 ,
 136 .Xr elf64_newphdr 3 ,
 137 .Xr elf_flagphdr 3 ,
 138 .Xr elf_getphnum 3 ,
 139 .Xr gelf 3 ,
 140 .Xr gelf_getehdr 3 ,
 141 .Xr gelf_newphdr 3 ,
 142 .Xr gelf_update_phdr 3 ,
 143 .Xr elf 5