Hi Aaron,
On Sun, 2025-09-21 at 21:31 -0400, Aaron Merey wrote:
> Signed-off-by: Aaron Merey <[email protected]>
> ---
> doc/Makefile.am | 1 +
> doc/gelf_newehdr.3 | 82 ++++++++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 83 insertions(+)
> create mode 100644 doc/gelf_newehdr.3
>
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index c0d979ec..bc0ade8a 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -93,6 +93,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
> elf_version.3 \
> gelf_getclass.3 \
> gelf_getehdr.3 \
> + gelf_newehdr.3 \
> gelf_update_ehdr.3 \
> libelf.3
OK.
>
> diff --git a/doc/gelf_newehdr.3 b/doc/gelf_newehdr.3
> new file mode 100644
> index 00000000..58ee910c
> --- /dev/null
> +++ b/doc/gelf_newehdr.3
> @@ -0,0 +1,82 @@
> +.TH GELF_NEWEHDR 3 2025-09-17 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +gelf_newehdr \- allocate and initialize a new ELF file header
> +
> +.SH SYNOPSIS
> +.nf
> +.B #include <gelf.h>
> +
> +.BI "GElf_Ehdr *gelf_newehdr(Elf *" elf ", int " class ");"
> +.fi
Yes, that is what I would expect, but note that our own documentation
in gelf.h says:
/* Create new ELF header if none exists. Creates an Elf32_Ehdr if CLASS
is ELFCLASS32 or an Elf64_Ehdr if CLASS is ELFCLASS64. Returns NULL
on error. */
extern void *gelf_newehdr (Elf *__elf, int __class);
And that is also what our implementation does.
It returns either a Elf32_Ehdr or Elf32_Ehdr handle.
This doesn't seem very consistent between libelf implementations.
The Solaris gelf_newehdr returns ulong_t. Documentation is unclear what
the return value represents. It just says "Upon failure, all GElf
functions return 0 and set elf_errno". But BSD versions also return
void * like we do (but doesn't seem to promise the return value is an
Elf[32|64}_Ehdr just that NULL means failure.
None seem to say what the ehdr values will be initialized to.
Our implementation sets all fields to zero, except when the ehdr
already exists then it does nothing (but still returns success).
> +.SH DESCRIPTION
> +.BR gelf_newehdr ()
> +allocates and initializes a new ELF header for
> +.IR elf ,
> +if a header does not already exist.
Maybe add, if it doesn't exist an all zero ehdr is created?
> +.PP
> +The caller must specify the ELF class via
> +.IR class ,
> +which must be either:
> +.TP
> +.B ELFCLASS32
> +Request a 32\-bit ELF file header.
> +.TP
> +.B ELFCLASS64
> +Request a 64\-bit ELF file header.
OK.
> +.SH PARAMETERS
> +.TP
> +.I elf
> +Pointer to an ELF descriptor of kind
> +.BR ELF_K_ELF .
> +
> +.TP
> +.I class
> +The requested ELF class for the new header. Must be
> +.B ELFCLASS32
> +or
> +.BR ELFCLASS64 .
> +
> +.SH RETURN VALUE
> +On success,
> +.B gelf_newehdr()
> +will return a non-zero value. The ELF header of
> +.I elf
> +can be retrieved using
> +.BR gelf_getehdr ().
> +.BR elf32_getehdr ()
> +or
> +.BR elf64_getehdr ()
> +can also be used depending on the ELF class specified by
> +.IR class .
> +
> +On failure, NULL is returned and elf_errno is set. If
> +.I elf
> +is NULL then NULL is returned without setting elf_errno.
OK.
> +.SH SEE ALSO
> +.BR elf32_getehdr ()
> +.BR elf64_getehdr ()
> +.BR gelf_getehdr (3),
> +.BR gelf_update_ehdr (3),
> +.BR libelf (3),
> +.BR elf (5)
OK.
> +.SH ATTRIBUTES
> +.TS
> +allbox;
> +lbx lb lb
> +l l l.
> +Interface Attribute Value
> +T{
> +.na
> +.nh
> +.BR gelf_newehdr ()
> +T} Thread safety MT-Safe
> +.TE
> +
> +.SH REPORTING BUGS
> +Report bugs to <[email protected]> or
> https://sourceware.org/bugzilla/.
OK. But maybe add a note about other implementations maybe returning a
different type?
Cheers,
Mark
