[PATCH 03/21] doc: Add gelf_update_phdr.3

[Mark Wielaard]

Hi Aaron,

On Wed, 2025-12-31 at 21:50 -0500, Aaron Merey wrote:
> Signed-off-by: Aaron Merey <amerey@redhat.com>
> ---
>  doc/Makefile.am        |  1 +
>  doc/gelf_update_phdr.3 | 84 ++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 85 insertions(+)
>  create mode 100644 doc/gelf_update_phdr.3
> 
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index b0825ca6..820880aa 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -107,6 +107,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
>  			gelf_newphdr.3 \
>  			gelf_offscn.3 \
>  			gelf_update_ehdr.3 \
> +			gelf_update_phdr.3 \
>  			gelf_update_shdr.3 \
>  			gelf_update_rel.3 \
>  			gelf_update_rela.3 \

Ack.

> diff --git a/doc/gelf_update_phdr.3 b/doc/gelf_update_phdr.3
> new file mode 100644
> index 00000000..453dc9c8
> --- /dev/null
> +++ b/doc/gelf_update_phdr.3
> @@ -0,0 +1,84 @@
> +.TH GELF_UPDATE_PHDR 3 2025-12-27 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +gelf_update_phdr \- copy a class\-independent program header table entry into an ELF descriptor
> +
> +.SH SYNOPSIS
> +.nf
> +.B #include <gelf.h>
> +
> +.BI "int gelf_update_phdr (Elf *" elf ", int " ndx ", GElf_Phdr *" src ");"
> +
> +.SH DESCRIPTION
> +.BR gelf_update_phdr ()
> +copies the class\-independent program header table entry from the structure
> +pointed to by
> +.I src
> +into the program header table of
> +.I elf
> +at index
> +.I ndx .
> +The program header table entry is translated as necessary to match the class
> +(\fBELFCLASS32\fP or \fBELFCLASS64\fP) of the underlying object file.

OK.

> +
> +If
> +.I elf
> +has class
> +.B ELFCLASS32
> +then
> +.BR p_offset ,
> +.B p_vaddr
> +and
> +.B p_paddr
> +must fit within unsigned 32-bit values.

And p_filesz, p_memsz, p_align.

> +
> +.SH PARAMETERS
> +.TP
> +.I elf
> +Pointer to an ELF descriptor of kind
> +.BR ELF_K_ELF .
> +
> +.TP
> +.I ndx
> +Index of the program header table entry to be updated.

Mention elf_getphdrnum?

> +.TP
> +.I src
> +Pointer to a
> +.B GElf_Phdr
> +structure that holds the caller's desired program header table entry contents.
> +.I src
> +must not be NULL.

OK.

> +.SH RETURN VALUE
> +On success, this function returns a non-zero value and updates the program
> +header table entry at index
> +.IR ndx .
> +The program header table will be flagged with
> +.BR ELF_F_DIRTY .
> +On failure, it returns 0 and sets elf_errno.  If
> +.I elf
> +is NULL then 0 is returned without setting elf_errno.

OK.

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

Add elf_getphdrnum?

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

OK.

Thanks,

Mark