[3/4] doc: Add elf_getarhdr.3
Commit Message
Signed-off-by: Aaron Merey <amerey@redhat.com>
---
doc/Makefile.am | 1 +
doc/elf_getarhdr.3 | 76 ++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 77 insertions(+)
create mode 100644 doc/elf_getarhdr.3
Comments
Hi Aaron,
On Mon, Jun 09, 2025 at 12:24:38PM -0400, Aaron Merey wrote:
> Signed-off-by: Aaron Merey <amerey@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
>
@@ -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,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)
+or
+.BR elf_end (3)
+is called on the 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 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-Safe
+.TE
+
+.SH REPORTING BUGS
+Report bugs to <elfutils-devel@sourceware.org> or https://sourceware.org/bugzilla/.