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