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