Hi Aaron,
On Wed, 2024-08-14 at 17:33 -0400, Aaron Merey wrote:
> diff --git a/doc/elf32_newphdr.3 b/doc/elf32_newphdr.3
> new file mode 100644
> index 00000000..8f55566c
> --- /dev/null
> +++ b/doc/elf32_newphdr.3
> @@ -0,0 +1,62 @@
> +.TH ELF32_NEWPHDR 3 2024-08-14 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +elf32_newphdr \- create a new program header table for an ELF32 object file
> +
> +.SH SYNOPSIS
> +.B #include <libelf.h>
> +
> +.BI "Elf32_Phdr *elf32_newphdr(Elf *" elf ", size_t " count ");"
> +
> +.SH DESCRIPTION
> +Create a new program header table for the ELF32 object file referred to by
> +.I elf.
> +The number of entries in the new program header table is specified by
> +.I count. A
> +.I count
> +of zero removes the existing program header table.
> +
> +The function allocates a new array of
> +.I Elf32_Phdr
> +and makes it the program header table for
> +.I elf.
> +Any previous program header table is discarded.
This is unfortunate. But indeed what the code does. Maybe explicitly
mention that the new program headers are zeroed out. So the user knows
to make a copy of any old headers they want to preserve (copy back in
after extending or reducing the program header count).
> +.SH PARAMETERS
> +.TP
> +.I elf
> +Pointer to the ELF object for which a new program header table is to be
> created.
> +
> +.TP
> +.I count
> +The number of entries in the new program header table. A count of zero
> removes
> +the existing program header table.
> +
> +.SH RETURN VALUE
> +On success, return a pointer to the first
> +.I Elf32_Phdr
> +in the newly created program header table. If an error occurs, return NULL
> and set a libelf error code.
If count is zero this also returns NULL.
And like other functions, if elf is NULL no (new) error is set, but
NULL is returned.
Maybe add that an ehdr needs to exists before calling newphdr?
> +
> +.SH SEE ALSO
> +.BR elf_errno (3),
> +.BR elf64_newphdr (3),
> +.BR libelf (3),
> +.BR elf (5)
> +
> +.SH ATTRIBUTES
> +For an explanation of the terms used in this section, see
> +.BR attributes (7).
> +.TS
> +allbox;
> +lbx lb lb
> +l l l.
> +Interface Attribute Value
> +T{
> +.na
> +.nh
> +.BR elf32_newphdr ()
> +T} Thread safety MT-Safe
> +.TE
> +
> +.SH REPORTING BUGS
> +Report bugs to <elfutils-devel@sourceware.org> or
> https://sourceware.org/bugzilla/.
Cheers,
Mark
