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