Hi Aaron,
On Mon, Aug 04, 2025 at 11:24:43PM -0400, Aaron Merey wrote:
> Signed-off-by: Aaron Merey <ame...@redhat.com>
> ---
> v4: Minor rewording in DESCRIPTION and code comment in EXAMPLES
>
> 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 8ad9eb13..96d35d20 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -82,6 +82,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
> elf_ndxscn.3 \
> elf_newdata.3 \
> elf_newscn.3 \
> + elf_next.3 \
> elf_nextscn.3 \
> elf_rand.3 \
> elf_rawdata.3 \
OK.
> diff --git a/doc/elf_next.3 b/doc/elf_next.3
> new file mode 100644
> index 00000000..35336109
> --- /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 (3).
> +.BR elf_next (3)
> +updates the archive descriptor so that
> +.BR elf_begin (3)
> +returns the ELF descriptor of the next member of the archive. See the
> +.B EXAMPLES
> +section below.
OK. This reads better and is more concise compared to the previous
version.
> +.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 (3).
> +Return the
> +.B Elf_Cmd
> +that was used with
> +.BR elf_begin (3)
> +to initialize
> +.IR elf .
> +
> +.P
> +If
> +.I elf
> +was not initialized from an archive file or there are no more archive
> members,
> +.BR elf_next (3)
> +returns
> +.B ELF_C_NULL.
OK.
> +.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 */
> + [...]
> +
> + /* elf_next updates elf, the parent archive, so that the next call
> + to elf_begin returns the next archive member. */
> + 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
OK. Really nice example.
> +.SH SEE ALSO
> +.BR elf_begin (3),
> +.BR elf_rand (3),
> +.BR libelf (3),
> +.BR elf (5)
OK.
> +.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/.
OK.
Thanks,
Mark
