Drop main() prototype. Syncs with NetBSD-8
[minix.git] / external / bsd / elftoolchain / dist / libelf / elf_getdata.3
blob73991cd29e75da780794463eb58538e55dfdec8f
1 .\"     $NetBSD: elf_getdata.3,v 1.2 2014/03/09 16:58:04 christos Exp $
2 .\"
3 .\" Copyright (c) 2006,2008,2010-2011 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: elf_getdata.3 1766 2011-08-22 06:01:03Z jkoshy 
27 .\"
28 .Dd January 26, 2011
29 .Os
30 .Dt ELF_GETDATA 3
31 .Sh NAME
32 .Nm elf_getdata ,
33 .Nm elf_newdata ,
34 .Nm elf_rawdata
35 .Nd iterate through or allocate section data
36 .Sh LIBRARY
37 .Lb libelf
38 .Sh SYNOPSIS
39 .In libelf.h
40 .Ft "Elf_Data *"
41 .Fn elf_getdata "Elf_Scn *scn" "Elf_Data *data"
42 .Ft "Elf_Data *"
43 .Fn elf_newdata "Elf_Scn *scn"
44 .Ft "Elf_Data *"
45 .Fn elf_rawdata "Elf_Scn *scn" "Elf_Data *data"
46 .Sh DESCRIPTION
47 These functions are used to access and manipulate data descriptors
48 associated with section descriptors.
49 Data descriptors used by the ELF library are described in
50 .Xr elf 3 .
51 .Pp
52 Function
53 .Fn elf_getdata
54 will return the next data descriptor associated with section descriptor
55 .Ar scn .
56 The returned data descriptor will be setup to contain translated data.
57 Argument
58 .Ar data
59 may be
60 .Dv NULL ,
61 in which case the function returns the first data descriptor
62 associated with section
63 .Ar scn .
64 If argument
65 .Ar data
66 is not
67 .Dv NULL ,
68 it must be a pointer to a data descriptor associated with
69 section descriptor
70 .Ar scn ,
71 and function
72 .Fn elf_getdata
73 will return a pointer to the next data descriptor for the section,
75 .Dv NULL
76 when the end of the section's descriptor list is reached.
77 .Pp
78 Function
79 .Fn elf_newdata
80 will allocate a new data descriptor and append it to the list of data
81 descriptors associated with section descriptor
82 .Ar scn .
83 The new data descriptor will be initialized as follows:
84 .Bl -tag -width "d_version" -compact -offset indent
85 .It Va d_align
86 Set to 1.
87 .It Va d_buf
88 Initialized to.
89 .Dv NULL .
90 .It Va d_off
91 Set to (off_t) -1.
92 This field is under application control if the
93 .Dv ELF_F_LAYOUT
94 flag was set on the ELF descriptor.
95 .It Va d_size
96 Set to zero.
97 .It Va d_type
98 Initialized to
99 .Dv ELF_T_BYTE .
100 .It Va d_version
101 Set to the current working version of the library, as set by
102 .Xr elf_version 3 .
104 The application must set these values as appropriate before
105 calling
106 .Xr elf_update 3 .
107 Section
108 .Ar scn
109 must be associated with an ELF file opened for writing.
110 If the application has not requested full control of layout by
111 setting the
112 .Dv ELF_F_LAYOUT
113 flag on descriptor
114 .Ar elf ,
115 then the data referenced by the returned descriptor will be positioned
116 after the existing content of the section, honoring the file alignment
117 specified in member
118 .Va d_align .
119 On successful completion of a call to
120 .Fn elf_newdata ,
121 the ELF library will mark the section
122 .Ar scn
124 .Dq dirty .
126 Function
127 .Fn elf_rawdata
128 is used to step through the data descriptors associated with
129 section
130 .Ar scn .
131 In contrast to function
132 .Fn elf_getdata ,
133 this function returns untranslated data.
134 If argument
135 .Ar data
137 .Dv NULL ,
138 the first data descriptor associated with section
139 .Ar scn
140 is returned.
141 If argument
142 .Ar data
143 is not
144 .Dv NULL ,
145 is must be a data descriptor associated with
146 section
147 .Ar scn ,
148 and function
149 .Fn elf_rawdata
150 will return the next data descriptor in the list, or
151 .Dv NULL
152 if no further descriptors are present.
153 Function
154 .Fn elf_rawdata
155 always returns
156 .Vt Elf_Data
157 structures of type
158 .Dv ELF_T_BYTE .
159 .Ss Special handling of zero-sized and SHT_NOBITS sections
160 For sections of type
161 .Dv SHT_NOBITS,
162 and for zero-sized sections,
163 the functions
164 .Fn elf_getdata
166 .Fn elf_rawdata
167 return a pointer to a valid
168 .Vt Elf_Data
169 structure that has its
170 .Va d_buf
171 member set to
172 .Dv NULL
173 and its
174 .Va d_size
175 member set to the size of the section.
177 If an application wishes to create a section of type
178 .Dv SHT_NOBITS ,
179 it should add a data buffer to the section using function
180 .Fn elf_newdata .
181 It should then set the
182 .Va d_buf
184 .Va d_size
185 members of the returned
186 .Vt Elf_Data
187 structure to
188 .Dv NULL
189 and the desired size of the section respectively.
190 .Sh RETURN VALUES
191 These functions return a valid pointer to a data descriptor if successful, or
192 .Dv NULL
193 if an error occurs.
194 .Sh ERRORS
195 These functions may fail with the following errors:
196 .Bl -tag -width "[ELF_E_RESOURCE]" 
197 .It Bq Er ELF_E_ARGUMENT
198 Either of the arguments
199 .Ar scn
201 .Ar data
203 .Dv NULL .
204 .It Bq Er ELF_E_ARGUMENT
205 The data descriptor referenced by argument
206 .Ar data
207 is not associated with section descriptor
208 .Ar scn .
209 .It Bq Er ELF_E_ARGUMENT
210 The section denoted by argument
211 .Ar scn
212 had no data associated with it.
213 .It Bq Er ELF_E_DATA
214 Retrieval of data from the underlying object failed.
215 .It Bq Er ELF_E_RESOURCE
216 An out of memory condition was detected.
217 .It Bq Er ELF_E_SECTION
218 Section
219 .Ar scn
220 had type
221 .Dv SHT_NULL .
222 .It Bq Er ELF_E_SECTION
223 The type of the section
224 .Ar scn
225 was not recognized by the library.
226 .It Bq Er ELF_E_SECTION
227 The size of the section
228 .Ar scn
229 is not a multiple of the file size for its section type.
230 .It Bq Er ELF_E_SECTION
231 The file offset for section
232 .Ar scn
233 is incorrect.
234 .It Bq Er ELF_E_UNIMPL
235 The section type associated with section
236 .Ar scn
237 is currently unsupported by the library.
239 .Sh SEE ALSO
240 .Xr elf 3 ,
241 .Xr elf_flagdata 3 ,
242 .Xr elf_flagscn 3 ,
243 .Xr elf_getscn 3 ,
244 .Xr elf_getshdr 3 ,
245 .Xr elf_newscn 3 ,
246 .Xr elf_rawfile 3 ,
247 .Xr elf_update 3 ,
248 .Xr elf_version 3 ,
249 .Xr gelf 3