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