Hi Aaron,
On Mon, Jun 09, 2025 at 12:24:38PM -0400, Aaron Merey wrote:
> Signed-off-by: Aaron Merey <ame...@redhat.com>
> ---
> doc/Makefile.am | 1 +
> doc/elf_getarhdr.3 | 76 ++++++++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 77 insertions(+)
> create mode 100644 doc/elf_getarhdr.3
>
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index 6451ffab..aae29ebc 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -55,6 +55,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
> elf_errmsg.3 \
> elf_errno.3 \
> elf_fill.3 \
> + elf_getarhdr.3 \
> elf_getaroff.3 \
> elf_getbase.3 \
> elf_getdata.3 \
Ack.
> diff --git a/doc/elf_getarhdr.3 b/doc/elf_getarhdr.3
> new file mode 100644
> index 00000000..5dcedf89
> --- /dev/null
> +++ b/doc/elf_getarhdr.3
> @@ -0,0 +1,76 @@
> +.TH ELF_GETARHDR 3 2025-06-06 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +elf_getarhdr \- retrieve archive member header information
> +
> +.SH SYNOPSIS
> +.nf
> +.B #include <libelf.h>
> +
> +.BI "Elf_Arhdr *elf_getarhdr(Elf *" elf ");"
> +.fi
> +
> +.SH DESCRIPTION
> +Return a
> +.B Elf_Arhdr *
> +describing the archive header of the archive member currently referred
> +to by an ELF descriptor.
> +
> +The
> +.B Elf_Arhdr
> +structure is defined as:
> +
> +.P
> +.nf
> +typedef struct {
> + char *ar_name; /* Name of archive member. */
> + time_t ar_date; /* File date. */
> + uid_t ar_uid; /* User ID. */
> + gid_t ar_gid; /* Group ID. */
> + mode_t ar_mode; /* File mode. */
> + int64_t ar_size; /* File size. */
> + char *ar_rawname; /* Original name of archive member. */
> +} Elf_Arhdr;
> +.fi
> +
> +.SH PARAMETERS
> +.TP
> +.I elf
> +An ELF descriptor referring to a member of an archive file.
> +
> +.SH RETURN VALUE
> +If
> +.I elf
> +refers to an archive member,
> +.B elf_getarhdr()
> +returns a pointer to its archive header. This pointer is valid only until
> +.BR elf_next (3)
on the parent elf archive descriptor?
What about elf_rand?
> +or
> +.BR elf_end (3)
> +is called on the descriptor.
I think this description of the lifetime if the returned Elf_Arhdr is
correct given how the code is implemented. But I must say it is a
little confusing.
It also looks like if you call elf_getarhdr after elf_next or elf_rand
is called on the parent elf archive descriptor you get the Elf_Arhdr
of that ar member. That is really odd. I am afraid all the ar
member/archive elf descriptor stuff confuses me a little.
> If
> +.I elf
> +does not refer to an archive member or the header cannot be
> +acquired then NULL is returned.
> +
> +.SH SEE ALSO
> +.BR elf_begin (3),
> +.BR elf_getaroff (3),
> +.BR elf_next (3),
> +.BR libelf (3),
> +.BR elf (5)
elf_rand?
> +
> +.SH ATTRIBUTES
> +.TS
> +allbox;
> +lbx lb lb
> +l l l.
> +Interface Attribute Value
> +T{
> +.na
> +.nh
> +.BR elf_getarhdr ()
> +T} Thread safety MT-Safe
> +.TE
So it looks like all this depends on the state of the parent archive
elf descriptor. Is that something we can express as Thread safety
attribute value?
> +.SH REPORTING BUGS
> +Report bugs to <elfutils-devel@sourceware.org> or
> https://sourceware.org/bugzilla/.
> --
> 2.49.0
>
