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_newehdr.3 3500 2016-12-04 11:08:44Z jkoshy $
25.\"
26.Dd October 22, 2007
27.Os
28.Dt GELF_NEWEHDR 3
29.Sh NAME
30.Nm elf32_newehdr ,
31.Nm elf64_newehdr ,
32.Nm gelf_newehdr
33.Nd retrieve or allocate the object file header
34.Sh LIBRARY
35.Lb libelf
36.Sh SYNOPSIS
37.In libelf.h
38.Ft "Elf32_Ehdr *"
39.Fn elf32_newehdr "Elf *elf"
40.Ft "Elf64_Ehdr *"
41.Fn elf64_newehdr "Elf *elf"
42.In gelf.h
43.Ft "void *"
44.Fn gelf_newehdr "Elf *elf" "int elfclass"
45.Sh DESCRIPTION
46These functions retrieve the ELF header from the ELF descriptor
47.Ar elf ,
48allocating a new header if needed.
49File data structures are translated to their in-memory representations
50as described in
51.Xr elf 3 .
52.Pp
53Function
54.Fn elf32_newehdr
55returns a pointer to a 32 bit
56.Vt Elf32_Ehdr
57structure.
58Function
59.Fn elf64_newehdr
60returns a pointer to a 64 bit
61.Vt Elf64_Ehdr structure.
62.Pp
63When argument
64.Ar elfclass
65has value
66.Dv ELFCLASS32 ,
67function
68.Fn gelf_newehdr
69returns the value returned by
70.Fn elf32_newehdr "elf" .
71When argument
72.Ar elfclass
73has value
74.Dv ELFCLASS64
75it returns the value returned by
76.Fn elf64_newehdr "elf" .
77.Pp
78If a fresh header structure is allocated, the members of the
79structure are initialized as follows:
80.Bl -tag -width indent
81.It Va "e_ident[EI_MAG0..EI_MAG3]"
82Identification bytes at offsets
83.Dv EI_MAG0 ,
84.Dv EI_MAG1 ,
85.Dv EI_MAG2
86and
87.Dv EI_MAG3
88are set to the ELF signature.
89.It Va "e_ident[EI_CLASS]"
90The identification byte at offset
91.Dv EI_CLASS
92is set to the ELF class associated with the function being called
93or to argument
94.Ar elfclass
95for function
96.Fn gelf_newehdr .
97.It Va "e_ident[EI_DATA]"
98The identification byte at offset
99.Dv EI_DATA
100is set to
101.Dv ELFDATANONE .
102.It Va "e_ident[EI_VERSION]"
103The identification byte at offset
104.Dv EI_VERSION
105is set to the ELF library's operating version set by a prior call to
106.Xr elf_version 3 .
107.It Va e_machine
108is set to
109.Dv EM_NONE .
110.It Va e_type
111is set to
112.Dv ELF_K_NONE .
113.It Va e_version
114is set to the ELF library's operating version set by a prior call to
115.Xr elf_version 3 .
116.El
117.Pp
118Other members of the header are set to zero.
119The application is responsible for changing these values
120as needed before calling
121.Fn elf_update .
122.Pp
123If successful, these three functions set the
124.Dv ELF_F_DIRTY
125flag on ELF descriptor
126.Ar elf .
127.Sh RETURN VALUES
128These functions return a pointer to a translated header descriptor
129if successful, or NULL on failure.
130.Sh COMPATIBILITY
131The
132.Fn gelf_newehdr
133function uses a type of
134.Ft "void *"
135for its returned value.
136This differs from some other implementations of the ELF(3) API, which use an
137.Ft "unsigned long"
138return type.
139.Sh ERRORS
140These functions can fail with the following errors:
141.Bl -tag -width "[ELF_E_RESOURCE]"
142.It Bq Er ELF_E_ARGUMENT
143The argument
144.Ar elf
145was null.
146.It Bq Er ELF_E_ARGUMENT
147Argument
148.Ar elf
149was not a descriptor for an ELF object.
150.It Bq Er ELF_E_ARGUMENT
151Argument
152.Ar elfclass
153had an unsupported value.
154.It Bq Er ELF_E_ARGUMENT
155The class of the ELF descriptor
156.Ar elf
157did not match that of the requested operation.
158.It Bq Er ELF_E_ARGUMENT
159For function
160.Fn gelf_newehdr ,
161the class of argument
162.Ar elf
163was not
164.Dv ELFCLASSNONE
165and did not match the argument
166.Ar elfclass .
167.It Bq Er ELF_E_CLASS
168The ELF class of descriptor
169.Ar elf
170did not match that of the API function being called.
171.It Bq Er ELF_E_HEADER
172A malformed ELF header was detected.
173.It Bq Er ELF_E_RESOURCE
174An out of memory condition was detected during execution.
175.It Bq Er ELF_E_SECTION
176The ELF descriptor in argument
177.Ar elf
178did not adhere to the conventions used for extended numbering.
179.It Bq Er ELF_E_VERSION
180The ELF descriptor
181.Ar elf
182had an unsupported ELF version number.
183.El
184.Sh SEE ALSO
185.Xr elf 3 ,
186.Xr elf32_getehdr 3 ,
187.Xr elf64_getehdr 3 ,
188.Xr elf_flagdata 3 ,
189.Xr elf_getident 3 ,
190.Xr elf_update 3 ,
191.Xr elf_version 3 ,
192.Xr gelf 3 ,
193.Xr gelf_getehdr 3 ,
194.Xr elf 5
195