lib/libelf/gelf_getehdr.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 December 16, 2006
  27 .Dt GELF_GETEHDR 3
  28 .Os
  29 .Sh NAME
  30 .Nm elf32_getehdr ,
  31 .Nm elf64_getehdr ,
  32 .Nm gelf_getehdr
  33 .Nd retrieve the object file header
  34 .Sh LIBRARY
  35 .Lb libelf
  36 .Sh SYNOPSIS
  37 .In libelf.h
  38 .Ft "Elf32_Ehdr *"
  39 .Fn elf32_getehdr "Elf *elf"
  40 .Ft "Elf64_Ehdr *"
  41 .Fn elf64_getehdr "Elf *elf"
  42 .In gelf.h
  43 .Ft "GElf_Ehdr *"
  44 .Fn gelf_getehdr "Elf *elf" "GElf_Ehdr *dst"
  45 .Sh DESCRIPTION
  46 These functions retrieve the ELF object file
  47 header from the ELF descriptor
  48 .Ar elf
  49 and return a translated header descriptor to their callers.
  50 .Pp
  51 Functions
  52 .Fn elf32_getehdr
  53 and
  54 .Fn elf64_getehdr
  55 return a pointer to the appropriate class-specific header descriptor
  56 if it exists in the file referenced by descriptor
  57 .Ar elf .
  58 These functions return
  59 .Dv NULL
  60 if an ELF header was not found in file
  61 .Ar elf .
  62 .Pp
  63 Function
  64 .Fn gelf_getehdr
  65 stores a translated copy of the header for ELF file
  66 .Ar elf
  67 into the descriptor pointed to by argument
  68 .Ar dst .
  69 It returns argument
  70 .Ar dst
  71 if successful or
  72 .Dv NULL
  73 in case of failure.
  74 .Sh RETURN VALUES
  75 These functions return a pointer to a translated header descriptor
  76 if successful, or NULL on failure.
  77 .Sh ERRORS
  78 These functions can fail with the following errors:
  79 .Bl -tag -width "[ELF_E_RESOURCE]"
  80 .It Bq Er ELF_E_ARGUMENT
  81 The argument
  82 .Ar elf
  83 was null.
  84 .It Bq Er ELF_E_ARGUMENT
  85 Argument
  86 .Ar elf
  87 was not a descriptor for an ELF file.
  88 .It Bq Er ELF_E_ARGUMENT
  89 The elf class of descriptor
  90 .Ar elf
  91 was not recognized.
  92 .It Bq Er ELF_E_ARGUMENT
  93 Argument
  94 .Ar dst
  95 was null.
  96 .It Bq Er ELF_E_CLASS
  97 The ELF class of descriptor
  98 .Ar elf
  99 did not match that of the API function being called.
 100 .It Bq Er ELF_E_HEADER
 101 ELF descriptor
 102 .Ar elf
 103 does not have an associated header.
 104 .It Bq Er ELF_E_RESOURCE
 105 An out of memory condition was detected during execution.
 106 .It Bq Er ELF_E_SECTION
 107 The ELF descriptor in argument
 108 .Ar elf
 109 did not adhere to the conventions used for extended numbering.
 110 .It Bq Er ELF_E_VERSION
 111 The ELF descriptor
 112 .Ar elf
 113 had an unsupported ELF version number.
 114 .El
 115 .Sh SEE ALSO
 116 .Xr elf 3 ,
 117 .Xr elf32_newehdr 3 ,
 118 .Xr elf64_newehdr 3 ,
 119 .Xr elf_flagehdr 3 ,
 120 .Xr elf_getident 3 ,
 121 .Xr gelf 3 ,
 122 .Xr gelf_newehdr 3 ,
 123 .Xr elf 5