diff mbox series

[5/9] doc: Add elf32_getshdr.3 and elf64_getshdr.3

Message ID 20240814213321.244089-5-amerey@redhat.com
State Superseded
Delegated to: Mark Wielaard
Headers
Series [1/9] doc: Add elf32_checksum.3 and elf64_checksum.3 |

Commit Message

Aaron Merey Aug. 14, 2024, 9:33 p.m. UTC 
  Signed-off-by: Aaron Merey <amerey@redhat.com>
---
 doc/elf32_getshdr.3 | 46 +++++++++++++++++++++++++++++++++++++++++++++
 doc/elf64_getshdr.3 | 46 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 92 insertions(+)
 create mode 100644 doc/elf32_getshdr.3
 create mode 100644 doc/elf64_getshdr.3

Comments

Mark Wielaard Aug. 27, 2024, 10:58 p.m. UTC | #1 
Hi Aaron,

Meta. In this series I am only commenting on the elf32 variants,
because the elf64 variants are really just identical. Would it make
sense to combine these into one man page?

e.g readv and writev are really the same:
https://man7.org/linux/man-pages/man2/readv.2.html
https://man7.org/linux/man-pages/man2/writev.2.html

On Wed, Aug 14, 2024 at 05:33:17PM -0400, Aaron Merey wrote:
> diff --git a/doc/elf32_getshdr.3 b/doc/elf32_getshdr.3
> new file mode 100644
> index 00000000..5e01fe1c
> --- /dev/null
> +++ b/doc/elf32_getshdr.3
> @@ -0,0 +1,46 @@
> +.TH ELF32_GETSHDR 3 2024-08-14 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +elf32_getshdr \- retrieve the section header for a section in an ELF32 object file
> +
> +.SH SYNOPSIS
> +.B #include <libelf.h>
> +
> +.BI "Elf32_Shdr *elf32_getshdr(Elf_Scn *" scn ");"
> +
> +.SH DESCRIPTION
> +Retrieve the section header for the section referred to by
> +.I scn.

This should imho describe the Shdr members. It also should mention
that if you change any member field you should call elf_flagshdr
ELF_C_SET ELF_F_DIRTY to make sure the (changed) Shdr is written out
to the file again.

> +
> +.SH PARAMETERS
> +.TP
> +.I scn
> +The section descriptor whose section header is to be retrieved.
> +
> +.SH RETURN VALUE
> +On success, return a pointer to the section header. If an error occurs, returns
> +NULL and set a libelf error code.

Should probably mention that if scn is NULL the return value will also
be NULL and the libelf error code will not be changed (to help
propagate errors).

> +.SH SEE ALSO
> +.BR elf_errno (3),
> +.BR elf64_getshdr (3),
> +.BR libelf (3),
> +.BR elf (5)

Add elf_flagshdr.

> +.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_getshdr ()
> +T}	Thread safety	MT-Safe
> +.TE
> +
> +.SH REPORTING BUGS
> +Report bugs to <elfutils-devel@sourceware.org> or https://sourceware.org/bugzilla/.

Cheers,

Mark
diff mbox series

Patch

diff --git a/doc/elf32_getshdr.3 b/doc/elf32_getshdr.3
new file mode 100644
index 00000000..5e01fe1c
--- /dev/null
+++ b/doc/elf32_getshdr.3
@@ -0,0 +1,46 @@ 
+.TH ELF32_GETSHDR 3 2024-08-14 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf32_getshdr \- retrieve the section header for a section in an ELF32 object file
+
+.SH SYNOPSIS
+.B #include <libelf.h>
+
+.BI "Elf32_Shdr *elf32_getshdr(Elf_Scn *" scn ");"
+
+.SH DESCRIPTION
+Retrieve the section header for the section referred to by
+.I scn.
+
+.SH PARAMETERS
+.TP
+.I scn
+The section descriptor whose section header is to be retrieved.
+
+.SH RETURN VALUE
+On success, return a pointer to the section header. If an error occurs, returns
+NULL and set a libelf error code.
+
+.SH SEE ALSO
+.BR elf_errno (3),
+.BR elf64_getshdr (3),
+.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 elf32_getshdr ()
+T}	Thread safety	MT-Safe
+.TE
+
+.SH REPORTING BUGS
+Report bugs to <elfutils-devel@sourceware.org> or https://sourceware.org/bugzilla/.
diff --git a/doc/elf64_getshdr.3 b/doc/elf64_getshdr.3
new file mode 100644
index 00000000..cd816aa9
--- /dev/null
+++ b/doc/elf64_getshdr.3
@@ -0,0 +1,46 @@ 
+.TH ELF64_GETSHDR 3 2024-08-14 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf64_getshdr \- retrieve the section header for a section in an ELF64 object file
+
+.SH SYNOPSIS
+.B #include <libelf.h>
+
+.BI "Elf64_Shdr *elf64_getshdr(Elf_Scn *" scn ");"
+
+.SH DESCRIPTION
+Retrieve the section header for the section referred to by
+.I scn.
+
+.SH PARAMETERS
+.TP
+.I scn
+The section descriptor whose section header is to be retrieved.
+
+.SH RETURN VALUE
+On success, return a pointer to the section header. If an error occurs, returns
+NULL and set a libelf error code.
+
+.SH SEE ALSO
+.BR elf_errno (3),
+.BR elf32_getshdr (3),
+.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 elf64_getshdr ()
+T}	Thread safety	MT-Safe
+.TE
+
+.SH REPORTING BUGS
+Report bugs to <elfutils-devel@sourceware.org> or https://sourceware.org/bugzilla/.