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

Reply via email to