Provided by: libelf-dev_0.194-1_amd64 
NAME
elf_begin - initialize an ELF descriptor
SYNOPSIS
#include <libelf.h>
Elf *elf_begin(int fildes, Elf_Cmd cmd, Elf *ref);
DESCRIPTION
Initialize and return a handle to an ELF file for use with the elfutils libelf library and related
elfutils libraries such as libdw.
The returned Elf descriptor must be released using elf_end(3).
elf_version(3) must be called before using any libelf library including elf_begin(3).
PARAMETERS
fildes 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 ref is non-NULL, then fildes must
either be -1 or be set to the same file descriptor as the one associated with ref.
cmd Specifies the action to perform. Common values include:
ELF_C_NULL
Return a NULL pointer instead of initializing an ELF descriptor. Ignores ref.
ELF_C_READ
Open an ELF descriptor for reading.
ELF_C_WRITE
Open an ELF descriptor for writing. The descriptor initially refers to an empty file.
ELF_C_RDWR
Open an ELF descriptor for reading and writing.
ELF_C_READ_MMAP
Open an ELF descriptor for reading using mmap, if available. The ELF_C_*_MMAP 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, ELF_C_*_MMAP
commands tend to be more useful for in-place modifications or removal of data from an ELF
descriptor.
ELF_C_WRITE_MMAP
Open an ELF descriptor for writing using mmap, if available. The descriptor initially
refers to an empty file.
ELF_C_RDWR_MMAP
Open an ELF descriptor for reading and writing using mmap, if available.
ELF_C_READ_MMAP_PRIVATE
Open an ELF descriptor for reading using mmap, if available. This command invokes mmap
with MAP_PRIVATE whereas the other ELF_C_*_MMAP commands invoke mmap with MAP_SHARED. See
mmap(2) for more information.
ref A reference to an existing Elf descriptor. If ref refers to regular ELF binary (not an AR file),
then elf_begin will duplicate ref. The reference count associated with ref will be incremented
and elf_end(3) will need to be called an additional time to deallocate ref. ref must have been
opened with read/write permissions consistent with cmd.
If ref refers to an AR file, then the ELF descriptor returned will be the first available object
member of the archive (see elf_next(3) for more information).
ref may be NULL, in which case this argument is ignored.
RETURN VALUE
On success, elf_begin() returns a pointer to a new Elf descriptor. If cmd is ELF_C_NULL then NULL is
returned. If ref is non-NULL and isn't an AR file, then a copy of ref is returned. On failure,
elf_begin() returns NULL and sets an internal error state that can be retrieved with elf_errmsg(3).
SEE ALSO
mmap(2), elf_clone(3), elf_end(3), elf_next(3), elf_rand(3), libelf(3), elf(5)
ATTRIBUTES
┌─────────────────────────────────────────────────────────────────────────────┬───────────────┬─────────┐
│ Interface │ Attribute │ Value │
├─────────────────────────────────────────────────────────────────────────────┼───────────────┼─────────┤
│ elf_begin() │ Thread safety │ MT-Safe │
└─────────────────────────────────────────────────────────────────────────────┴───────────────┴─────────┘
REPORTING BUGS
Report bugs to <elfutils-devel@sourceware.org> or https://sourceware.org/bugzilla/.
Libelf 2025-06-02 ELF_BEGIN(3)