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