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

Reply via email to