diff mbox series

Add man pages for some libelf functions

Message ID 20240719020302.2755027-1-amerey@redhat.com
State Committed
Headers
Series Add man pages for some libelf functions |

Commit Message

Aaron Merey July 19, 2024, 2:03 a.m. UTC 
  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>
---

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

Comments

Mark Wielaard July 21, 2024, 10:15 p.m. UTC | #1 
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 <amerey@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
>
Aaron Merey July 24, 2024, 10:12 p.m. UTC | #2 
Hi Mark,

On Sun, Jul 21, 2024 at 6:15 PM Mark Wielaard <mark@klomp.org> wrote:
>
> 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 <amerey@redhat.com>

Thanks for the review. I updated the patch with your suggestions and
pushed it as commit a49d5c0e6dee.

Aaron
diff mbox series

Patch

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.
+
+.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.
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
@@ -0,0 +1,62 @@ 
+.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 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
+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 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.
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.
+
+.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.
+
+.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/.