Hi Aaron,

On Mon, Jun 30, 2025 at 11:12:21PM -0400, Aaron Merey wrote:
> Signed-off-by: Aaron Merey <ame...@redhat.com>
> ---
>  doc/Makefile.am    |  1 +
>  doc/elf_getident.3 | 89 ++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 90 insertions(+)
>  create mode 100644 doc/elf_getident.3
> 
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index 8afda0bd..d3fd9a49 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -67,6 +67,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
>                       elf_getbase.3 \
>                       elf_getdata.3 \
>                       elf_getdata_rawchunk.3 \
> +                     elf_getident.3 \
>                       elf_getscn.3 \
>                       elf_hash.3 \
>                       elf_kind.3 \

OK.

> diff --git a/doc/elf_getident.3 b/doc/elf_getident.3
> new file mode 100644
> index 00000000..07f70b80
> --- /dev/null
> +++ b/doc/elf_getident.3
> @@ -0,0 +1,89 @@
> +.TH ELF_GETIDENT 3 2025-06-30 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +elf_getident \- return the ELF identification bytes
> +.SH SYNOPSIS
> +.nf
> +#include <libelf.h>
> +
> +.B char * elf_getident("Elf *elf", "size_t *ptr");
> +.fi

OK.

> +.SH DESCRIPTION
> +The
> +.BR elf_getident ()
> +function returns a pointer to the 16-byte ELF identification array
> +from the ELF header of the given descriptor
> +.IR elf .
> +
> +This identification data begins with the magic number `\fB\\177ELF\fR`
> +and includes the class, data encoding, ELF version, OS ABI, and ABI
> +version fields. It corresponds to the first
> +.B EI_NIDENT
> +bytes of the ELF header, typically accessed via the
> +.B e_ident
> +field of either
> +.B Elf32_Ehdr
> +or
> +.B Elf64_Ehdr .

typically? Maybe: and can also be accessed via ...

> +If
> +.I elf
> +is a valid descriptor for an ELF object, the function returns a pointer to
> +the internal buffer containing the header's identification bytes. The buffer
> +is owned by the library and must not be modified or freed by the caller.

It is valid till elf_end is called.

> +If
> +.I ptr
> +is not NULL, the function sets
> +.*ptr
> +to
> +.B EI_NIDENT
> +(16), the length in bytes of the returned identifier.

OK.

> +.SH PARAMETERS
> +.TP
> +.I elf
> +Pointer to an
> +.B Elf
> +descriptor referring to a valid ELF object.  If the descriptor does not
> +represent an ELF file (e.g., is an archive), NULL is returned.

Maybe say "an ELF object file (is NULL or elf_kind is not ELF_K_ELF), ..."?

> +.TP
> +.I ptr
> +Optional pointer to a
> +.B size_t
> +variable. If non-NULL, it will be set to the length of the returned buffer
> +(always EI_NIDENT on success, 0 on failure).
> +
> +.SH RETURN VALUE
> +Returns a pointer to the internal 16-byte
> +.B e_ident
> +buffer on success.

NULL on failure. Does not set elf_errno.

> +This buffer is indexed using the
> +.B EI_*
> +macros found in elf.h.  See elf.h for a complete list of indexing macros.

See elf (5) ? And maybe just list them? There are just 5 "interesting"
bytes.  EI_CLASS, EI_DATA, EI_VERSION, EI_OSABI, EI_ABIVERSION.

And maybe this should be in the description? Not in the RETURN VALUE
section?

> +Returns NULL if
> +.I elf
> +is NULL or does not refer to an ELF object.

Ah, you already mention that. The index part confused me.

> +.SH SEE ALSO
> +.BR libelf (3),
> +.BR elf (5)

OK.

> +.SH ATTRIBUTES
> +.TS
> +allbox;
> +lbx lb lb
> +l l l.
> +Interface    Attribute       Value
> +T{
> +.na
> +.nh
> +.BR elf_getident ()
> +T}   Thread safety   MT-Safe
> +.TE
> +
> +.SH REPORTING BUGS
> +Report bugs to <elfutils-devel@sourceware.org> or 
> https://sourceware.org/bugzilla/.

OK.

Thanks,

Mark

Reply via email to