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 3500 2016-12-04 11:08:44Z jkoshy $ 25.\" 26.Dd October 22, 2007 27.Os 28.Dt GELF_NEWPHDR 3 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 ELF(3) API, which use an 107.Ft "unsigned long" 108return type. 109.Sh ERRORS 110These functions may fail with the following errors: 111.Bl -tag -width "[ELF_E_RESOURCE]" 112.It Bq Er ELF_E_ARGUMENT 113Argument 114.Ar elf 115was NULL. 116.It Bq Er ELF_E_ARGUMENT 117Argument 118.Ar elf 119was not a descriptor for an ELF object. 120.It Bq Er ELF_E_CLASS 121ELF descriptor 122.Ar elf 123was of an unrecognized class. 124.It Bq Er ELF_E_RESOURCE 125An out of memory condition was detected. 126.It Bq Er ELF_E_SEQUENCE 127An executable header was not allocated for ELF descriptor 128.Ar elf 129before using these APIs. 130.El 131.Sh SEE ALSO 132.Xr elf 3 , 133.Xr elf32_getphdr 3 , 134.Xr elf32_newehdr 3 , 135.Xr elf64_getphdr 3 , 136.Xr elf64_newehdr 3 , 137.Xr elf_flagphdr 3 , 138.Xr elf_getphnum 3 , 139.Xr gelf 3 , 140.Xr gelf_getphdr 3 , 141.Xr gelf_newehdr 3 , 142.Xr elf 5 143