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