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$
 25  .\"
 26  .Dd December 16, 2006
 27  .Os
 28  .Dt GELF_GETEHDR 3
 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