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