1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
|
.TH ELF_BEGIN 3 2025-06-02 "Libelf" "Libelf Programmer's Manual"
.SH NAME
elf_begin \- initialize an ELF descriptor
.SH SYNOPSIS
.nf
#include <libelf.h>
Elf *elf_begin(int fildes, Elf_Cmd cmd, Elf *ref);
.fi
.SH DESCRIPTION
Initialize and return a handle to an ELF file for use with the elfutils
\fBlibelf\fP library and related elfutils libraries such as \fBlibdw\fP.
The returned \fBElf\fP descriptor must be released using \fBelf_end(3)\fP.
\fBelf_version(3)\fP must be called before using any \fBlibelf\fP library
including \fBelf_begin(3)\fP.
.SH PARAMETERS
.TP
\fIfildes\fP
A file descriptor referring to an ELF object. The descriptor should be open
for reading, and optionally for writing, depending on the intended operation.
If \fIref\fP is non-NULL, then \fIfildes\fP must either be -1 or be set to the
same file descriptor as the one associated with \fIref\fP.
.TP
\fIcmd\fP
Specifies the action to perform. Common values include:
.RS
.TP
\fBELF_C_NULL\fP
Return a NULL pointer instead of initializing an ELF descriptor. Ignores
\fIref\fP.
.TP
\fBELF_C_READ\fP
Open an ELF descriptor for reading.
.TP
\fBELF_C_WRITE\fP
Open an ELF descriptor for writing. The descriptor initially refers to an
empty file.
.TP
\fBELF_C_RDWR\fP
Open an ELF descriptor for reading and writing.
.TP
\fBELF_C_READ_MMAP\fP
Open an ELF descriptor for reading using mmap, if available. The
\fBELF_C_*_MMAP\fP commands are an elfutils libelf extension and may not be
available in other libelf implementations. Once the mmap size is set attempts
to extend the size may fail. Therefore, \fBELF_C_*_MMAP\fP commands tend to be
more useful for in-place modifications or removal of data from an ELF
descriptor.
.TP
\fBELF_C_WRITE_MMAP\fP
Open an ELF descriptor for writing using mmap, if available. The descriptor
initially refers to an empty file.
.TP
\fBELF_C_RDWR_MMAP\fP
Open an ELF descriptor for reading and writing using mmap, if available.
.TP
\fBELF_C_READ_MMAP_PRIVATE\fP
Open an ELF descriptor for reading using mmap, if available. This command
invokes mmap with MAP_PRIVATE whereas the other \fBELF_C_*_MMAP\fP commands
invoke mmap with MAP_SHARED. See \fBmmap(2)\fP for more information.
.RE
.TP
\fIref\fP
A reference to an existing Elf descriptor. If \fIref\fP refers to regular
ELF binary (not an AR file), then \fBelf_begin\fP will duplicate \fIref\fP.
The reference count associated with \fIref\fP will be incremented and
\fBelf_end(3)\fP will need to be called an additional time to deallocate
\fIref\fP. \fIref\fP must have been opened with read/write permissions
consistent with \fIcmd\fP.
If \fIref\fP refers to an AR file, then the ELF descriptor returned will be
the first available object member of the archive (see \fBelf_next(3)\fP for
more information).
\fIref\fP may be NULL, in which case this argument is ignored.
.SH RETURN VALUE
On success, \fBelf_begin()\fP returns a pointer to a new Elf descriptor.
If \fIcmd\fP is \fBELF_C_NULL\fP then NULL is returned. If \fIref\fP is
non-NULL and isn't an AR file, then a copy of \fIref\fP is returned. On
failure, \fBelf_begin()\fP returns NULL and sets an internal error
state that can be retrieved with \fBelf_errmsg(3)\fP.
.SH SEE ALSO
.BR mmap (2),
.BR elf_clone (3),
.BR elf_end (3),
.BR elf_next (3),
.BR elf_rand (3),
.BR libelf (3),
.BR elf (5)
.SH ATTRIBUTES
.TS
allbox;
lbx lb lb
l l l.
Interface Attribute Value
T{
.na
.nh
.BR elf_begin ()
T} Thread safety MT-Safe
.TE
.SH REPORTING BUGS
Report bugs to <elfutils-devel@sourceware.org> or https://sourceware.org/bugzilla/.
|
