Add man pages for some libelf functions

Add man pages for elf32_offscn.3, elf64_offscn.3, elf_getscn.3 and
elf_ndxscn.3.

Signed-off-by: Aaron Merey <amerey@redhat.com>

diff --git a/doc/Makefile.am b/doc/Makefile.am
index db8526fc36f55b925f4bf6ce8ff5454c2459a693..86c1d82db73bcdbd4f60798b1b2ffb8cf5bf803f 100644 (file)
--- 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 (file)
index 0000000..7de01f7
--- /dev/null
+++ b/doc/elf32_offscn.3
@@ -0,0 +1,63 @@
+.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 non-empty section at the specified file offset in the ELF32 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 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
+of the non-empty section with a sh_offset matching
+.I 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. This elfutils libelf function may not be found in other libelf implementations.

diff --git a/doc/elf64_offscn.3 b/doc/elf64_offscn.3
new file mode 100644 (file)
index 0000000..157879a
--- /dev/null
+++ b/doc/elf64_offscn.3
@@ -0,0 +1,64 @@
+.TH ELF64_OFFSCN 3 2024-07-18 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf64_offscn \- retrieve a section descriptor by file offset for a 64-bit ELF file
+
+.SH SYNOPSIS
+.B #include <libelf.h>
+
+.BI "Elf_Scn *elf64_offscn(Elf *" elf ", off_t " offset ");"
+
+.SH DESCRIPTION
+The
+.B elf64_offscn
+function retrieves the section descriptor for the non-empty section at the specified file offset in the ELF64 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 offset
+An
+.I off_t
+value representing the file offset of the section whose descriptor is to be retrieved.
+
+.SH RETURN VALUE
+The
+.B elf64_offscn
+function returns a pointer to the
+.I Elf_Scn
+of the non-empty section with a sh_offset matching
+.I 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 elf64_offscn ()
+T}     Thread safety   MT-Safe
+.TE
+
+.SH SEE ALSO
+.BR elf32_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 elf64_offscn
+first appeared in elfutils 0.112.  This elfutils libelf function may not be found in other libelf implementations.

diff --git a/doc/elf_getscn.3 b/doc/elf_getscn.3
new file mode 100644 (file)
index 0000000..eea6ae2
--- /dev/null
+++ b/doc/elf_getscn.3
@@ -0,0 +1,60 @@
+.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.  The section at index 0 is always
+.B 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 (file)
index 0000000..3574574
--- /dev/null
+++ b/doc/elf_ndxscn.3
@@ -0,0 +1,54 @@
+.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.
+.B SHN_UNDEF
+is 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/.