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: gelf_getphdr.3 3643 2018-10-14 21:09:24Z jkoshy $
25.\"
26.Dd October 21, 2007
27.Dt GELF_GETPHDR 3
28.Os
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
46These functions retrieve and translate ELF program header information
47from an ELF descriptor, if this information exists.
48.Pp
49Functions
50.Fn elf32_getphdr
51and
52.Fn elf64_getphdr
53return a pointer to an array of translated
54.Vt Elf32_Phdr
55and
56.Vt Elf64_Phdr
57descriptors respectively.
58These descriptors are described in
59.Xr elf 5 .
60The number of entries in this array may be determined using the
61.Xr elf_getphnum 3
62function.
63.Pp
64Function
65.Fn gelf_getphdr
66will retrieve the program header table entry at index
67.Ar index
68from ELF descriptor
69.Ar elf .
70The translated program header table entry will be written to the
71address pointed to be argument
72.Ar dst .
73.Pp
74Applications may inform the library of modifications to a program header table entry
75by using the
76.Xr elf_flagphdr 3
77API.
78Applications using the
79.Xr gelf 3
80interface need to use the
81.Xr gelf_update_phdr 3
82API to copy modifications to a program header entry back to the underlying
83ELF descriptor.
84.Sh RETURN VALUES
85The functions a valid pointer if successful, or NULL in case an error
86was encountered.
87.Sh ERRORS
88These functions may fail with the following errors:
89.Bl -tag -width "[ELF_E_RESOURCE]"
90.It Bq Er ELF_E_ARGUMENT
91Argument
92.Ar elf
93was NULL.
94.It Bq Er ELF_E_ARGUMENT
95Argument
96.Ar elf
97was not a descriptor for an ELF object.
98.It Bq Er ELF_E_ARGUMENT
99Argument
100.Ar dst
101was NULL.
102.It Bq Er ELF_E_ARGUMENT
103Index
104.Ar index
105was out of range.
106.It Bq Er ELF_E_CLASS
107The class of ELF descriptor
108.Ar elf
109did not match the expected class of the function being called.
110.It Bq Er ELF_E_HEADER
111ELF descriptor
112.Ar elf
113did not possess an executable header.
114.It Bq Er ELF_E_HEADER
115ELF descriptor
116.Ar elf
117had a corrupt executable header.
118.It Bq Er ELF_E_RESOURCE
119An out of memory condition was detected.
120.It Bq Er ELF_E_SECTION
121The ELF descriptor in argument
122.Ar elf
123did not adhere to the conventions used for extended numbering.
124.It Bq Er ELF_VERSION
125ELF descriptor
126.Ar elf
127was 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
142