ELF\_BEGIN(3) Libelf Programmer's Manual ELF\_BEGIN(3)

# [NAME](#NAME)

elf\_begin - initialize an ELF descriptor

# [SYNOPSIS](#SYNOPSIS)

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

# [DESCRIPTION](#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)**](/man/os/elfutils/elf_end.3).

[**elf\_version(3)**](/man/os/elfutils/elf_version.3) must be called before using any **libelf** library including [**elf\_begin(3)**](/man/os/elfutils/elf_begin.3).

# [PARAMETERS](#PARAMETERS)

[*fildes*](#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*](#cmd)

Specifies the action to perform. Common values include:

[**ELF\_C\_NULL**](#ELF_C_NULL)

Return a NULL pointer instead of initializing an ELF descriptor. Ignores *ref*.

[**ELF\_C\_READ**](#ELF_C_READ)

Open an ELF descriptor for reading.

[**ELF\_C\_WRITE**](#ELF_C_WRITE)

Open an ELF descriptor for writing. The descriptor initially refers to an empty file.

[**ELF\_C\_RDWR**](#ELF_C_RDWR)

Open an ELF descriptor for reading and writing.

[**ELF\_C\_READ\_MMAP**](#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**](#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**](#ELF_C_RDWR_MMAP)

Open an ELF descriptor for reading and writing using mmap, if available.

[**ELF\_C\_READ\_MMAP\_PRIVATE**](#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)**](/man/os/elfutils/mmap.2) for more information.

[*ref*](#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)**](/man/os/elfutils/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)**](/man/os/elfutils/elf_next.3) for more information).

*ref* may be NULL, in which case this argument is ignored.

# [RETURN VALUE](#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)**](/man/os/elfutils/elf_errmsg.3).

# [SEE ALSO](#SEE_ALSO)

[**mmap**(2)](/man/os/elfutils/mmap.2), [**elf\_clone**(3)](/man/os/elfutils/elf_clone.3), [**elf\_end**(3)](/man/os/elfutils/elf_end.3), [**elf\_next**(3)](/man/os/elfutils/elf_next.3), [**elf\_rand**(3)](/man/os/elfutils/elf_rand.3), [**libelf**(3)](/man/os/elfutils/libelf.3), [**elf**(5)](/man/os/elfutils/elf.5)

# [ATTRIBUTES](#ATTRIBUTES)

**Interface** **Attribute** **Value** elf\_begin () Thread safety MT-Safe

# [REPORTING BUGS](#REPORTING_BUGS)

Report bugs to &lt;elfutils-devel@sourceware.org&gt; or https://sourceware.org/bugzilla/.

2025-06-02 Libelf

---

Document: elf_begin(3) from elfutils 0.196-r1 (Chainguard OS)
Source: https://sourceware.org/git/elfutils.git