---
name: "elf_begin"
section: "3"
platform: "linux"
package: "libelf"
version: "0.197-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux", "freebsd"]
url: "https://new.carta.tech/elf_begin"
---

# elf\_begin(3)

initialize an ELF descriptor

## 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_end/3.md)**.

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

## 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)](/mmap/2.md)** 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)](/elf_end/3.md)** 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)](/elf_next/3.md)** 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)](/elf_errmsg/3.md)**.

## SEE ALSO

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

## ATTRIBUTES

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

## REPORTING BUGS

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