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