Hi Aaron, On Mon, Jun 30, 2025 at 11:12:29PM -0400, Aaron Merey wrote: > Signed-off-by: Aaron Merey <ame...@redhat.com> > --- > doc/Makefile.am | 1 + > doc/elf_rand.3 | 68 +++++++++++++++++++++++++++++++++++++++++++++++++ > 2 files changed, 69 insertions(+) > create mode 100644 doc/elf_rand.3 > > diff --git a/doc/Makefile.am b/doc/Makefile.am > index 9ef2b60d..374e5d49 100644 > --- a/doc/Makefile.am > +++ b/doc/Makefile.am > @@ -82,6 +82,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \ > elf_newdata.3 \ > elf_newscn.3 \ > elf_nextscn.3 \ > + elf_rand.3 \ > elf_update.3 \ > elf_version.3 \ > libelf.3
OK. > diff --git a/doc/elf_rand.3 b/doc/elf_rand.3 > new file mode 100644 > index 00000000..59449733 > --- /dev/null > +++ b/doc/elf_rand.3 > @@ -0,0 +1,68 @@ > +.TH ELF_RAND 3 2025-06-30 "Libelf" "Libelf Programmer's Manual" > + > +.SH NAME > +elf_rand - Set the current offset for archive member retrieval. Maybe Sets the offset for the next archive member in an Elf file? > +.SH SYNOPSIS > +.nf > +#include <libelf.h> > + > +.BI "size_t elf_rand(Elf *" elf ", size_t " offset ");" > +.fi OK. > +.SH DESCRIPTION > +The > +.BR elf_rand () > +function sets the current archive member offset for the ELF archive > descriptor > +.I elf > +to > +.IR offset . > +This affects subsequent calls to > +.BR elf_next (3), > +causing iteration to resume from the member at the specified offset. It does, but I wonder if that isn't a bug. elf_next operates on an archive member, not the (parent) ELF archive handle. It would give you the next member after the offset you just set. I think normally you would call elf_begin with the same elf as ref to get the archive member for the offset. Lets also mention you would get the offets from the elf_getarsym array. > + > +This function is only valid when > +.I elf > +refers to an archive descriptor (i.e., its kind is > +.BR ELF_K_AR ). OK. > +If the archive header at the given offset cannot be parsed or validated, > +the current member is marked unusable. Which imho is a bug. Lets just say an error (zero) is returned. > +.SH PARAMETERS > +.TP > +.I elf > +A pointer to an ELF archive descriptor. > + > +.TP > +.I offset > +A byte offset relative to the beginning of the archive, indicating the > desired member position. Maybe say "The byte offset to the archive header"? > +.SH RETURN VALUE > +Returns the input > +.I offset > +if successful. Returns 0 if > +.I elf > +is NULL, is not an archive descriptor, or if an error occurs while reading > the member at > +.IR offset . > + > +.SH SEE ALSO > +.BR elf_next (3), > +.BR libelf (3), > +.BR elf (5) Add elf_getarsym. > +.SH ATTRIBUTES > +.TS > +allbox; > +lbx lb lb > +l l l. > +Interface Attribute Value > +T{ > +.na > +.nh > +.BR elf_rand () > +T} Thread safety MT-Safe > +.TE > + > +.SH REPORTING BUGS > +Report bugs to <elfutils-devel@sourceware.org> or > https://sourceware.org/bugzilla/. OK. Thanks, Mark