[PATCH 02/16] doc: Add elf_flag*.3
Signed-off-by: Aaron Merey
---
doc/Makefile.am| 6 ++
doc/elf_flagdata.3 | 1 +
doc/elf_flagehdr.3 | 1 +
doc/elf_flagelf.3 | 145 +
doc/elf_flagphdr.3 | 1 +
doc/elf_flagscn.3 | 1 +
doc/elf_flagshdr.3 | 1 +
7 files changed, 156 insertions(+)
create mode 100644 doc/elf_flagdata.3
create mode 100644 doc/elf_flagehdr.3
create mode 100644 doc/elf_flagelf.3
create mode 100644 doc/elf_flagphdr.3
create mode 100644 doc/elf_flagscn.3
create mode 100644 doc/elf_flagshdr.3
diff --git a/doc/Makefile.am b/doc/Makefile.am
index e5b12133..3b63dc38 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -58,6 +58,12 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
elf_errmsg.3 \
elf_errno.3 \
elf_fill.3 \
+ elf_flagelf.3 \
+ elf_flagehdr.3 \
+ elf_flagphdr.3 \
+ elf_flagscn.3 \
+ elf_flagdata.3 \
+ elf_flagshdr.3 \
elf_getbase.3 \
elf_getdata.3 \
elf_getscn.3 \
diff --git a/doc/elf_flagdata.3 b/doc/elf_flagdata.3
new file mode 100644
index ..ee84d431
--- /dev/null
+++ b/doc/elf_flagdata.3
@@ -0,0 +1 @@
+.so man3/elf_flagelf.3
diff --git a/doc/elf_flagehdr.3 b/doc/elf_flagehdr.3
new file mode 100644
index ..ee84d431
--- /dev/null
+++ b/doc/elf_flagehdr.3
@@ -0,0 +1 @@
+.so man3/elf_flagelf.3
diff --git a/doc/elf_flagelf.3 b/doc/elf_flagelf.3
new file mode 100644
index ..1118deaa
--- /dev/null
+++ b/doc/elf_flagelf.3
@@ -0,0 +1,145 @@
+.TH ELF_FLAGELF 3 2025-06-23 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf_flagelf, elf_flagdata, elf_flagehdr, elf_flagphdr, elf_flagscn,
elf_flagshdr \- set or clear flags on ELF descriptors and components
+.SH SYNOPSIS
+.nf
+#include
+
+.B unsigned int elf_flagelf(Elf *" elf ", Elf_Cmd" cmd ", unsigned int" flags
");
+.B unsigned int elf_flagehdr(Elf *" elf ", "Elf_Cmd" cmd ", unsigned int"
flags ");
+.B unsigned int elf_flagphdr(Elf *" elf ", Elf_Cmd" cmd ", unsigned int" flags
");
+.B unsigned int elf_flagscn(Elf_Scn *" scn ", Elf_Cmd" cmd ", unsigned int"
flags ");
+.B unsigned int elf_flagshdr("Elf_Scn *" scn ", "Elf_Cmd" cmd ", unsigned int"
flags ");
+.B unsigned int elf_flagdata(Elf_Data *" data ", Elf_Cmd" cmd ", unsigned int"
flags ");
+.fi
+.SH DESCRIPTION
+These functions allow the caller to set or clear flags on various ELF
+components managed by
+.B libelf .
+They are typically used to indicate that a component has been modified
+(dirty), or to control layout behavior during output.
+
+.BR elf_flagelf ()
+modifies flags on the top-level
+.B Elf
+descriptor.
+
+.BR elf_flagdata ()
+modifies flags on an
+.B Elf_Data
+descriptor, typically retrieved using
+.BR elf_getdata (3)
+or created with
+.BR elf_newdata (3).
+
+.BR elf_flagehdr ()
+modifies flags on the ELF header for a ELF descriptor (e.g., the result of
+.BR gelf_getehdr (3)).
+
+.BR elf_flagphdr ()
+modifies flags on the program header table of an ELF descriptor.
+
+.BR elf_flagscn ()
+modifies flags on an
+.B Elf_Scn
+(section) descriptor.
+
+.BR elf_flagshdr ()
+modifies flags on the section header of a given
+.B Elf_Scn .
+
+The
+.I cmd
+argument determines whether the given flags should be set (
+.B ELF_C_SET
+) or cleared (
+.B ELF_C_CLR
+).
+
+The following flag values may be passed via the
+.I flags
+parameter:
+
+.TP
+.B ELF_F_DIRTY
+Marks the object as modified. This ensures changes to the component is written
+out during
+.BR elf_update (3).
+
+.TP
+.B ELF_F_LAYOUT
+Indicates that the layout of the ELF component is managed manually. Offsets and
+sizes will be preserved as provided.
+
+.TP
+.B ELF_F_PERMISSIVE
+Enables relaxed validation of object structure. This flag permits nonstandard
layouts
+without strict checks.
+
+.SH PARAMETERS
+.TP
+.I obj
+The object to be modified:
+For
+.BR elf_flagelf ,
+.BR elf_flagehdr ,
+.BR elf_flagphdr ,
+this is an
+.B Elf *
+descriptor.
+For
+.B elf_flagscn
+and
+.B elf_flagshdr ,
+this is an
+.B Elf_Scn *
+descriptor.
+For
+.B elf_flagdata ,
+an
+.B Elf_Data *
+buffer.
+
+.TP
+.I cmd
+Must be either:
+.B ELF_C_SET
+to set the given flags, or
+.B ELF_C_CLR
+to clear them.
+
+.TP
+.I flags
+Bitmask of flags to modify. May include any combination of
+.B ELF_F_DIRTY ,
+.B ELF_F_LAYOUT ,
+and
+.B ELF_F_PERMISSIVE .
+
+.SH RETURN VALUE
+Returns the new value of the flags after the set/clear operation.
+
+Returns 0 on error, and sets an error code retrievable via
+.BR elf_errmsg (3).
+
+.SH SEE ALSO
+.BR elf_errmsg (3),
+.BR libelf (3),
+.BR elf (5)
+
+.SH ATTRIBUTES
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR elf_flagelf
(),\~elf_flagehdr(),\~elf_flagphdr(),\~elf_flagscn(),\~elf_flagshdr(),\~elf_flagdata()
+T} Thread safety MT-Unsafe race
+.TE
+
+
[PATCH 10/16] doc: Add elf_newscn.3
Signed-off-by: Aaron Merey
---
doc/Makefile.am | 1 +
doc/elf_newscn.3 | 70
2 files changed, 71 insertions(+)
create mode 100644 doc/elf_newscn.3
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 97aac570..022906bb 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -80,6 +80,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
elf_memory.3 \
elf_ndxscn.3 \
elf_newdata.3 \
+ elf_newscn.3 \
elf_update.3 \
elf_version.3 \
libelf.3
diff --git a/doc/elf_newscn.3 b/doc/elf_newscn.3
new file mode 100644
index ..c53cd4ef
--- /dev/null
+++ b/doc/elf_newscn.3
@@ -0,0 +1,70 @@
+.TH ELF_NEWSCN 3 2025-06-30 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf_newscn \- create a new section for an ELF descriptor
+
+.SH SYNOPSIS
+.nf
+#include
+
+.BI "void elf_fill(int " fill ");"
+
+.SH DESCRIPTION
+The
+.BR elf_newscn ()
+function creates a new section descriptor for the ELF descriptor
+.I elf.
+
+Each call to
+.BR elf_newscn ()
+appends a new section to the internal list of sections for the
+ELF descriptor. It also creates a corresponding empty section header,
+which is zero-initialized and marked dirty.
+
+A newly created section has no name or type and must be properly initialized
+before calling
+.BR elf_update ().
+Use
+.BR elf_getshdr ()
+to obtain the section header structure, then populate the required fields.
+Use
+.BR elf_newdata ()
+to associate one or more data buffers with the new section.
+
+The section with index 0 (the null section) is reserved and cannot have
+data added to it.
+
+.SH PARAMETERS
+.TP
+.I elf
+An ELF descriptor in ELF_C_WRITE or ELF_C_RDWR mode.
+
+.SH RETURN VALUE
+On success,
+.BR elf_newscn ()
+returns a pointer to a new section descriptor. On failure, it returns NULL.
+
+
+.SH SEE ALSO
+.BR elf_getshdr (3),
+.BR elf_getdata (3),
+.BR elf_newdata (3),
+.BR elf_update (3),
+.BR libelf (3),
+.BR elf (5)
+
+.SH ATTRIBUTES
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR elf_newscn ()
+T} Thread safety MT-Safe
+.TE
+
+.SH REPORTING BUGS
+Report bugs to or
https://sourceware.org/bugzilla/.
--
2.49.0
[PATCH 07/16] doc: Add elf_getshdrstrndx.3 and elf_getshstrndx.3
Signed-off-by: Aaron Merey
---
doc/Makefile.am | 2 ++
doc/elf_getshdrstrndx.3 | 80 +
doc/elf_getshstrndx.3 | 1 +
3 files changed, 83 insertions(+)
create mode 100644 doc/elf_getshdrstrndx.3
create mode 100644 doc/elf_getshstrndx.3
diff --git a/doc/Makefile.am b/doc/Makefile.am
index cf60a271..129c612d 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -71,7 +71,9 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
elf_getphdrnum.3 \
elf_getscn.3 \
elf_getshdrnum.3 \
+ elf_getshdrstrndx.3 \
elf_getshnum.3 \
+ elf_getshstrndx.3 \
elf_hash.3 \
elf_kind.3 \
elf_memory.3 \
diff --git a/doc/elf_getshdrstrndx.3 b/doc/elf_getshdrstrndx.3
new file mode 100644
index ..b3bdca0f
--- /dev/null
+++ b/doc/elf_getshdrstrndx.3
@@ -0,0 +1,80 @@
+.TH ELF_GETSHDRSTRNDX 3 2025-06-30 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf_getshdrstrndx, elf_getshstrndx \- retrieve the section header string table
index
+.SH SYNOPSIS
+.nf
+#include
+
+.B int elf_getshdrstrndx("Elf *elf", "size_t *dst");
+.B int elf_getshstrndx("Elf *elf", "size_t *dst");
+.fi
+.SH DESCRIPTION
+The
+.BR elf_getshdrstrndx ()
+function retrieves the section header string table index from the ELF
descriptor
+.IR elf ,
+and stores it in the location pointed to by
+.IR dst .
+
+This function handles both standard ELF values and extended section indexing.
+In the latter case, if the section header string table index field of the ELF
+header contains
+.B SHN_XINDEX,
+then the true index is stored in the
+.B sh_link
+field of section 0, which this function reads either from memory or directly
+from the file.
+
+The function
+.BR elf_getshstrndx ()
+is a deprecated alias for
+.BR elf_getshdrstrndx ()
+and should not be used in new code.
+
+.SH PARAMETERS
+.TP
+.I elf
+A pointer to an
+.B Elf
+descriptor opened with
+.BR elf_begin (3).
+The descriptor must be of kind
+.B ELF_K_ELF .
+
+.TP
+.I dst
+A pointer to a
+.B size_t
+location where the index of the section header string table will be stored.
+Must not be NULL.
+
+.SH RETURN VALUE
+Returns 0 on success and stores the section header string table index in
+.IR dst .
+Returns \-1 on failure.
+
+.SH SEE ALSO
+.BR libelf (3),
+.BR elf (5)
+
+.SH ATTRIBUTES
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR elf_getshdrstrndx (),\~elf_getshstrndx ()
+T} Thread safety MT-Safe
+.TE
+
+.SH REPORTING BUGS
+Report bugs to or
https://sourceware.org/bugzilla/.
+
+.SH HISTORY
+.B elf_getshdrstrndx
+first appeared in elfutils 0.142. This function is a elfutils libelf
extension and
+may not be available in other libelf implementations.
diff --git a/doc/elf_getshstrndx.3 b/doc/elf_getshstrndx.3
new file mode 100644
index ..22a2251f
--- /dev/null
+++ b/doc/elf_getshstrndx.3
@@ -0,0 +1 @@
+.so man3/elf_getshdrstrndx.3
--
2.49.0
[PATCH 01/16] doc: Add elf_memory.3
Signed-off-by: Aaron Merey
---
doc/Makefile.am | 1 +
doc/elf_memory.3 | 84
2 files changed, 85 insertions(+)
create mode 100644 doc/elf_memory.3
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 3ed04cd7..e5b12133 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -63,6 +63,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
elf_getscn.3 \
elf_hash.3 \
elf_kind.3 \
+ elf_memory.3 \
elf_ndxscn.3 \
elf_update.3 \
elf_version.3 \
diff --git a/doc/elf_memory.3 b/doc/elf_memory.3
new file mode 100644
index ..88d259ca
--- /dev/null
+++ b/doc/elf_memory.3
@@ -0,0 +1,84 @@
+.TH ELF_MEMORY 3 2025-06-23 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf_memory \- create an ELF descriptor from a memory buffer
+.SH SYNOPSIS
+.nf
+#include
+
+.B Elf * elf_memory(char *" image ", size_t" size ");
+
+.fi
+.SH DESCRIPTION
+The
+.BR elf_memory ()
+function creates a new ELF descriptor from a memory region containing an ELF
+object. This function is used when the ELF data is already present in memory
+rather than being read from a file descriptor.
+
+The memory pointed to by
+.I image
+must contain a complete ELF file or archive. The contents must remain valid
+and unmodified for the lifetime of the resulting ELF descriptor.
+
+The ELF descriptor returned by
+.BR elf_memory ()
+is opened in read-only mode using ELF_C_READ_MMAP_PRIVATE (see
+.BR elf_begin ).
+Writing, updating, or modifying this ELF descriptor is not permitted.
+
+.PP
+Internally,
+.BR elf_memory ()
+is equivalent to calling
+.BR elf_begin ()
+to create a descriptor from an open memory buffer with command
+.B ELF_C_READ_MMAP_PRIVATE
+and a NULL parent.
+
+.SH PARAMETERS
+.TP
+.I image
+A pointer to a memory buffer that contains the complete contents of an ELF file
+or archive. Should not be NULL.
+
+.TP
+.I size
+The size in bytes of the memory region pointed to by
+.IR image .
+Must be greater than zero and cover the entire ELF object.
+
+.SH RETURN VALUE
+On success,
+.BR elf_memory ()
+returns a pointer to an
+.B Elf
+descriptor representing the archive or ELF file contained in
+.IR image .
+
+On failure, it returns NULL and sets an error code retrievable by
+.BR elf_errmsg (3).
+
+
+.SH SEE ALSO
+.BR elf_begin (3),
+.BR elf_errmsg (3),
+.BR libelf (3),
+.BR elf (5)
+
+.SH ATTRIBUTES
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR elf_memory ()
+T} Thread safety MT-Safe
+.TE
+
+.SH REPORTING BUGS
+Report bugs to or
https://sourceware.org/bugzilla/.
+
--
2.49.0
[PATCH 12/16] doc: Add elf_rand.3
Signed-off-by: Aaron Merey
---
doc/Makefile.am | 1 +
doc/elf_rand.3 | 68 +
2 files changed, 69 insertions(+)
create mode 100644 doc/elf_rand.3
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 9ef2b60d..374e5d49 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -82,6 +82,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
elf_newdata.3 \
elf_newscn.3 \
elf_nextscn.3 \
+ elf_rand.3 \
elf_update.3 \
elf_version.3 \
libelf.3
diff --git a/doc/elf_rand.3 b/doc/elf_rand.3
new file mode 100644
index ..59449733
--- /dev/null
+++ b/doc/elf_rand.3
@@ -0,0 +1,68 @@
+.TH ELF_RAND 3 2025-06-30 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf_rand - Set the current offset for archive member retrieval.
+
+.SH SYNOPSIS
+.nf
+#include
+
+.BI "size_t elf_rand(Elf *" elf ", size_t " offset ");"
+.fi
+
+.SH DESCRIPTION
+The
+.BR elf_rand ()
+function sets the current archive member offset for the ELF archive descriptor
+.I elf
+to
+.IR offset .
+This affects subsequent calls to
+.BR elf_next (3),
+causing iteration to resume from the member at the specified offset.
+
+This function is only valid when
+.I elf
+refers to an archive descriptor (i.e., its kind is
+.BR ELF_K_AR ).
+
+If the archive header at the given offset cannot be parsed or validated,
+the current member is marked unusable.
+
+.SH PARAMETERS
+.TP
+.I elf
+A pointer to an ELF archive descriptor.
+
+.TP
+.I offset
+A byte offset relative to the beginning of the archive, indicating the desired
member position.
+
+.SH RETURN VALUE
+Returns the input
+.I offset
+if successful. Returns 0 if
+.I elf
+is NULL, is not an archive descriptor, or if an error occurs while reading the
member at
+.IR offset .
+
+.SH SEE ALSO
+.BR elf_next (3),
+.BR libelf (3),
+.BR elf (5)
+
+.SH ATTRIBUTES
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR elf_rand ()
+T} Thread safety MT-Safe
+.TE
+
+.SH REPORTING BUGS
+Report bugs to or
https://sourceware.org/bugzilla/.
--
2.49.0
[PATCH 03/16] doc: Add elf_getdata_rawchunk.3
Signed-off-by: Aaron Merey
---
doc/Makefile.am| 1 +
doc/elf_getdata_rawchunk.3 | 133 +
2 files changed, 134 insertions(+)
create mode 100644 doc/elf_getdata_rawchunk.3
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 3b63dc38..8afda0bd 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -66,6 +66,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
elf_flagshdr.3 \
elf_getbase.3 \
elf_getdata.3 \
+ elf_getdata_rawchunk.3 \
elf_getscn.3 \
elf_hash.3 \
elf_kind.3 \
diff --git a/doc/elf_getdata_rawchunk.3 b/doc/elf_getdata_rawchunk.3
new file mode 100644
index ..3b7f644f
--- /dev/null
+++ b/doc/elf_getdata_rawchunk.3
@@ -0,0 +1,133 @@
+.TH ELF_GETDATA_RAWCHUNK 3 2025-06-30 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf_getdata_rawchunk \- create a raw data descriptor from a file offset
+
+.SH SYNOPSIS
+.nf
+#include
+
+.B Elf_Data * elf_getdata_rawchunk("Elf *elf", "int64_t offset", "size_t
size", "Elf_Type type");
+.fi
+
+.SH DESCRIPTION
+The
+.BR elf_getdata_rawchunk ()
+function returns an
+.B Elf_Data
+descriptor that refers to a raw region of the ELF file, starting at the
+given file
+.I offset
+and spanning
+.I size
+bytes. This is used to access arbitrary byte ranges in the ELF file that may
+not correspond to any section or segment.
+
+If a descriptor for the same offset, size, and type has previously been
requested,
+the cached result is returned. Otherwise, the data is loaded and prepared
according
+to the conditions below.
+
+If the ELF descriptor is backed by a memory-mapped file and the file offset
yields
+a pointer suitably aligned for the given
+.I type ,
+the buffer is returned as a direct pointer into the mapped file. If alignment
+constraints are not met, or if the file is not memory-mapped, a copy of the
data is
+allocated and returned instead. The returned buffer is always read-only and
must not
+be modified.
+
+If the file’s byte order matches the host, and alignment permits, the raw data
is
+returned as-is. If the file’s byte order differs, the buffer is converted into
native
+byte order.
+
+The returned data is not associated with any section or update mechanism. It
will not
+be included in any output written by
+.BR elf_update (3).
+
+.SH PARAMETERS
+.TP
+.I elf
+A pointer to an
+.B Elf
+descriptor representing the ELF file.
+
+.TP
+.I offset
+The starting file offset in bytes. This must lie within the bounds of the file.
+
+.TP
+.I size
+The number of bytes to include in the data chunk, starting at
+.IR offset .
+
+.TP
+.I type
+An
+.B Elf_Type
+enumeration value indicating the intended interpretation of the data. Values
include:
+
+.RS
+.TP
+.B ELF_T_BYTE
+Raw bytes.
+.TP
+.B ELF_T_ADDR, ELF_T_OFF, ELF_T_HALF, ELF_T_WORD, ELF_T_XWORD, ELF_T_SWORD,
ELF_T_SXWORD
+Integer and pointer types.
+.TP
+.B ELF_T_EHDR, ELF_T_SHDR, ELF_T_PHDR
+ELF file, section, and program headers.
+.TP
+.B ELF_T_SYM, ELF_T_DYN, ELF_T_REL, ELF_T_RELA, ELF_T_RELR
+Symbols and relocations.
+.TP
+.B ELF_T_NHDR, ELF_T_CHDR, ELF_T_NHDR8
+ELF note headers and compressed data headers.
+.TP
+.B ELF_T_VDEF, ELF_T_VDAUX, ELF_T_VNEED, ELF_T_VNAUX
+Versioning structures.
+.TP
+.B ELF_T_SYMINFO, ELF_T_MOVE, ELF_T_LIB
+Other ELF metadata.
+.TP
+.B ELF_T_GNUHASH
+GNU-style hash table.
+.TP
+.B ELF_T_AUXV
+Auxiliary vectors.
+.RE
+
+.SH RETURN VALUE
+Returns a pointer to an
+.B Elf_Data
+descriptor on success.
+
+Returns NULL if any arguments are invalid, or if memory allocation or file
reading
+fails. The result is cached and shared between repeated calls using the same
arguments.
+
+.SH SEE ALSO
+.BR elf (3),
+.BR elf_getdata (3),
+.BR elf_getscn (3),
+.BR elf_rawdata (3),
+.BR libelf (3),
+.BR elf (5)
+
+.SH ATTRIBUTES
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR elf_getdata_rawchunk ()
+T} Thread safety MT-Safe
+.TE
+
+.SH REPORTING BUGS
+Report bugs to or
https://sourceware.org/bugzilla/.
+
+.SH HISTORY
+.B elf_getdata_rawchunk
+first appeared in elfutils 0.130. This function is a elfutils libelf
extension and
+may not be available in other libelf implementations.
--
2.49.0
[PATCH 08/16] doc: Add elf_gnu_hash.3
Signed-off-by: Aaron Merey
---
doc/Makefile.am| 1 +
doc/elf_gnu_hash.3 | 1 +
doc/elf_hash.3 | 20 +---
3 files changed, 19 insertions(+), 3 deletions(-)
create mode 100644 doc/elf_gnu_hash.3
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 129c612d..98712576 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -75,6 +75,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
elf_getshnum.3 \
elf_getshstrndx.3 \
elf_hash.3 \
+ elf_gnu_hash.3 \
elf_kind.3 \
elf_memory.3 \
elf_ndxscn.3 \
diff --git a/doc/elf_gnu_hash.3 b/doc/elf_gnu_hash.3
new file mode 100644
index ..d87463f1
--- /dev/null
+++ b/doc/elf_gnu_hash.3
@@ -0,0 +1 @@
+.so man3/elf_hash.3
diff --git a/doc/elf_hash.3 b/doc/elf_hash.3
index 1e06d888..2313f3b5 100644
--- a/doc/elf_hash.3
+++ b/doc/elf_hash.3
@@ -1,13 +1,14 @@
.TH ELF_HASH 3 2025-03-31 "Libelf" "Libelf Programmer's Manual"
.SH NAME
-elf_hash \- Compute the standard ELF hash of a string.
+elf_hash, elf_gnu_hash \- Compute the standard ELF hash of a string.
.SH SYNOPSIS
.nf
#include
.BI "unsigned long int elf_hash(const char *" string ");"
+.BI "unsigned long int elf_gnu_hash(const char *" string ");"
.SH DESCRIPTION
The
@@ -18,13 +19,21 @@ symbol table hashing. The hash function is used in
SHT_HASH sections as
it avoids generating architecture-dependent values and is suitable for use
across architectures.
+The
+.BR elf_gnu_hash
+function computes the GNU-style hash value of a null-terminated string,
+used in
+.B SHT_GNU_HASH
+sections. This method is more space- and time-efficient in dynamic symbol
lookup
+compared to the standard ELF hash, particularly for larger symbol tables.
+
.SH PARAMETERS
.TP
.I string
NULL-terminated string to be hashed.
.SH RETURN VALUE
-This function returns the standard ELF hash value for
+These functions return a hash value for
.IR string .
Only the lower 32 bits of the return value are used.
@@ -43,9 +52,14 @@ InterfaceAttribute Value
T{
.na
.nh
-.BR elf_hash ()
+.BR elf_hash (),\~elf_gnu_hash ()
T} Thread safety MT-Safe
.TE
.SH REPORTING BUGS
Report bugs to or
https://sourceware.org/bugzilla/.
+
+.SH HISTORY
+.B elf_gnu_hash
+first appeared in elfutils 0.122. This function is a elfutils libelf
extension and
+may not be available in other libelf implementations.
--
2.49.0
[PATCH 05/16] doc: Add elf_getphdrnum.3
Signed-off-by: Aaron Merey
---
doc/Makefile.am | 1 +
doc/elf_getphdrnum.3 | 74
2 files changed, 75 insertions(+)
create mode 100644 doc/elf_getphdrnum.3
diff --git a/doc/Makefile.am b/doc/Makefile.am
index d3fd9a49..5c1cd51e 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -68,6 +68,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
elf_getdata.3 \
elf_getdata_rawchunk.3 \
elf_getident.3 \
+ elf_getphdrnum.3 \
elf_getscn.3 \
elf_hash.3 \
elf_kind.3 \
diff --git a/doc/elf_getphdrnum.3 b/doc/elf_getphdrnum.3
new file mode 100644
index ..f67899bd
--- /dev/null
+++ b/doc/elf_getphdrnum.3
@@ -0,0 +1,74 @@
+.TH ELF_GETPHDRNUM 3 2025-06-30 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf_getphdrnum \- retrieve the number of program headers in an ELF file
+.SH SYNOPSIS
+.nf
+#include
+
+.B int elf_getphdrnum("Elf *elf", "size_t *dst");
+.fi
+.SH DESCRIPTION
+The
+.BR elf_getphdrnum ()
+function stores the number of program headers associated with the ELF
descriptor
+.I elf
+into the variable pointed to by
+.IR dst .
+
+If the number of program headers exceeds the representable range of the
+.I e_phnum
+field in the ELF header, the ELF specification allows encoding the true count
+in section header 0’s
+.I sh_info
+field, and sets
+.I e_phnum
+to the reserved value
+.B PN_XNUM
+(usually 0x). This function transparently handles that case.
+
+If no program headers are present, or if the ELF file has not yet been fully
+initialized, the function may return 0 as the count.
+
+.SH PARAMETERS
+.TP
+.I elf
+A pointer to an
+.B Elf
+descriptor.
+The descriptor must represent a file with
+.I Elf_Kind
+.B ELF_K_ELF .
+
+.TP
+.I dst
+On success, the number of program headers in
+.I elf
+is written here. Must not be NULL.
+
+.SH RETURN VALUE
+Returns 0 on success and stores the result in
+.IR dst .
+Returns \-1 on failure or if
+.B elf
+is NULL.
+
+.SH SEE ALSO
+.BR libelf (3),
+.BR elf (5)
+
+.SH ATTRIBUTES
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR elf_getphdrnum ()
+T} Thread safety MT-Safe
+.TE
+
+.SH REPORTING BUGS
+Report bugs to or
https://sourceware.org/bugzilla/.
--
2.49.0
[PATCH 15/16] doc: Add elf_scnshndx.3
Signed-off-by: Aaron Merey
---
doc/Makefile.am| 1 +
doc/elf_scnshndx.3 | 68 ++
2 files changed, 69 insertions(+)
create mode 100644 doc/elf_scnshndx.3
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 50ab63ec..dc4a8b18 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -85,6 +85,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
elf_rand.3 \
elf_rawdata.3 \
elf_rawfile.3 \
+ elf_scnshndx.3 \
elf_update.3 \
elf_version.3 \
libelf.3
diff --git a/doc/elf_scnshndx.3 b/doc/elf_scnshndx.3
new file mode 100644
index ..8344df89
--- /dev/null
+++ b/doc/elf_scnshndx.3
@@ -0,0 +1,68 @@
+.TH ELF_SCNSHNDX 3 2025-06-30 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf_scnshndx \- Find the index of the SHT_SYMTAB_SHNDX section associated with
a symbol table
+
+.SH SYNOPSIS
+.nf
+#include
+
+.BI "int elf_scnshndx(Elf_Scn *" scn ");"
+.fi
+
+.SH DESCRIPTION
+The
+.BR elf_scnshndx ()
+function searches for the
+.BR SHT_SYMTAB_SHNDX
+section associated with a given symbol table section. It returns the section
+index of the corresponding
+.BR SHT_SYMTAB_SHNDX
+section, or zero if none is found.
+
+This function is used for retrieving extended section indices in ELF files
+with many sections, where standard symbol table entries cannot store all
+possible section references directly.
+
+The function only returns a valid result if
+.IR scn
+refers to a section of type
+.BR SHT_SYMTAB .
+Otherwise, the function returns 0.
+
+.SH PARAMETERS
+.TP
+.I scn
+An
+.B Elf_Scn
+pointer referencing a symbol table section.
+
+.SH RETURN VALUE
+Returns the section index of the
+.BR SHT_SYMTAB_SHNDX
+section if found. If no such section is found, returns 0. On error, returns
\-1.
+
+.SH SEE ALSO
+.BR libelf (3),
+.BR elf (5)
+
+.SH ATTRIBUTES
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR elf_scnshndx ()
+T} Thread safety MT-Safe
+.TE
+
+.SH REPORTING BUGS
+Report bugs to or
https://sourceware.org/bugzilla/.
+
+.SH HISTORY
+.B elf_scnshndx
+first appeared in elfutils 0.132. This function is a elfutils libelf
extension and
+may not be available in other libelf implementations.
--
2.49.0
[PATCH 13/16] doc: Add elf_rawdata.3
Signed-off-by: Aaron Merey
---
doc/Makefile.am | 1 +
doc/elf_rawdata.3 | 97 +++
2 files changed, 98 insertions(+)
create mode 100644 doc/elf_rawdata.3
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 374e5d49..7d5a3eef 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -83,6 +83,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
elf_newscn.3 \
elf_nextscn.3 \
elf_rand.3 \
+ elf_rawdata.3 \
elf_update.3 \
elf_version.3 \
libelf.3
diff --git a/doc/elf_rawdata.3 b/doc/elf_rawdata.3
new file mode 100644
index ..c441edeb
--- /dev/null
+++ b/doc/elf_rawdata.3
@@ -0,0 +1,97 @@
+.TH ELF_RAWDATA 3 2025-06-30 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf_rawdata - Retrieve unprocessed section data from an ELF descriptor.
+
+.SH SYNOPSIS
+.nf
+#include
+
+.BI "Elf_Data *elf_rawdata(Elf_Scn *" scn ", Elf_Data *" data ");"
+.fi
+
+.SH DESCRIPTION
+The
+.BR elf_rawdata ()
+function returns a pointer to an
+.B Elf_Data
+structure containing the unprocessed (raw) contents of the section identified
by
+.IR scn .
+This raw view reflects the exact binary layout in the ELF file, without any
+conversion or translation.
+
+If
+.I data
+is
+.B NULL ,
+the raw data of the section is returned.
+If
+.I data
+is not
+.B NULL ,
+and raw data has not been initialized, the call fails.
+
+For compressed sections (i.e., with the
+.B SHF_COMPRESSED
+flag), the returned
+.B Elf_Data
+contains the compressed form, and its
+.B d_type
+is
+.BR ELF_T_CHDR .
+
+For sections of type
+.B SHT_NOBITS ,
+the
+.B d_buf
+pointer is
+.B NULL .
+
+The data buffer may come directly from the memory-mapped file or may be
+allocated and populated on first access.
+
+.SH PARAMETERS
+.TP
+.I scn
+A section descriptor returned from
+.BR elf_getscn (3)
+or
+.BR elf_nextscn (3) .
+Must not be
+.B NULL .
+
+.TP
+.I data
+Must be
+.B NULL
+on initial invocation. Any other use is not supported.
+
+.SH RETURN VALUE
+Returns a pointer to an
+.B Elf_Data
+descriptor describing the raw contents of the section. On failure,
+.B NULL
+is returned.
+
+.SH SEE ALSO
+.BR elf_getdata (3),
+.BR elf_getscn (3),
+.BR elf_compress (3),
+.BR libelf (3),
+.BR elf (5)
+
+.SH ATTRIBUTES
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR elf_rawdata ()
+T} Thread safety MT-Safe
+.TE
+
+.SH REPORTING BUGS
+Report bugs to or
https://sourceware.org/bugzilla/.
--
2.49.0
[PATCH 14/16] doc: Add elf_rawfile.3
Signed-off-by: Aaron Merey
---
doc/Makefile.am | 1 +
doc/elf_rawfile.3 | 71 +++
2 files changed, 72 insertions(+)
create mode 100644 doc/elf_rawfile.3
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 7d5a3eef..50ab63ec 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -84,6 +84,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
elf_nextscn.3 \
elf_rand.3 \
elf_rawdata.3 \
+ elf_rawfile.3 \
elf_update.3 \
elf_version.3 \
libelf.3
diff --git a/doc/elf_rawfile.3 b/doc/elf_rawfile.3
new file mode 100644
index ..d7a3e3fb
--- /dev/null
+++ b/doc/elf_rawfile.3
@@ -0,0 +1,71 @@
+.TH ELF_RAWFILE 3 2025-06-30 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf_rawfile \- Retrieve a pointer to the entire raw ELF file image
+
+.SH SYNOPSIS
+.nf
+#include
+
+.BI "char *elf_rawfile(Elf *" elf ", size_t *" ptr ");"
+.fi
+
+.SH DESCRIPTION
+The
+.BR elf_rawfile ()
+function returns a pointer to the entire contents of the ELF file represented
by
+.IR elf .
+This data is unprocessed and includes everything from the ELF header to the
+final byte.
+
+If the ELF descriptor was opened from memory or the file has already been
+memory-mapped or fully read, this function returns a pointer to the internal
buffer.
+
+If the ELF data has not yet been read or mapped, it is loaded on demand.
+
+If
+.I ptr
+is non-NULL, the total size in bytes of the raw file is stored in
+.IR *ptr .
+
+The returned buffer is read-only and managed internally by libelf.
+The application must not modify or free it.
+
+.SH PARAMETERS
+.TP
+.I elf
+A handle previously returned by
+.BR elf_begin (3) .
+
+.TP
+.I ptr
+If not
+.BR NULL ,
+receives the size in bytes of the ELF file.
+
+.SH RETURN VALUE
+Returns a pointer to the start of the ELF file data. On failure,
+.B NULL
+is returned and
+.I *ptr
+(if non-NULL) is set to 0.
+
+.SH SEE ALSO
+.BR libelf (3),
+.BR elf (5)
+
+.SH ATTRIBUTES
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR elf_rawfile ()
+T} Thread safety MT-Safe
+.TE
+
+.SH REPORTING BUGS
+Report bugs to or
https://sourceware.org/bugzilla/.
--
2.49.0
[PATCH 16/16] doc: Add elf_strptr.3
Signed-off-by: Aaron Merey
---
doc/Makefile.am | 1 +
doc/elf_strptr.3 | 72
2 files changed, 73 insertions(+)
create mode 100644 doc/elf_strptr.3
diff --git a/doc/Makefile.am b/doc/Makefile.am
index dc4a8b18..f7446872 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -86,6 +86,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
elf_rawdata.3 \
elf_rawfile.3 \
elf_scnshndx.3 \
+ elf_strptr.3 \
elf_update.3 \
elf_version.3 \
libelf.3
diff --git a/doc/elf_strptr.3 b/doc/elf_strptr.3
new file mode 100644
index ..1cfdf401
--- /dev/null
+++ b/doc/elf_strptr.3
@@ -0,0 +1,72 @@
+.TH ELF_STRPTR 3 2025-06-30 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf_strptr \- Return a pointer to a string in a string table section
+
+.SH SYNOPSIS
+.nf
+#include
+
+.BI "char *elf_strptr(Elf *" elf ", size_t " section_index ", size_t " offset
");"
+.fi
+
+.SH DESCRIPTION
+The
+.BR elf_strptr ()
+function returns a pointer to a null-terminated string located at
+.I offset
+bytes from the beginning of the string table section identified by
+.IR section_index .
+The section must be of type
+.BR SHT_STRTAB .
+
+This function validates the provided offset against the size of the string
+table and ensures the string is null-terminated. It transparently handles
+both uncompressed and compressed sections.
+
+If the ELF descriptor is not backed by memory mapping, or the section has
+not been loaded yet, the function will read and initialize the necessary
+data from the file.
+
+.SH PARAMETERS
+.TP
+.I elf
+Pointer to an ELF descriptor.
+
+.TP
+.I section_index
+The index of the string table section (of type
+.BR SHT_STRTAB ).
+
+.TP
+.I offset
+The byte offset from the beginning of the string table section where
+the desired string is located.
+
+.SH RETURN VALUE
+Returns a pointer to the string within the string table if successful.
+Returns
+.B NULL
+on error.
+
+.SH SEE ALSO
+.BR elf (3),
+.BR elf_getscn (3),
+.BR libelf (3),
+.BR elf (5)
+
+.SH ATTRIBUTES
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR elf_strptr ()
+T} Thread safety MT-Safe
+.TE
+
+.SH REPORTING BUGS
+Report bugs to or
https://sourceware.org/bugzilla/.
--
2.49.0
[Bug general/22253] RFE elfutils add man pages documenting the API
https://sourceware.org/bugzilla/show_bug.cgi?id=22253 Aaron Merey changed: What|Removed |Added Assignee|unassigned at sourceware dot org |amerey at redhat dot com --- Comment #4 from Aaron Merey --- Currently we have man pages for all libelf.h functions either merged or posted to elfutils-devel for review. There's still a lot to do but we are progressing faster now than when we started. -- You are receiving this mail because: You are on the CC list for the bug.
[PATCH 09/16] doc: Add elf_newdata.3
Signed-off-by: Aaron Merey
---
doc/Makefile.am | 1 +
doc/elf_newdata.3 | 75 +++
2 files changed, 76 insertions(+)
create mode 100644 doc/elf_newdata.3
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 98712576..97aac570 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -79,6 +79,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
elf_kind.3 \
elf_memory.3 \
elf_ndxscn.3 \
+ elf_newdata.3 \
elf_update.3 \
elf_version.3 \
libelf.3
diff --git a/doc/elf_newdata.3 b/doc/elf_newdata.3
new file mode 100644
index ..4a8a77ad
--- /dev/null
+++ b/doc/elf_newdata.3
@@ -0,0 +1,75 @@
+.TH ELF_NEWDATA 3 2025-06-30 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf_newdata \- create a new Elf_Data descriptor for a section
+
+.SH SYNOPSIS
+.nf
+#include
+
+.BI "Elf_Data * elf_newdata(Elf_Scn *" scn ");"
+.fi
+
+.SH DESCRIPTION
+The
+.BR elf_newdata ()
+function creates a new
+.BR Elf_Data
+descriptor associated with the section referred to by
+.I scn .
+This descriptor can be used to describe new section contents for an ELF object
+being constructed or modified.
+
+The section must not be the null section (index 0), and the section header must
+already be initialized (for example, by calling
+.BR elf_getshdr ()
+after creating the section via
+.BR elf_newscn ()).
+If the section has not yet been assigned data, or was created using
+.BR elf_newscn (),
+this function creates the first
+.BR Elf_Data
+descriptor for the section.
+
+Subsequent calls to
+.BR elf_newdata ()
+will append new data descriptors to the section.
+
+The returned descriptor is marked dirty so that it will be included during
+.BR elf_update () .
+
+.SH PARAMETERS
+.TP
+.I scn
+A section descriptor to which the new data descriptor should be attached.
+Must not be the null section.
+
+.SH RETURN VALUE
+On success, a pointer to a new, writable
+.BR Elf_Data
+descriptor is returned. On failure, NULL is returned.
+
+The caller is responsible for configuring the return value.
+
+.SH SEE ALSO
+.BR elf_getdata (3),
+.BR elf_newscn (3),
+.BR elf_update (3),
+.BR libelf (3),
+.BR elf (5)
+
+.SH ATTRIBUTES
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR elf_newdata ()
+T} Thread safety MT-Safe
+.TE
+
+.SH REPORTING BUGS
+Report bugs to or
https://sourceware.org/bugzilla/.
--
2.49.0
[PATCH 11/16] doc: Add elf_nextscn.3
Signed-off-by: Aaron Merey
---
doc/Makefile.am | 1 +
doc/elf_nextscn.3 | 65 +++
2 files changed, 66 insertions(+)
create mode 100644 doc/elf_nextscn.3
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 022906bb..9ef2b60d 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -81,6 +81,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
elf_ndxscn.3 \
elf_newdata.3 \
elf_newscn.3 \
+ elf_nextscn.3 \
elf_update.3 \
elf_version.3 \
libelf.3
diff --git a/doc/elf_nextscn.3 b/doc/elf_nextscn.3
new file mode 100644
index ..1aac00d0
--- /dev/null
+++ b/doc/elf_nextscn.3
@@ -0,0 +1,65 @@
+.TH ELF_NEXTSCN 3 2025-06-30 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf_nextscn - Return the next section in an ELF descriptor.
+
+.SH SYNOPSIS
+.nf
+#include
+
+.BI "Elf_Scn *elf_nextscn(Elf *" elf ", Elf_Scn *" scn ");"
+.fi
+
+.SH DESCRIPTION
+The
+.BR elf_nextscn ()
+function returns a handle to the next section in the ELF object descriptor
+.IR elf .
+If
+.I scn
+is NULL, the first section (with index 1) is returned. Section index 0 is
+reserved and skipped.
+
+If
+.I scn
+is not NULL, the section immediately following it is returned. If there are
+no further sections, NULL is returned.
+
+.SH PARAMETERS
+.TP
+.I elf
+A pointer to an ELF descriptor.
+.TP
+.I scn
+A section handle returned by
+.BR elf_getscn (3),
+or NULL to begin iteration.
+
+.SH RETURN VALUE
+Returns a pointer to the next
+.B Elf_Scn
+structure in the section list, or NULL if there are no more sections or if
+.I elf
+is NULL.
+
+.SH SEE ALSO
+.BR elf_getscn (3),
+.BR elf_newscn (3),
+.BR libelf (3),
+.BR elf (5)
+
+.SH ATTRIBUTES
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR elf_nextscn ()
+T} Thread safety MT-Safe
+.TE
+
+.SH REPORTING BUGS
+Report bugs to or
https://sourceware.org/bugzilla/.
--
2.49.0
[PATCH 04/16] doc: Add elf_getident.3
Signed-off-by: Aaron Merey
---
doc/Makefile.am| 1 +
doc/elf_getident.3 | 89 ++
2 files changed, 90 insertions(+)
create mode 100644 doc/elf_getident.3
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 8afda0bd..d3fd9a49 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -67,6 +67,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
elf_getbase.3 \
elf_getdata.3 \
elf_getdata_rawchunk.3 \
+ elf_getident.3 \
elf_getscn.3 \
elf_hash.3 \
elf_kind.3 \
diff --git a/doc/elf_getident.3 b/doc/elf_getident.3
new file mode 100644
index ..07f70b80
--- /dev/null
+++ b/doc/elf_getident.3
@@ -0,0 +1,89 @@
+.TH ELF_GETIDENT 3 2025-06-30 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf_getident \- return the ELF identification bytes
+.SH SYNOPSIS
+.nf
+#include
+
+.B char * elf_getident("Elf *elf", "size_t *ptr");
+.fi
+.SH DESCRIPTION
+The
+.BR elf_getident ()
+function returns a pointer to the 16-byte ELF identification array
+from the ELF header of the given descriptor
+.IR elf .
+
+This identification data begins with the magic number `\fB\\177ELF\fR`
+and includes the class, data encoding, ELF version, OS ABI, and ABI
+version fields. It corresponds to the first
+.B EI_NIDENT
+bytes of the ELF header, typically accessed via the
+.B e_ident
+field of either
+.B Elf32_Ehdr
+or
+.B Elf64_Ehdr .
+
+If
+.I elf
+is a valid descriptor for an ELF object, the function returns a pointer to
+the internal buffer containing the header's identification bytes. The buffer
+is owned by the library and must not be modified or freed by the caller.
+
+If
+.I ptr
+is not NULL, the function sets
+.*ptr
+to
+.B EI_NIDENT
+(16), the length in bytes of the returned identifier.
+
+.SH PARAMETERS
+.TP
+.I elf
+Pointer to an
+.B Elf
+descriptor referring to a valid ELF object. If the descriptor does not
+represent an ELF file (e.g., is an archive), NULL is returned.
+
+.TP
+.I ptr
+Optional pointer to a
+.B size_t
+variable. If non-NULL, it will be set to the length of the returned buffer
+(always EI_NIDENT on success, 0 on failure).
+
+.SH RETURN VALUE
+Returns a pointer to the internal 16-byte
+.B e_ident
+buffer on success.
+
+This buffer is indexed using the
+.B EI_*
+macros found in elf.h. See elf.h for a complete list of indexing macros.
+
+Returns NULL if
+.I elf
+is NULL or does not refer to an ELF object.
+
+.SH SEE ALSO
+.BR libelf (3),
+.BR elf (5)
+
+.SH ATTRIBUTES
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR elf_getident ()
+T} Thread safety MT-Safe
+.TE
+
+.SH REPORTING BUGS
+Report bugs to or
https://sourceware.org/bugzilla/.
--
2.49.0
[PATCH 06/16] doc: Add elf_getshdrnum.3 and elf_getshnum.3
Signed-off-by: Aaron Merey
---
doc/Makefile.am | 2 ++
doc/elf_getshdrnum.3 | 76
doc/elf_getshnum.3 | 1 +
3 files changed, 79 insertions(+)
create mode 100644 doc/elf_getshdrnum.3
create mode 100644 doc/elf_getshnum.3
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 5c1cd51e..cf60a271 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -70,6 +70,8 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
elf_getident.3 \
elf_getphdrnum.3 \
elf_getscn.3 \
+ elf_getshdrnum.3 \
+ elf_getshnum.3 \
elf_hash.3 \
elf_kind.3 \
elf_memory.3 \
diff --git a/doc/elf_getshdrnum.3 b/doc/elf_getshdrnum.3
new file mode 100644
index ..719dc0a3
--- /dev/null
+++ b/doc/elf_getshdrnum.3
@@ -0,0 +1,76 @@
+.TH ELF_GETSHDRNUM 3 2025-06-30 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf_getshdrnum, elf_getshnum \- retrieve the number of section headers in an
ELF file
+.SH SYNOPSIS
+.nf
+#include
+
+.B int elf_getshdrnum("Elf *elf", "size_t *dst");
+.B int elf_getshnum("Elf *elf", "size_t *dst");
+.fi
+.SH DESCRIPTION
+The
+.BR elf_getshdrnum ()
+function stores the number of section headers (sections) associated with the
+ELF descriptor
+.I elf
+into the variable pointed to by
+.IR dst .
+
+It transparently handles both standard and extended section header counts as
+represented in modern ELF files.
+
+The function
+.BR elf_getshnum ()
+is a deprecated alias for
+.BR elf_getshdrnum ()
+and should not be used in new code.
+
+.SH PARAMETERS
+.TP
+.I elf
+A pointer to an
+.B Elf
+descriptor opened with
+.BR elf_begin (3).
+The descriptor must represent a file of kind
+.B ELF_K_ELF .
+It must not be NULL.
+
+.TP
+.I dst
+Pointer to a
+.B size_t
+variable. On success, the number of section headers is written here.
+
+.SH RETURN VALUE
+Returns 0 on success and stores the result in
+.IR dst .
+Returns \-1 on failure.
+
+.SH SEE ALSO
+.BR libelf (3),
+.BR elf (5)
+
+.SH ATTRIBUTES
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR elf_getshdrnum (),\~elf_getshnum()
+T} Thread safety MT-Safe
+.TE
+
+.SH REPORTING BUGS
+Report bugs to or
https://sourceware.org/bugzilla/.
+
+.SH HISTORY
+.B elf_getshdrnum
+first appeared in elfutils 0.142. This function is a elfutils libelf
extension and
+may not be available in other libelf implementations.
+
diff --git a/doc/elf_getshnum.3 b/doc/elf_getshnum.3
new file mode 100644
index ..bc84abc2
--- /dev/null
+++ b/doc/elf_getshnum.3
@@ -0,0 +1 @@
+.so man3/elf_getshdrnum.3
--
2.49.0
