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