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 | 2 ++
> doc/elf_getshdrnum.3 | 76 ++++++++++++++++++++++++++++++++++++++++++++
> doc/elf_getshnum.3 | 1 +
> 3 files changed, 79 insertions(+)
> create mode 100644 doc/elf_getshdrnum.3
> create mode 100644 doc/elf_getshnum.3
>
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index 5c1cd51e..cf60a271 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -70,6 +70,8 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
> elf_getident.3 \
> elf_getphdrnum.3 \
> elf_getscn.3 \
> + elf_getshdrnum.3 \
> + elf_getshnum.3 \
> elf_hash.3 \
> elf_kind.3 \
> elf_memory.3 \
OK.
> diff --git a/doc/elf_getshdrnum.3 b/doc/elf_getshdrnum.3
> new file mode 100644
> index 00000000..719dc0a3
> --- /dev/null
> +++ b/doc/elf_getshdrnum.3
> @@ -0,0 +1,76 @@
> +.TH ELF_GETSHDRNUM 3 2025-06-30 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +elf_getshdrnum, elf_getshnum \- retrieve the number of section headers in an
> ELF file
> +.SH SYNOPSIS
> +.nf
> +#include <libelf.h>
> +
> +.B int elf_getshdrnum("Elf *elf", "size_t *dst");
> +.B int elf_getshnum("Elf *elf", "size_t *dst");
> +.fi
Maybe explicitly mark elf_getshnum as deprecated/obsolete?
> +.SH DESCRIPTION
> +The
> +.BR elf_getshdrnum ()
> +function stores the number of section headers (sections) associated with the
> +ELF descriptor
> +.I elf
> +into the variable pointed to by
> +.IR dst .
> +
> +It transparently handles both standard and extended section header counts as
> +represented in modern ELF files.
OK. But in get_phdrnum you explained explicitly how this extended count
worked, why not here? e_shnum is zero and the real shnum is in the zero
section sh_size, technically that is resolved in elf_begin not
get_shdrnum, but I think that doesn't matter for the documentation.
> +The function
> +.BR elf_getshnum ()
> +is a deprecated alias for
> +.BR elf_getshdrnum ()
> +and should not be used in new code.
OK, maybe add note see history?
> +.SH PARAMETERS
> +.TP
> +.I elf
> +A pointer to an
> +.B Elf
> +descriptor opened with
> +.BR elf_begin (3).
> +The descriptor must represent a file of kind
> +.B ELF_K_ELF .
> +It must not be NULL.
It can be NULL, then the function returns failure (-1) but doesn't
(re)set elf_errno.
> +
> +.TP
> +.I dst
> +Pointer to a
> +.B size_t
> +variable. On success, the number of section headers is written here.
But this cannot be NULL.
> +.SH RETURN VALUE
> +Returns 0 on success and stores the result in
> +.IR dst .
> +Returns \-1 on failure.
Yes, but see below.
> +
> +.SH SEE ALSO
> +.BR libelf (3),
> +.BR elf (5)
Add elf32_getshdr/elf64_getshdr (which return an array of Shdr of
elf_getshdrnum size).
> +.SH ATTRIBUTES
> +.TS
> +allbox;
> +lbx lb lb
> +l l l.
> +Interface Attribute Value
> +T{
> +.na
> +.nh
> +.BR elf_getshdrnum (),\~elf_getshnum()
> +T} Thread safety MT-Safe
> +.TE
> +
> +.SH REPORTING BUGS
> +Report bugs to <elfutils-devel@sourceware.org> or
> https://sourceware.org/bugzilla/.
OK.
> +.SH HISTORY
> +.B elf_getshdrnum
> +first appeared in elfutils 0.142. This function is a elfutils libelf
> extension and
> +may not be available in other libelf implementations.
Yes, it was added "later", but this was deliberate and done for all
libelf implementations. That was because the return value of
elf_getshnum was one on success and zero on failure in some
implementations, while others had zero on success and minus one on
failure. So it was decided to introduce a new function elf_getshdrnum
which consistently returned zero on success.
> diff --git a/doc/elf_getshnum.3 b/doc/elf_getshnum.3
> new file mode 100644
> index 00000000..bc84abc2
> --- /dev/null
> +++ b/doc/elf_getshnum.3
> @@ -0,0 +1 @@
> +.so man3/elf_getshdrnum.3
OK.
Thanks,
Mark
