Hi Aaron,
On Mon, 2025-06-30 at 23:12 -0400, Aaron Merey wrote:
> Signed-off-by: Aaron Merey <ame...@redhat.com>
> ---
> doc/Makefile.am | 1 +
> doc/elf_getphdrnum.3 | 74 ++++++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 75 insertions(+)
> create mode 100644 doc/elf_getphdrnum.3
>
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index d3fd9a49..5c1cd51e 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -68,6 +68,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
> elf_getdata.3 \
> elf_getdata_rawchunk.3 \
> elf_getident.3 \
> + elf_getphdrnum.3 \
> elf_getscn.3 \
> elf_hash.3 \
> elf_kind.3 \
OK.
> diff --git a/doc/elf_getphdrnum.3 b/doc/elf_getphdrnum.3
> new file mode 100644
> index 00000000..f67899bd
> --- /dev/null
> +++ b/doc/elf_getphdrnum.3
> @@ -0,0 +1,74 @@
> +.TH ELF_GETPHDRNUM 3 2025-06-30 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +elf_getphdrnum \- retrieve the number of program headers in an ELF file
> +.SH SYNOPSIS
> +.nf
> +#include <libelf.h>
> +
> +.B int elf_getphdrnum("Elf *elf", "size_t *dst");
> +.fi
OK.
> +.SH DESCRIPTION
> +The
> +.BR elf_getphdrnum ()
> +function stores the number of program headers associated with the ELF
> descriptor
> +.I elf
> +into the variable pointed to by
> +.IR dst .
> +
> +If the number of program headers exceeds the representable range of the
> +.I e_phnum
> +field in the ELF header, the ELF specification allows encoding the true count
> +in section header 0’s
> +.I sh_info
> +field, and sets
> +.I e_phnum
> +to the reserved value
> +.B PN_XNUM
> +(usually 0xFFFF). This function transparently handles that case.
Usually? Always.
> +If no program headers are present, or if the ELF file has not yet been fully
> +initialized, the function may return 0 as the count.
What do you mean by "if the ELF file has not yet been fully
initialized"?
I think you should mention that elf_getphdrnum does sanity check the
number of phdrs and will not return more than you can actually address.
This is important when you index into the phdrs array returned by
elf32_getphdr/elf64_getphdr.
> +.SH PARAMETERS
> +.TP
> +.I elf
> +A pointer to an
> +.B Elf
> +descriptor.
> +The descriptor must represent a file with
> +.I Elf_Kind
> +.B ELF_K_ELF .
s/file/image/ ? Or maybe just "an ELF"?
> +.TP
> +.I dst
> +On success, the number of program headers in
> +.I elf
> +is written here. Must not be NULL.
OK.
> +.SH RETURN VALUE
> +Returns 0 on success and stores the result in
> +.IR dst .
> +Returns \-1 on failure
And sets elf_errno?
> or if
> +.B elf
> +is NULL.
OK.
> +.SH SEE ALSO
> +.BR libelf (3),
> +.BR elf (5)
elf32_getphdr/elf64_getphdr?
> +.SH ATTRIBUTES
> +.TS
> +allbox;
> +lbx lb lb
> +l l l.
> +Interface Attribute Value
> +T{
> +.na
> +.nh
> +.BR elf_getphdrnum ()
> +T} Thread safety MT-Safe
> +.TE
> +
> +.SH REPORTING BUGS
> +Report bugs to <elfutils-devel@sourceware.org> or
> https://sourceware.org/bugzilla/.
OK.
Cheers,
Mark
