Drop main() prototype. Syncs with NetBSD-8
[minix.git] / external / bsd / elftoolchain / dist / libelf / gelf_newphdr.3
blob044d8533561096d3982a71d342128143f4b6e287
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
48 These functions allocate an ELF Program Header table
49 for an ELF descriptor.
50 .Vt Elf32_Phdr
51 and
52 .Vt Elf64_Phdr
53 descriptors are described further in
54 .Xr elf 5 .
55 .Pp
56 Functions
57 .Fn elf32_newphdr
58 and
59 .Fn elf64_newphdr
60 allocate a table of
61 .Ar count
62 .Vt Elf32_Phdr
63 and
64 .Vt Elf64_Phdr
65 descriptors respectively,
66 discarding any existing program header table
67 already present in the ELF descriptor
68 .Ar elf .
69 A value of zero for argument
70 .Ar count
71 may be used to delete an existing program header table
72 from an ELF descriptor.
73 .Pp
74 Function
75 .Fn gelf_newphdr
76 will return a table of
77 .Vt Elf32_Phdr
79 .Vt Elf64_Phdr
80 with
81 .Ar count
82 elements depending on the ELF class of ELF descriptor
83 .Ar elf .
84 .Pp
85 The functions set the
86 .Dv ELF_F_DIRTY
87 flag on the program header table.
88 All members of the returned array of Phdr structures
89 will be initialized to zero.
90 .Pp
91 After a successful call to these functions, the pointer returned
92 by a prior call to
93 .Fn elf32_getphdr
95 .Fn elf64_getphdr
96 on the same descriptor
97 .Ar elf
98 will no longer be valid.
99 .Sh RETURN VALUES
100 The functions a valid pointer if successful, or NULL in case an error
101 was encountered.
102 .Sh ERRORS
103 These functions may fail with the following errors:
104 .Bl -tag -width "[ELF_E_RESOURCE]"
105 .It Bq Er ELF_E_ARGUMENT
106 Argument
107 .Ar elf
108 was NULL.
109 .It Bq Er ELF_E_ARGUMENT
110 Argument
111 .Ar elf
112 was not a descriptor for an ELF object.
113 .It Bq Er ELF_E_CLASS
114 ELF descriptor
115 .Ar elf
116 was of an unrecognized class.
117 .It Bq Er ELF_E_RESOURCE
118 An out of memory condition was detected.
119 .It Bq Er ELF_E_SEQUENCE
120 An executable header was not allocated for ELF descriptor
121 .Ar elf
122 before using these APIs.
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