Hi Aaron,
Some small comments below.
On Thu, Jul 18, 2024 at 10:03:02PM -0400, Aaron Merey wrote:
> Add man pages for elf32_offscn.3, elf64_offscn.3, elf_getscn.3 and
> elf_ndxscn.3.
>
> Signed-off-by: Aaron Merey <ame...@redhat.com>
> ---
>
> Reposting this patch with the new man pages added to doc/Makefile.am.
>
> doc/Makefile.am | 6 ++++-
> doc/elf32_offscn.3 | 61 +++++++++++++++++++++++++++++++++++++++++++++
> doc/elf64_offscn.3 | 62 ++++++++++++++++++++++++++++++++++++++++++++++
> doc/elf_getscn.3 | 55 ++++++++++++++++++++++++++++++++++++++++
> doc/elf_ndxscn.3 | 52 ++++++++++++++++++++++++++++++++++++++
> 5 files changed, 235 insertions(+), 1 deletion(-)
> create mode 100644 doc/elf32_offscn.3
> create mode 100644 doc/elf64_offscn.3
> create mode 100644 doc/elf_getscn.3
> create mode 100644 doc/elf_ndxscn.3
>
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index db8526fc..86c1d82d 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -35,7 +35,11 @@ notrans_dist_man3_MANS= elf_update.3 \
> elf64_getehdr.3 \
> elf_errmsg.3 \
> elf_errno.3 \
> - elf_version.3
> + elf_version.3 \
> + elf32_offscn.3 \
> + elf64_offscn.3 \
> + elf_getscn.3 \
> + elf_ndxscn.3
>
> # libdebuginfod man pages (also notrans)
> # Note we include them even when not building them because we want
> diff --git a/doc/elf32_offscn.3 b/doc/elf32_offscn.3
> new file mode 100644
> index 00000000..5d4a657f
> --- /dev/null
> +++ b/doc/elf32_offscn.3
> @@ -0,0 +1,61 @@
> +.TH ELF32_OFFSCN 3 2024-07-18 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +elf32_offscn \- retrieve a section descriptor by file offset for a 32-bit
> ELF file
> +
> +.SH SYNOPSIS
> +.B #include <libelf.h>
> +
> +.BI "Elf_Scn *elf32_offscn(Elf *" elf ", off_t " offset ");"
> +
> +.SH DESCRIPTION
> +The
> +.B elf32_offscn
> +function retrieves the section descriptor for the section at the specified
> file offset in the ELF32 object referred to by
> +.I elf.
This should probably say non-empty, not SHT_NOBITS, section which sh_offset
equals the given offset. See this comment in elf32_offscn.c:
/* If this section is empty, the following one has the same
sh_offset. We presume the caller is looking for a nonempty
section, so keep looking if this one is empty. */
> +
> +.SH PARAMETERS
> +.TP
> +.I elf
> +An
> +.I Elf pointer to the ELF object from which the section descriptor is to be
> retrieved.
> +
> +.TP
> +.I offset
> +An
> +.I off_t
> +value representing the file offset of the section whose descriptor is to be
> retrieved.
> +
> +.SH RETURN VALUE
> +The
> +.B elf32_offscn
> +function returns a pointer to the
> +.I Elf_Scn
> +for the section at the specified offset. If an error occurs, it returns NULL
> and sets an appropriate libelf error code.
> +
> +.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_offscn ()
> +T} Thread safety MT-Safe
> +.TE
> +
> +.SH SEE ALSO
> +.BR elf64_offscn (3),
> +.BR libelf (3),
> +.BR elf (5),
> +
> +.SH REPORTING BUGS
> +Report bugs to <elfutils-devel@sourceware.org> or
> https://sourceware.org/bugzilla/.
> +
> +.SH HISTORY
> +.B elf32_offscn
> +first appeared in elfutils 0.112.
It should probably also mention that this is an elfutils only libelf
function, which might not be found in other libelf implementations.
> diff --git a/doc/elf64_offscn.3 b/doc/elf64_offscn.3
> new file mode 100644
> index 00000000..4ab29b30
> --- /dev/null
> +++ b/doc/elf64_offscn.3
Same comments as for elf32_offscn.
> diff --git a/doc/elf_getscn.3 b/doc/elf_getscn.3
> new file mode 100644
> index 00000000..1be13369
> --- /dev/null
> +++ b/doc/elf_getscn.3
> @@ -0,0 +1,55 @@
> +.TH ELF_GETSCN 3 2024-07-18 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +elf_getscn \- retrieve a descriptor for an ELF section at a specified index.
> +
> +.SH SYNOPSIS
> +.B #include <libelf.h>
> +
> +.BI "Elf_Scn *elf_getscn(Elf *" elf ", size_t " index ");"
> +
> +.SH DESCRIPTION
> +The .B elf_getscn function retrieves a section descriptor for the section at
> the specified index in the ELF object referred to by .I elf.
> +
> +.SH PARAMETERS
> +.TP
> +.I elf
> +An
> +.I Elf
> +pointer to the ELF object from which the section descriptor is to be
> retrieved.
> +
> +.TP
> +.I index
> +A
> +.I size_t
> +value representing the index of the section whose descriptor is to be
> retrieved. Section indices start at 0.
Although technically true, it should probably be mentioned that
section zero is always SHT_NULL and does not contain any data.
> +
> +.SH RETURN VALUE
> +The
> +.B elf_getscn
> +function returns a pointer to the
> +.I Elf_Scn
> +for the section at the specified index. If an error occurs, it returns NULL
> and sets an appropriate libelf error code.
> +
> +.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 elf_getscn ()
> +T} Thread safety MT-Safe
> +.TE
> +
> +.SH SEE ALSO
> +.BR elf_errno (3),
> +.BR libelf (3),
> +.BR elf (5)
> +
> +.SH REPORTING BUGS
> +Report bugs to <elfutils-devel@sourceware.org> or
> https://sourceware.org/bugzilla/.
> diff --git a/doc/elf_ndxscn.3 b/doc/elf_ndxscn.3
> new file mode 100644
> index 00000000..e8c493a6
> --- /dev/null
> +++ b/doc/elf_ndxscn.3
> @@ -0,0 +1,52 @@
> +.TH ELF_NDXSCN 3 2024-07-18 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +elf_ndxscn \- retrieve the index of a descriptor for an ELF file section
> +
> +.SH SYNOPSIS
> +.B #include <libelf.h>
> +
> +.BI "size_t elf_ndxscn(Elf_Scn *" scn ");"
> +
> +.SH DESCRIPTION
> +The
> +.B elf_ndxscn
> +function retrieves the index of the section descriptor referred to by
> +.I scn.
> +
> +.SH PARAMETERS
> +.TP
> +.I scn
> +An
> +.I Elf_Scn
> +pointer to the section descriptor whose index is to be retrieved.
> +
> +.SH RETURN VALUE
> +The
> +.B elf_ndxscn
> +function returns the index of the section descriptor. If
> +.I scn
> +is NULL, it returns
> +.B SHN_UNDEF.
It should probably be mentioned that SHN_UNDEF is zero. So for the
zero (SHT_NULL) section you also get back zero.
> +.SH SEE ALSO
> +.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 elf_ndxscn ()
> +T} Thread safety MT-Safe
> +.TE
> +
> +.SH REPORTING BUGS
> +Report bugs to <elfutils-devel@sourceware.org> or
> https://sourceware.org/bugzilla/.
> --
> 2.45.2
>
