Re: [PATCH 08/16] doc: Add elf_gnu_hash.3
Hi Aaron,
On Mon, Jun 30, 2025 at 11:12:25PM -0400, Aaron Merey wrote:
> 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 \
OK.
> 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.
standard or GNU?
> .SH SYNOPSIS
> .nf
> #include
>
> .BI "unsigned long int elf_hash(const char *" string ");"
> +.BI "unsigned long int elf_gnu_hash(const char *" string ");"
OK.
> .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.
Yes, but that is the table setup. But the funcion just calculates a
hash value. The hash is also 32bits, maybe it is slightly faster?
> .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.
OK.
> @@ -43,9 +52,14 @@ Interface Attribute 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.
OK.
Thanks,
Mark
Re: [PATCH 10/16] doc: Add elf_newscn.3
Hi Aaron,
On Mon, Jun 30, 2025 at 11:12:27PM -0400, Aaron Merey wrote:
> 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
OK.
> 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 ");"
? Elf_Scn *elf_newscn(Elf *elf);
> +.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.
If the elf didn't have any sections yet, elf_newscn creates the zero
section, but returns a new first section. The zero section is special
and doesn't have any section data associated with it.
> +A newly created section has no name or type and must be properly initialized
> +before calling
> +.BR elf_update ().
> +Use
> +.BR elf_getshdr ()
elf32_getshdr or elf64_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.
Right. Also elf_newscn will never return it (see above).
> +.SH PARAMETERS
> +.TP
> +.I elf
> +An ELF descriptor in ELF_C_WRITE or ELF_C_RDWR mode.
Are you sure? I believe you can always call elf_newscn and it will add
internal data as if the Elf had a new section. You cannot write it out
with elf_update though. The Elf does need to have an Ehdr before
calling elf_newscn though.
> +
> +.SH RETURN VALUE
> +On success,
> +.BR elf_newscn ()
> +returns a pointer to a new section descriptor. On failure, it returns NULL.
and sets elf_errno. If elf is NULL, failure is returned and elf_errno
is not (re)set.
> +
> +.SH SEE ALSO
> +.BR elf_getshdr (3),
elf32_getshdr
elf64_getshdr
> +.BR elf_getdata (3),
> +.BR elf_newdata (3),
> +.BR elf_update (3),
> +.BR libelf (3),
> +.BR elf (5)
OK.
> +.SH ATTRIBUTES
> +.TS
> +allbox;
> +lbx lb lb
> +l l l.
> +InterfaceAttribute Value
> +T{
> +.na
> +.nh
> +.BR elf_newscn ()
> +T} Thread safety MT-Safe
> +.TE
> +
> +.SH REPORTING BUGS
> +Report bugs to or
> https://sourceware.org/bugzilla/.
OK.
Thanks,
Mark
Re: [PATCH 09/16] doc: Add elf_newdata.3
Hi Aaron,
On Mon, Jun 30, 2025 at 11:12:26PM -0400, Aaron Merey wrote:
> 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
OK.
> 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
Maybe adds a new...?
> +
> +.SH SYNOPSIS
> +.nf
> +#include
> +
> +.BI "Elf_Data * elf_newdata(Elf_Scn *" scn ");"
> +.fi
OK.
> +.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 ()).
That last requirement surprises me. I don't see it back in the code.
> +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.
Maybe s/has not yet been assigned data/has no data associated with it yet/ ?
> +Subsequent calls to
> +.BR elf_newdata ()
> +will append new data descriptors to the section.
OK.
> +The returned descriptor is marked dirty so that it will be included during
> +.BR elf_update () .
Maybe add the Elf_Data is initialized to represent no data with d_buf
set to NULL, d_type set to ELF_T_BYTE, d_version set to EV_CURRENT and
d_size, d_off and d_align set to zero.
> +.SH PARAMETERS
> +.TP
> +.I scn
> +A section descriptor to which the new data descriptor should be attached.
> +Must not be the null section.
Must not be section zero. When NULL the function returns NULL.
> +.SH RETURN VALUE
> +On success, a pointer to a new, writable
> +.BR Elf_Data
> +descriptor is returned. On failure, NULL is returned.
and elf_errno will be set. When scn is NULL failure is returned, but
elf_errno isn't (re)set.
> +The caller is responsible for configuring the return value.
Maybe see above for which fields?
> +
> +.SH SEE ALSO
> +.BR elf_getdata (3),
> +.BR elf_newscn (3),
> +.BR elf_update (3),
> +.BR libelf (3),
> +.BR elf (5)
OK.
> +.SH ATTRIBUTES
> +.TS
> +allbox;
> +lbx lb lb
> +l l l.
> +InterfaceAttribute Value
> +T{
> +.na
> +.nh
> +.BR elf_newdata ()
> +T} Thread safety MT-Safe
> +.TE
> +
> +.SH REPORTING BUGS
> +Report bugs to or
> https://sourceware.org/bugzilla/.
OK. Some of the lines are very wide though.
Thanks,
Mark
Re: [PATCH 05/16] doc: Add elf_getphdrnum.3
Hi Aaron,
On Mon, 2025-06-30 at 23:12 -0400, Aaron Merey wrote:
> 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 \
OK.
> 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
OK.
> +.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.
Usually? Always.
> +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.
What do you mean by "if the ELF file has not yet been fully
initialized"?
I think you should mention that elf_getphdrnum does sanity check the
number of phdrs and will not return more than you can actually address.
This is important when you index into the phdrs array returned by
elf32_getphdr/elf64_getphdr.
> +.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 .
s/file/image/ ? Or maybe just "an ELF"?
> +.TP
> +.I dst
> +On success, the number of program headers in
> +.I elf
> +is written here. Must not be NULL.
OK.
> +.SH RETURN VALUE
> +Returns 0 on success and stores the result in
> +.IR dst .
> +Returns \-1 on failure
And sets elf_errno?
> or if
> +.B elf
> +is NULL.
OK.
> +.SH SEE ALSO
> +.BR libelf (3),
> +.BR elf (5)
elf32_getphdr/elf64_getphdr?
> +.SH ATTRIBUTES
> +.TS
> +allbox;
> +lbx lb lb
> +l l l.
> +InterfaceAttribute Value
> +T{
> +.na
> +.nh
> +.BR elf_getphdrnum ()
> +T} Thread safety MT-Safe
> +.TE
> +
> +.SH REPORTING BUGS
> +Report bugs to or
> https://sourceware.org/bugzilla/.
OK.
Cheers,
Mark
Re: [PATCH 06/16] doc: Add elf_getshdrnum.3 and elf_getshnum.3
Hi Aaron,
On Mon, 2025-06-30 at 23:12 -0400, Aaron Merey wrote:
> 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 \
OK.
> 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
Maybe explicitly mark elf_getshnum as deprecated/obsolete?
> +.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.
OK. But in get_phdrnum you explained explicitly how this extended count
worked, why not here? e_shnum is zero and the real shnum is in the zero
section sh_size, technically that is resolved in elf_begin not
get_shdrnum, but I think that doesn't matter for the documentation.
> +The function
> +.BR elf_getshnum ()
> +is a deprecated alias for
> +.BR elf_getshdrnum ()
> +and should not be used in new code.
OK, maybe add note see history?
> +.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.
It can be NULL, then the function returns failure (-1) but doesn't
(re)set elf_errno.
> +
> +.TP
> +.I dst
> +Pointer to a
> +.B size_t
> +variable. On success, the number of section headers is written here.
But this cannot be NULL.
> +.SH RETURN VALUE
> +Returns 0 on success and stores the result in
> +.IR dst .
> +Returns \-1 on failure.
Yes, but see below.
> +
> +.SH SEE ALSO
> +.BR libelf (3),
> +.BR elf (5)
Add elf32_getshdr/elf64_getshdr (which return an array of Shdr of
elf_getshdrnum size).
> +.SH ATTRIBUTES
> +.TS
> +allbox;
> +lbx lb lb
> +l l l.
> +InterfaceAttribute 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/.
OK.
> +.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.
Yes, it was added "later", but this was deliberate and done for all
libelf implementations. That was because the return value of
elf_getshnum was one on success and zero on failure in some
implementations, while others had zero on success and minus one on
failure. So it was decided to introduce a new function elf_getshdrnum
which consistently returned zero on success.
> 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
OK.
Thanks,
Mark
Re: [PATCH 07/16] doc: Add elf_getshdrstrndx.3 and elf_getshstrndx.3
Hi Aaron,
On Mon, 2025-06-30 at 23:12 -0400, Aaron Merey wrote:
> 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 \
OK.
> 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
OK, but maybe mark elf_getshstrndx deprecated/obsolete?
> +.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.
OK, but the last subsentence (from memory or file) seems an
implementation detail.
Maybe add a bit more explanation about how/when to use this (SEE ALSO)?
> +
> +The function
> +.BR elf_getshstrndx ()
> +is a deprecated alias for
> +.BR elf_getshdrstrndx ()
> +and should not be used in new code.
OK. Maybe add see history, below?
> +.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 .
Can also be created with elf_memory.
Elf may be NULL, but then an error is returned.
> +.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.
OK.
> +
> +.SH RETURN VALUE
> +Returns 0 on success and stores the section header string table index in
> +.IR dst .
> +Returns \-1 on failure.
And sets elf_errno, except when elf is NULL.
> +
> +.SH SEE ALSO
> +.BR libelf (3),
> +.BR elf (5)
Maybe add elf32_getshdr/elf64_getshdr and/or elf_strptr since you get
section names using elf_strptr (elf, shdrstrndx, sh_name)
But maybe that should be in the description?
> +
> +.SH ATTRIBUTES
> +.TS
> +allbox;
> +lbx lb lb
> +l l l.
> +InterfaceAttribute 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/.
OK.
> +.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.
Same story as for elf_getshnum/elf_getshdrnum. Some other libelf
implementations got the return value of elf_getshstrndx wrong. So to
get things consistent elf_getshdrstrndx was introduced.
[There also was a get_elfphnum function with the same issue, but
elfutils libelf never had an implementation of that.]
> 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
OK.
Thanks,
Mark
Re: [PATCH 11/16] doc: Add elf_nextscn.3
Hi Aaron,
On Mon, Jun 30, 2025 at 11:12:28PM -0400, Aaron Merey wrote:
> 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
OK.
> 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
OK.
> +.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.
OK.
> +.SH PARAMETERS
> +.TP
> +.I elf
> +A pointer to an ELF descriptor.
> +.TP
> +.I scn
> +A section handle returned by
this function, or
> +.BR elf_getscn (3),
> +or NULL to begin iteration.
OK.
> +.SH RETURN VALUE
> +Returns a pointer to
the first Elf_Scn if scn is NULL,
> the next
> +.B Elf_Scn
> +structure in the section list
after the given scn
, or NULL if there are no more sections or if
> +.I elf
> +is NULL.
OK.
> +.SH SEE ALSO
> +.BR elf_getscn (3),
> +.BR elf_newscn (3),
> +.BR libelf (3),
> +.BR elf (5)
OK.
> +.SH ATTRIBUTES
> +.TS
> +allbox;
> +lbx lb lb
> +l l l.
> +InterfaceAttribute Value
> +T{
> +.na
> +.nh
> +.BR elf_nextscn ()
> +T} Thread safety MT-Safe
> +.TE
> +
> +.SH REPORTING BUGS
> +Report bugs to or
> https://sourceware.org/bugzilla/.
OK.
Thanks,
Mark
