elf_begin3

Usage

#include <libelf.h>
Elf *elf_begin(int fildes, Elf_Cmd cmd, Elf *ref);

Overview

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

Attributes