---
name: "elf_newscn"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["linux", "freebsd"]
url: "https://new.carta.tech/elf_getscn"
---

# elf\_newscn(3)

get/allocate section information for an ELF object

Part of [elf\_getscn(3)](/elf_getscn/3.md).

## NAME

**elf\_getscn**, **elf\_ndxscn**, **elf\_newscn**, **elf\_nextscn** – get/allocate section information for an ELF object

## LIBRARY

library “libelf”

## SYNOPSIS

**#include \<libelf.h\>**

*Elf\_Scn \**\

**elf\_getscn**(*Elf \*elf*, *size\_t index*);

*size\_t*\

**elf\_ndxscn**(*Elf\_Scn \*scn*);

*Elf\_Scn \**\

**elf\_newscn**(*Elf \*elf*);

*Elf\_Scn \**\

**elf\_nextscn**(*Elf \*elf*, *Elf\_Scn \*scn*);

## DESCRIPTION

These functions are used to iterate through the sections associated with an ELF descriptor.

Function **elf\_getscn**() will return a section descriptor for the section at index *index* in the object denoted by ELF descriptor *elf*. An error will be signalled if the specified section does not exist.

Function **elf\_ndxscn**() returns the section table index associated with section descriptor *scn*.

Function **elf\_newscn**() creates a new section and appends it to the list of sections associated with descriptor *elf*. The library will automatically increment the *e\_shnum* field of the ELF header associated with descriptor *elf*, and will set the ELF\_F\_DIRTY flag on the returned section descriptor. For ELF descriptors opened for writing, the ELF library will automatically create an empty section at index zero (SHN\_UNDEF) on the first call to **elf\_newscn**().

Function **elf\_nextscn**() takes a section descriptor *scn* and returns a pointer to the section descriptor at the next higher index. As a consequence, **elf\_nextscn**() will never return a pointer to the empty section at index zero (SHN\_UNDEF). Argument *scn* is allowed to be NULL, in which case this function will return a pointer to the section descriptor at index 1. If no further sections are present, function **elf\_nextscn**() will return a NULL pointer.

## RETURN VALUES

Functions **elf\_getscn**(), **elf\_newscn**() and **elf\_nextscn**() return a valid pointer to a section descriptor if successful, or NULL if an error occurs.

Function **elf\_ndxscn**() returns a valid section table index if successful, or SHN\_UNDEF if an error occurs.

## ERRORS

These functions may fail with the following errors:

- \[ELF\_E\_ARGUMENT\]

  Arguments *elf* or *scn* were NULL.

- \[ELF\_E\_ARGUMENT\]

  Argument *index* exceeded the current number of sections in the ELF object.

- \[ELF\_E\_ARGUMENT\]

  Argument *elf* was not a descriptor for an ELF file.

- \[ELF\_E\_ARGUMENT\]

  Section descriptor *scn* was not associated with ELF descriptor *elf*.

- \[ELF\_E\_CLASS\]

  Descriptor *elf* was of an unknown ELF class.

- \[ELF\_E\_SECTION\]

  Argument *elf* specified extended section numbering in the ELF header with the section header at index SHN\_UNDEF not being of type SHT\_NULL.

## SEE ALSO

[elf(3)](/elf/3.md), [elf\_flagdata(3)](/elf_flagdata/3.md), [elf\_flagscn(3)](/elf_flagscn/3.md), [elf\_getdata(3)](/elf_getdata/3.md), elf\_getshdr(3), [gelf(3)](/gelf/3.md)