[3/6,v2] doc: Add elf_getarhdr.3
Commit Message
Signed-off-by: Aaron Merey <amerey@redhat.com>
---
v2 changes: clarify when changes to the parent archive descriptor
invalidate the return value. Change thread safety attribute to
MT-Unsafe race.
doc/Makefile.am | 1 +
doc/elf_getarhdr.3 | 80 ++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 81 insertions(+)
create mode 100644 doc/elf_getarhdr.3
Comments
Hi Aaron,
On Sun, Jun 22, 2025 at 07:02:05PM -0400, Aaron Merey wrote:
> Signed-off-by: Aaron Merey <amerey@redhat.com>
>
> ---
> v2 changes: clarify when changes to the parent archive descriptor
> invalidate the return value. Change thread safety attribute to
> MT-Unsafe race.
So I think this describes the current implementation. But I also
think that doesn't really make sense. We keep the Elf_Arhdr (state) as
part of the parent archive. Which means you can only have one "active"
header per archive even if you have multiple member Elfs from that
archive.
IMHO we should keep the header state as part of the Elf member itself.
So maybe we should not document the lifetime as it is now. That is
really a bug IMHO.
We could also decide to document it as currently buggy and that we
might fix this later.
Sorry for being slightly confusing here.
> doc/Makefile.am | 1 +
> doc/elf_getarhdr.3 | 80 ++++++++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 81 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 \
> diff --git a/doc/elf_getarhdr.3 b/doc/elf_getarhdr.3
> new file mode 100644
> index 00000000..10c2f62a
> --- /dev/null
> +++ b/doc/elf_getarhdr.3
> @@ -0,0 +1,80 @@
> +.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
> +.B elf_next()
> +or
> +.B elf_rand()
> +update the parent archive ELF descriptor,
So this description is "correct" for the current implementation. But
IMHO not for a "correct" implementation. Should we remove it, fix the
implementation or add a warning this is a bug in the current
implementation?
> +or
> +.BR elf_end()
> +is called on the parent archive ELF descriptor. 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 elf_rand (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_getarhdr ()
> +T} Thread safety MT-Unsafe race
> +.TE
> +
> +.SH REPORTING BUGS
> +Report bugs to <elfutils-devel@sourceware.org> or https://sourceware.org/bugzilla/.
> --
> 2.49.0
>
@@ -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 \
new file mode 100644
@@ -0,0 +1,80 @@
+.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
+.B elf_next()
+or
+.B elf_rand()
+update the parent archive ELF descriptor,
+or
+.BR elf_end()
+is called on the parent archive ELF descriptor. 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 elf_rand (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_getarhdr ()
+T} Thread safety MT-Unsafe race
+.TE
+
+.SH REPORTING BUGS
+Report bugs to <elfutils-devel@sourceware.org> or https://sourceware.org/bugzilla/.