[1/4] doc: Add elf_next.3
Commit Message
Signed-off-by: Aaron Merey <amerey@redhat.com>
---
doc/Makefile.am | 1 +
doc/elf_next.3 | 66 +++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 67 insertions(+)
create mode 100644 doc/elf_next.3
Comments
Hi Aaron,
On Mon, 2025-06-09 at 12:24 -0400, Aaron Merey wrote:
> 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
Ack.
> diff --git a/doc/elf_next.3 b/doc/elf_next.3
> new file mode 100644
> index 00000000..fb691bce
> --- /dev/null
> +++ b/doc/elf_next.3
> @@ -0,0 +1,66 @@
> +.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.
I think this doesn't really describe that this function is slightly
"weird". You give it an Elf descriptor associated with an AR archive
member and it advances the Elf descriptor of the Elf archive (the
parent of) the archive member it came from. So this is different from
elf_rand which you give the actual Elf archive descriptor.
Sorry for not having a good phrasing for this. But I think it is
important to mention that this operates not on the given Elf
descriptor, but on parent. And that you have to call elf_begin with the
parent ref to actually get the next archive member Elf descriptor.
Maybe an code example could be added?
> +.P
> +If
> +.I elf
> +was initialized from an archive file,
> +.B elf_next()
> +updates
> +.I elf
> +to refer to the next ELF object in the archive.
Do not elf itself, but the (parent) archive elf descriptor.
> If
> +.I elf
> +was not initialized from an archive file, then this function makes no changes to
> +.I elf.
It doesn't make changes to elf in any case.
> +.SH RETURN VALUE
> +If
> +.I elf
> +refers to an archive and another member is available, update the state of
> +.I elf
parent/archive elf descriptor
> +is updated so that it refers to the next archive member and return the
> +.B Elf_Cmd
> +that was used with
> +.B elf_begin
> +to initialize
> +.IR elf .
Yes.
> +.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.
Yes.
> +.SH SEE ALSO
> +.BR elf_begin (3),
> +.BR libelf (3),
> +.BR elf (5)
Maybe add elf_rand?
> +.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/.
@@ -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
new file mode 100644
@@ -0,0 +1,66 @@
+.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
+If
+.I elf
+was initialized from an archive file,
+.B elf_next()
+updates
+.I elf
+to refer to the next ELF object in the archive. If
+.I elf
+was not initialized from an archive file, then this function makes no changes to
+.I elf.
+
+.SH RETURN VALUE
+If
+.I elf
+refers to an archive and another member is available, update the state of
+.I elf
+is updated so that it refers to the next archive member and 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 SEE ALSO
+.BR elf_begin (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/.