| blob | db8d0147cfcf3a94ce9762b35d36f045ac5660d2 |
1 .\" $NetBSD: elf_flagdata.3,v 1.2 2014/03/09 16:58:04 christos Exp $
2 .\"
3 .\" Copyright (c) 2006-2008,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_flagdata.3 2884 2013-01-11 02:03:46Z jkoshy
27 .\"
28 .Dd December 3, 2011
29 .Os
30 .Dt ELF_FLAGDATA 3
31 .Sh NAME
32 .Nm elf_flagarhdr ,
33 .Nm elf_flagdata ,
34 .Nm elf_flagehdr ,
35 .Nm elf_flagelf ,
36 .Nm elf_flagphdr ,
37 .Nm elf_flagscn ,
38 .Nm elf_flagshdr
39 .Nd manipulate flags associated with ELF(3) data structures
40 .Sh LIBRARY
41 .Lb libelf
42 .Sh SYNOPSIS
43 .In libelf.h
44 .Ft "unsigned int"
45 .Fn elf_flagarhdr "Elf_Arhdr *arhdr" "Elf_Cmd cmd" "unsigned int flags"
46 .Ft "unsigned int"
47 .Fn elf_flagdata "Elf_Data *data" "Elf_Cmd cmd" "unsigned int flags"
48 .Ft "unsigned int"
49 .Fn elf_flagehdr "Elf *elf" "Elf_Cmd cmd" "unsigned int flags"
50 .Ft "unsigned int"
51 .Fn elf_flagelf "Elf *elf" "Elf_Cmd cmd" "unsigned int flags"
52 .Ft "unsigned int"
53 .Fn elf_flagphdr "Elf *elf" "Elf_Cmd cmd" "unsigned int flags"
54 .Ft "unsigned int"
55 .Fn elf_flagscn "Elf_Scn *scn" "Elf_Cmd cmd" "unsigned int flags"
56 .Ft "unsigned int"
57 .Fn elf_flagshdr "Elf_Scn *scn" "Elf_Cmd cmd" "unsigned int flags"
58 .Sh DESCRIPTION
59 These functions are used to query, set or reset flags on data
60 structures associated with an ELF file.
61 .Pp
62 Arguments
63 .Ar arhdr ,
64 .Ar data ,
65 .Ar elf
66 and
67 .Ar scn
68 denote the data structures whose flags need to be changed.
69 These values should have been returned by prior calls to
70 functions in the ELF(3) API set:
71 .Bl -bullet -compact
72 .It
73 Argument
74 .Ar arhdr
75 should have been returned by a prior call to
76 .Xr elf_getarhdr 3 .
77 .It
78 Argument
79 .Ar data
80 should have been returned by a prior call to one of
81 .Xr elf_newdata 3 ,
82 .Xr elf_getdata 3
83 or
84 .Xr elf_rawdata 3 .
85 .It
86 Argument
87 .Ar elf
88 should have been allocated by a prior call to one of
89 .Xr elf_begin 3
90 or
91 .Xr elf_memory 3 .
92 .It
93 Argument
94 .Ar scn
95 should have been returned by a prior call to one of
96 .Xr elf_getscn 3 ,
97 .Xr elf_newscn 3
98 or
99 .Xr elf_nextscn 3 .
100 .El
101 These values are allowed to be NULL to simplify error handling in
102 application code.
103 .Pp
104 Argument
105 .Ar cmd
106 may have the following values:
107 .Bl -tag -width ELF_C_SET
108 .It Dv ELF_C_CLR
109 The argument
110 .Ar flags
111 specifies the flags to be cleared.
112 .It Dv ELF_C_SET
113 The argument
114 .Ar flags
115 specifies the flags to be set.
116 .El
117 .Pp
118 The argument
119 .Ar flags
120 is allowed to have the following flags set:
121 .Bl -tag -width ELF_F_ARCHIVE_SYSV
122 .It Dv ELF_F_ARCHIVE
123 This flag is only valid with the
124 .Fn elf_flagelf
125 API.
126 It informs the library that the application desires to create an
127 .Xr ar 1
128 archive.
129 Argument
130 .Ar elf
131 should have been opened for writing using the
132 .Dv ELF_C_WRITE
133 command to function
134 .Fn elf_begin .
135 .It Dv ELF_F_ARCHIVE_SYSV
136 This flag is used in conjunction with the
137 .Dv ELF_F_ARCHIVE
138 flag to indicate that library should create archives that conform
139 to System V layout rules.
140 The default is to create BSD style archives.
141 .It Dv ELF_F_DIRTY
142 Mark the associated data structure as needing to be written back
143 to the underlying file.
144 A subsequent call to
145 .Xr elf_update 3
146 will resynchronize the library's internal data structures.
147 .It Dv ELF_F_LAYOUT
148 This flag is only valid with the
149 .Fn elf_flagelf
150 API.
151 It informs the library that the application will take
152 responsibility for the layout of the file and that the library is
153 not to insert any padding in between sections.
154 .El
155 .Pp
156 Marking a given data structure as
157 .Dq dirty
158 affects all of its contained elements.
159 Thus marking an ELF descriptor
160 .Ar elf
161 with
162 .Fn elf_flagelf "elf" "ELF_C_SET" "ELF_F_DIRTY"
163 means that the entire contents of the descriptor are
164 .Dq dirty .
165 .Pp
166 Using a value of zero for argument
167 .Ar flags
168 will return the current set of flags for the data structure being
169 queried.
170 .Sh RETURN VALUES
171 These functions return the updated flags if successful, or zero if
172 an error is detected.
173 .Sh COMPATIBILITY
174 The
175 .Fn elf_flagarhdr
176 function and the
177 .Dv ELF_F_ARCHIVE
178 and
179 .Dv ELF_F_ARCHIVE_SYSV
180 flags are an extension to the ELF(3) API.
181 .Sh ERRORS
182 These functions may fail with the following errors:
183 .Bl -tag -width "[ELF_E_RESOURCE]"
184 .It Bq Er ELF_E_ARGUMENT
185 An unsupported value was used for the
186 .Ar cmd
187 argument.
188 .It Bq Er ELF_E_ARGUMENT
189 Argument
190 .Ar flags
191 had unsupported flags set.
192 .It Bq Er ELF_E_ARGUMENT
193 The argument
194 .Ar elf
195 was not a descriptor for an ELF object.
196 .It Bq Er ELF_E_MODE
197 The
198 .Dv ELF_F_ARCHIVE
199 flag was used with an ELF descriptor that had not been opened for writing.
200 .It Bq Er ELF_E_SEQUENCE
201 Function
202 .Fn elf_flagehdr
203 was called without an executable header being allocated.
204 .It Bq Er ELF_E_SEQUENCE
205 Function
206 .Fn elf_flagphdr
207 was called without a program header being allocated.
208 .El
209 .Sh SEE ALSO
210 .Xr elf 3 ,
211 .Xr elf32_newehdr 3 ,
212 .Xr elf32_newphdr 3 ,
213 .Xr elf32_newshdr 3 ,
214 .Xr elf64_newehdr 3 ,
215 .Xr elf64_newphdr 3 ,
216 .Xr elf64_newshdr 3 ,
217 .Xr elf_newdata 3 ,
218 .Xr elf_update 3 ,
219 .Xr gelf 3 ,
220 .Xr gelf_newehdr 3 ,
221 .Xr gelf_newphdr 3 ,
222 .Xr gelf_newshdr 3 ,
223 .Xr gelf_update_dyn 3 ,
224 .Xr gelf_update_move 3 ,
225 .Xr gelf_update_rel 3 ,
226 .Xr gelf_update_rela 3 ,
227 .Xr gelf_update_sym 3 ,
228 .Xr gelf_update_syminfo 3