Hi Aaron,
On Mon, Jun 09, 2025 at 12:24:39PM -0400, Aaron Merey wrote:
> Signed-off-by: Aaron Merey <ame...@redhat.com>
> ---
> doc/Makefile.am | 1 +
> doc/elf_getarsym.3 | 91 ++++++++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 92 insertions(+)
> create mode 100644 doc/elf_getarsym.3
>
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index aae29ebc..d0ec20da 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -57,6 +57,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
> elf_fill.3 \
> elf_getarhdr.3 \
> elf_getaroff.3 \
> + elf_getarsym.3 \
> elf_getbase.3 \
> elf_getdata.3 \
> elf_getscn.3 \
Ack.
> diff --git a/doc/elf_getarsym.3 b/doc/elf_getarsym.3
> new file mode 100644
> index 00000000..74417b46
> --- /dev/null
> +++ b/doc/elf_getarsym.3
> @@ -0,0 +1,91 @@
> +.TH ELF_GETARSYM 3 2025-06-06 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +elf_getarsym \- retrieve archive symbol table
> +
> +.SH SYNOPSIS
> +.nf
> +.B #include <libelf.h>
> +
> +.BI "Elf_Arsym *elf_getarsym(Elf *" elf ", size_t *" narsyms );"
> +.fi
> +
> +.SH DESCRIPTION
> +Retrieve the archive symbol table from the archive file associated with
> +.IR elf .
> +
> +.P
> +If the archive contains a symbol table,
> +.B elf_getarsym()
> +returns a pointer to an array of
> +.B Elf_Arsym
> +structures describing each symbol and stores the number of symbols in this
> +array in
> +.IR narsyms .
If not NULL?
> +
> +.B Elf_Arsym
> +has the following layout:
> +
> +.P
> +.nf
> +typedef struct {
> + char *as_name; /* Symbol name (null-terminated). */
> + int64_t as_off; /* File offset of defining archive member. */
> + uint64_t as_hash; /* Hash value of symbol name. */
> +} Elf_Arsym;
> +.fi
It should probably mention that the last entry is always a special
entry { NULL, 0, ~0L }. Which isn't a valid symbol table entry and can
be used to find the end of the table if narsyms was NULL.
> +
> +.SH PARAMETERS
> +.TP
> +.I elf
> +An ELF descriptor referring to an archive file, obtained by calling
> +.BR elf_begin (3)
> +on an archive.
> +
> +.TP
> +.I narsyms
> +A pointer to a
> +.B size_t
> +in which the number of entries in the symbol table will be stored.
Can be NULL.
> +.SH RETURN VALUE
> +If the archive contains a symbol table,
> +return a pointer to an array of
> +.B Elf_Arsym
> +structures
This includes one extra special 'NULL' entry, which marks the end of
the table.
> and sets
> +.I *narsyms
> +to the number of entries in the array.
If narsyms is not NULL.
> These pointers are managed by
> +libelf and should not be freed by the caller of
> +.BR elf_getarsym .
> +
> +.P
> +If the archive does not contain a symbol table or
> +.I elf
> +is not a valid archive descriptor,
> +.B elf_getarsym
> +returns
> +.B NULL.
> +
> +.SH SEE ALSO
> +.BR elf_begin (3),
> +.BR elf_getarhdr (3),
> +.BR elf_next (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_getarsym ()
> +T} Thread safety MT-Safe
> +.TE
> +
> +.SH REPORTING BUGS
> +Report bugs to <elfutils-devel@sourceware.org> or
> https://sourceware.org/bugzilla/.
> --
> 2.49.0
>
