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_offscn.3 | 66 +++++++++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 67 insertions(+)
> create mode 100644 doc/gelf_offscn.3
>
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index bc0ade8a..e8d4c0a6 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -94,6 +94,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
> gelf_getclass.3 \
> gelf_getehdr.3 \
> gelf_newehdr.3 \
> + gelf_offscn.3 \
> gelf_update_ehdr.3 \
> libelf.3
OK.
>
> diff --git a/doc/gelf_offscn.3 b/doc/gelf_offscn.3
> new file mode 100644
> index 00000000..628e83df
> --- /dev/null
> +++ b/doc/gelf_offscn.3
> @@ -0,0 +1,66 @@
> +.TH GELF_OFFSCN 3 2025-09-22 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +gelf_offscn \- return descriptor for an ELF section at a given file offset
> +
> +.SH SYNOPSIS
> +.nf
> +.B #include <gelf.h>
> +
> +.BI "Elf_Scn *gelf_offscn(Elf *" elf ", GElf_Off " offset ");"
> +.fi
OK.
> +.SH DESCRIPTION
> +.B gelf_offscn()
> +retrieves the section descriptor for the non-empty section at the specified
> +file offset in the ELF object referred to by
> +.IR elf .
Maybe explicitly mention that the matching section must have sh_offset
equal to offset and that you can never match a SHT_NOBITS section
because they are empty by definition?
> +.SH PARAMETERS
> +.TP
> +.I elf
> +Pointer to an ELF descriptor with kind
> +.BR ELF_K_ELF .
> +
> +.TP
> +.I offset
> +The file offset (in bytes) of the section to be retrieved.
OK.
> +.SH RETURN VALUE
> +On success,
> +.BR gelf_offscn ()
> +returns a pointer to the
> +.I Elf_Scn
> +of the non-empty section with a sh_offset matching
> +.IR offset .
> +
> +On failure,
> +.B NULL
> +is returned and elf_errno is set to indicate the error. If
> +.I elf
> +is NULL, then NULL is returned without setting elf_errno.
OK.
But I see a bug in the implementation, if the last section (matching)
has zero sh_size or is SHT_NOBITS then it will still be returned (and
libelf_errno will also be set). I'll post a patch.
> +.SH SEE ALSO
> +.BR libelf (3),
> +.BR elf (5)
elf32_offscn, elf64_offscn
> +
> +.SH ATTRIBUTES
> +.TS
> +allbox;
> +lbx lb lb
> +l l l.
> +Interface Attribute Value
> +T{
> +.na
> +.nh
> +.BR gelf_offscn ()
> +T} Thread safety MT-Safe
> +.TE
> +
> +.SH REPORTING BUGS
> +Report bugs to <[email protected]> or
> https://sourceware.org/bugzilla/.
> +
> +HISTORY
> +.B gelf_offscn
> +first appeared in elfutils 0.112. This elfutils libelf function may not be
> +found in other libelf implementations.
OK.
Cheers,
Mark
