Signed-off-by: Aaron Merey <ame...@redhat.com>
---
v2: Clarify that elf_next is called with an archive member in order
to update the descriptor for the parent archive. Added a code example.
doc/Makefile.am | 1 +
doc/elf_next.3 | 120 ++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 121 insertions(+)
create mode 100644 doc/elf_next.3
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 1ced7858..fbfebfe0 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -61,6 +61,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
elf_hash.3 \
elf_kind.3 \
elf_ndxscn.3 \
+ elf_next.3 \
elf_update.3 \
elf_version.3 \
libelf.3
diff --git a/doc/elf_next.3 b/doc/elf_next.3
new file mode 100644
index 00000000..1e3f0ee5
--- /dev/null
+++ b/doc/elf_next.3
@@ -0,0 +1,120 @@
+.TH ELF_NEXT 3 2025-06-06 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf_next \- advance an ELF descriptor to the next archive member
+
+.SH SYNOPSIS
+.nf
+.B #include <libelf.h>
+
+.BI "Elf_Cmd elf_next(Elf *" elf ");"
+.fi
+.SH DESCRIPTION
+Advance an ELF descriptor associated with an archive file to the next available
+archive member.
+
+.P
+ELF descriptors initialized from an archive file can be used to retrieve ELF
+descriptors for archive members one at a time using
+.BR elf_begin .
+.B elf_next
+updates the archive descriptor so that
+.B elf_begin
+may return the ELF descriptor of the next member of the archive.
+.B elf_next
+is called with a archive member's ELF descriptor and updates descriptor
+of the parent archive (see the EXAMPLES section below).
+
+.SH RETURN VALUE
+If
+.I elf
+refers to an archive member, update the state of the parent archive
+ELF descriptor associated with
+.I elf
+so that the next archive member can be retrieved with
+.BR elf_begin .
+Return the
+.B Elf_Cmd
+that was used with
+.B elf_begin
+to initialize
+.IR elf .
+
+.P
+If
+.I elf
+was not initialized from an archive file or there are no more archive members,
+.B elf_next
+returns
+.B ELF_C_NULL.
+
+.SH EXAMPLES
+.nf
+ /* Open the archive. */
+ fd = open (archive_name, O_RDONLY);
+ if (fd == -1)
+ {
+ printf ("cannot open archive file `%s'", fname);
+ exit (1);
+ }
+
+ /* Set the ELF version. */
+ elf_version (EV_CURRENT);
+
+ /* Create an ELF descriptor for the archive. */
+ cmd = ELF_C_READ;
+ elf = elf_begin (fd, cmd, NULL);
+ if (elf == NULL)
+ {
+ printf ("cannot create ELF descriptor: %s\\n", elf_errmsg (-1));
+ exit (1);
+ }
+
+ /* Verify this is a descriptor for an archive. */
+ if (elf_kind (elf) != ELF_K_AR)
+ {
+ printf ("`%s' is not an archive\\n", fname);
+ exit (1);
+ }
+
+ /* Get the members of the archive one after the other. */
+ while ((subelf = elf_begin (fd, cmd, elf)) != NULL)
+ {
+ /* Process subelf here */
+ [...]
+
+ /* Get next archive element. */
+ cmd = elf_next (subelf);
+ if (elf_end (subelf) != 0)
+ {
+ printf ("error while freeing sub-ELF descriptor: %s\\n",
+ elf_errmsg (-1));
+ exit (1);
+ }
+ }
+
+ elf_end (elf);
+ close (fd);
+.fi
+
+.SH SEE ALSO
+.BR elf_begin (3),
+.BR elf_rand (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_next ()
+T} Thread safety MT-Safe
+.TE
+
+.SH REPORTING BUGS
+Report bugs to <elfutils-devel@sourceware.org> or
https://sourceware.org/bugzilla/.
--
2.49.0
