Hi Aaron,
On Wed, 2025-09-24 at 19:00 -0400, Aaron Merey wrote:
> Signed-off-by: Aaron Merey <[email protected]>
> ---
> doc/Makefile.am | 1 +
> doc/gelf_update_shdr.3 | 71 ++++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 72 insertions(+)
> create mode 100644 doc/gelf_update_shdr.3
>
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index 78d88696..b6826f4e 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -98,6 +98,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
> gelf_newphdr.3 \
> gelf_offscn.3 \
> gelf_update_ehdr.3 \
> + gelf_update_shdr.3 \
> libelf.3
>
OK.
>
> # libdebuginfod man pages (also notrans)
> diff --git a/doc/gelf_update_shdr.3 b/doc/gelf_update_shdr.3
> new file mode 100644
> index 00000000..d14da0b3
> --- /dev/null
> +++ b/doc/gelf_update_shdr.3
> @@ -0,0 +1,71 @@
> +.TH GELF_UPDATE_SHDR 3 2025-09-23 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +gelf_update_shdr \- copy a class\-independent section header into a section
> descriptor
> +
> +.SH SYNOPSIS
> +.nf
> +.B #include <gelf.h>
> +
> +.BI "int gelf_update_shdr(Elf_Scn *" scn ", GElf_Shdr *" src ");"
> +.fi
OK.
> +.SH DESCRIPTION
> +.BR gelf_update_shdr ()
> +copies the class\-independent section header referenced by
> +.I src
> +into the section descriptor
> +.IR scn .
> +The section header is translated as necessary to match the class (
> +.B ELFCLASS32
> +or
> +.BR ELFCLASS64 )
> +of the underlying ELF object.
OK. Probably also mention that if the ELF is ELFCLASS32 then the values
of the sh struct member do need to fit into 32bit field values. And
that on success the section header is marked with ELF_F_DIRTY so it
gets written out on an elf_update.
> +
> +.SH PARAMETERS
> +.TP
> +.I scn
> +Pointer to a section descriptor of type
> +.BR Elf_Scn .
> +
> +.TP
> +.I src
> +Pointer to a
> +.B GElf_Shdr
> +structure containing the caller’s desired section header contents.
OK.
> +.SH RETURN VALUE
> +On success,
> +.BR gelf_update_shdr ()
> +returns
> +.B 1 .
> +On failure, it returns
> +.B 0
> +and elf_errno is set. If
> +.I scn
> +or
> +.I src
> +are NULL, 0 is returned without setting elf_errno.
Should we be explicit about returning the value 1 on success?
Maybe just say on error zero is returned and leave it at that?
I mean, it is what our implementation does, but I think people should
just check the return value is (or isn't) equal to zero.
> +.SH SEE ALSO
> +.BR gelf_getshdr (3),
> +.BR elf_getscn (3),
> +.BR elf_nextscn (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_update_shdr ()
> +T} Thread safety MT-Safe
> +.TE
> +
> +.SH REPORTING BUGS
> +Report bugs to <[email protected]> or
> https://sourceware.org/bugzilla/.
OK.
Thanks,
Mark
