[4/4] doc: Add elf_getarsym.3
Commit Message
Signed-off-by: Aaron Merey <amerey@redhat.com>
---
doc/Makefile.am | 1 +
doc/elf_getarsym.3 | 91 ++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 92 insertions(+)
create mode 100644 doc/elf_getarsym.3
Comments
Hi Aaron,
On Mon, Jun 09, 2025 at 12:24:39PM -0400, Aaron Merey wrote:
> Signed-off-by: Aaron Merey <amerey@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
>
@@ -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 \
new file mode 100644
@@ -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 .
+
+.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
+
+
+.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.
+
+.SH RETURN VALUE
+If the archive contains a symbol table,
+return a pointer to an array of
+.B Elf_Arsym
+structures and sets
+.I *narsyms
+to the number of entries in the array. 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/.