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_newphdr.3 3743 2019-06-12 19:36:30Z jkoshy $ 25.\" 26.Dd June 12, 2019 27.Dt GELF_NEWPHDR 3 28.Os 29.Sh NAME 30.Nm elf32_newphdr , 31.Nm elf64_newphdr , 32.Nm gelf_newphdr 33.Nd allocate an ELF program header table 34.Sh LIBRARY 35.Lb libelf 36.Sh SYNOPSIS 37.In libelf.h 38.Ft "Elf32_Phdr *" 39.Fn elf32_newphdr "Elf *elf" "size_t count" 40.Ft "Elf64_Phdr *" 41.Fn elf64_newphdr "Elf *elf" "size_t count" 42.In gelf.h 43.Ft "void *" 44.Fn gelf_newphdr "Elf *elf" "size_t count" 45.Sh DESCRIPTION 46These functions allocate an ELF Program Header table 47for an ELF descriptor. 48.Vt Elf32_Phdr 49and 50.Vt Elf64_Phdr 51descriptors are described further in 52.Xr elf 5 . 53.Pp 54Functions 55.Fn elf32_newphdr 56and 57.Fn elf64_newphdr 58allocate a table of 59.Ar count 60.Vt Elf32_Phdr 61and 62.Vt Elf64_Phdr 63descriptors respectively, 64discarding any existing program header table 65already present in the ELF descriptor 66.Ar elf . 67A value of zero for argument 68.Ar count 69may be used to delete an existing program header table 70from an ELF descriptor. 71.Pp 72Function 73.Fn gelf_newphdr 74will return a table of 75.Vt Elf32_Phdr 76or 77.Vt Elf64_Phdr 78with 79.Ar count 80elements depending on the ELF class of ELF descriptor 81.Ar elf . 82.Pp 83The functions set the 84.Dv ELF_F_DIRTY 85flag on the program header table. 86All members of the returned array of Phdr structures 87will be initialized to zero. 88.Pp 89After a successful call to these functions, the pointer returned 90by a prior call to 91.Fn elf32_getphdr 92or 93.Fn elf64_getphdr 94on the same descriptor 95.Ar elf 96will no longer be valid. 97.Sh RETURN VALUES 98The functions a valid pointer if successful, or NULL in case an error 99was encountered. 100.Sh COMPATIBILITY 101The 102.Fn gelf_newphdr 103function uses a type of 104.Ft "void *" 105for its returned value. 106This differs from some other implementations of the 107.Xr elf 3 108API, which use an 109.Ft "unsigned long" 110return type. 111.Sh ERRORS 112These functions may fail with the following errors: 113.Bl -tag -width "[ELF_E_RESOURCE]" 114.It Bq Er ELF_E_ARGUMENT 115Argument 116.Ar elf 117was NULL. 118.It Bq Er ELF_E_ARGUMENT 119Argument 120.Ar elf 121was not a descriptor for an ELF object. 122.It Bq Er ELF_E_CLASS 123ELF descriptor 124.Ar elf 125was of an unrecognized class. 126.It Bq Er ELF_E_RESOURCE 127An out of memory condition was detected. 128.It Bq Er ELF_E_SEQUENCE 129An executable header was not allocated for ELF descriptor 130.Ar elf 131before using these APIs. 132.El 133.Sh SEE ALSO 134.Xr elf 3 , 135.Xr elf32_getphdr 3 , 136.Xr elf32_newehdr 3 , 137.Xr elf64_getphdr 3 , 138.Xr elf64_newehdr 3 , 139.Xr elf_flagphdr 3 , 140.Xr elf_getphnum 3 , 141.Xr gelf 3 , 142.Xr gelf_getphdr 3 , 143.Xr gelf_newehdr 3 , 144.Xr elf 5 145