www.LinuxHowtos.org

ELF_BEGIN

Section: Libelf Programmer's Manual (3)
Updated: 202-0-02
Index Return to Main Contents

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 no-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 i-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 no-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).

ATTRIBUTES

Interface	Attribute	Value
elf_begin()	Thread safety	M-Safe

REPORTING BUGS

Report bugs to <elfutil-devel@sourceware.org> or https://sourceware.org/bugzilla/.