diff mbox series

[4/4] doc: Add gelf_getehdr.3

Message ID 20250914232102.1033871-4-amerey@redhat.com
State Committed
Delegated to: Mark Wielaard
Headers
Series [1/4,v3] doc: Add elf_flag*.3 |

Commit Message

Aaron Merey Sept. 14, 2025, 11:21 p.m. UTC 
  Signed-off-by: Aaron Merey <amerey@redhat.com>
---
 doc/Makefile.am    |  1 +
 doc/gelf_getehdr.3 | 62 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 63 insertions(+)
 create mode 100644 doc/gelf_getehdr.3

Comments

Mark Wielaard Sept. 16, 2025, 1:07 p.m. UTC | #1 
Hi Aaron,

On Sun, 2025-09-14 at 19:21 -0400, Aaron Merey wrote:
> Signed-off-by: Aaron Merey <amerey@redhat.com>
> ---
>  doc/Makefile.am    |  1 +
>  doc/gelf_getehdr.3 | 62 ++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 63 insertions(+)
>  create mode 100644 doc/gelf_getehdr.3
> 
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index 1230480e..3c22f0aa 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -92,6 +92,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
>  			elf_update.3 \
>  			elf_version.3 \
>  			gelf_getclass.3 \
> +			gelf_getehdr.3 \
>  			libelf.3

OK.
 
>  # libdebuginfod man pages (also notrans)
> diff --git a/doc/gelf_getehdr.3 b/doc/gelf_getehdr.3
> new file mode 100644
> index 00000000..3f43bca8
> --- /dev/null
> +++ b/doc/gelf_getehdr.3
> @@ -0,0 +1,62 @@
> +.TH GELF_GETEHDR 3 2025-09-14 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +gelf_getehdr \- retrieve the header of an ELF binary as a class\-independent structure
> +
> +.SH SYNOPSIS
> +.nf
> +.B #include <gelf.h>
> +
> +.BI "GElf_Ehdr *gelf_getehdr(Elf *" elf ", GElf_Ehdr *" dest " );"
> +.fi

OK.

> +.SH DESCRIPTION
> +.B gelf_getehdr()
> +translates the ELF header of the object referenced by
> +.I elf
> +into a class\-independent
> +.B GElf_Ehdr
> +representation.

OK. I like the SH NAME description slightly better. But this is fine
too.

> +.SH PARAMETERS
> +.TP
> +.I elf
> +Pointer to an ELF descriptor.
> +.TP
> +.I dest
> +Pointer to a caller\-provided
> +.B GElf_Ehdr
> +structure that will receive the translated file header. Must not be
> +NULL.  On success, the function stores the header in
> +.IR *dest .

Maybe add "and returns it"?

> +.SH RETURN VALUE
> +On success, returns
> +.IR dest .
> +On failure, returns
> +.B NULL
> +and sets elf_errno.  If
> +.I elf
> +is NULL, NULL is returned and elf_errno is not set.

OK.

> +.SH SEE ALSO
> +.BR gelf_newehdr (3),
> +.BR gelf_update_ehdr (3),
> +.BR libelf (3),
> +.BR elf (5)

We probably also need an gelf manpage describing the "class
independent" datastructures.

> +.SH ATTRIBUTES
> +.TS
> +allbox;
> +lbx lb lb
> +l l l.
> +Interface	Attribute	Value
> +T{
> +.na
> +.nh
> +.BR gelf_getehdr ()
> +T}	Thread safety	MT-Safe
> +.TE
> +
> +.SH REPORTING BUGS
> +Report bugs to <elfutils-devel@sourceware.org> or https://sourceware.org/bugzilla/.

OK.

Thanks,

Mark
diff mbox series

Patch

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 1230480e..3c22f0aa 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -92,6 +92,7 @@  notrans_dist_man3_MANS= elf32_checksum.3 \
 			elf_update.3 \
 			elf_version.3 \
 			gelf_getclass.3 \
+			gelf_getehdr.3 \
 			libelf.3
 
 # libdebuginfod man pages (also notrans)
diff --git a/doc/gelf_getehdr.3 b/doc/gelf_getehdr.3
new file mode 100644
index 00000000..3f43bca8
--- /dev/null
+++ b/doc/gelf_getehdr.3
@@ -0,0 +1,62 @@ 
+.TH GELF_GETEHDR 3 2025-09-14 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+gelf_getehdr \- retrieve the header of an ELF binary as a class\-independent structure
+
+.SH SYNOPSIS
+.nf
+.B #include <gelf.h>
+
+.BI "GElf_Ehdr *gelf_getehdr(Elf *" elf ", GElf_Ehdr *" dest " );"
+.fi
+
+.SH DESCRIPTION
+.B gelf_getehdr()
+translates the ELF header of the object referenced by
+.I elf
+into a class\-independent
+.B GElf_Ehdr
+representation.
+
+.SH PARAMETERS
+.TP
+.I elf
+Pointer to an ELF descriptor.
+.TP
+.I dest
+Pointer to a caller\-provided
+.B GElf_Ehdr
+structure that will receive the translated file header. Must not be
+NULL.  On success, the function stores the header in
+.IR *dest .
+
+.SH RETURN VALUE
+On success, returns
+.IR dest .
+On failure, returns
+.B NULL
+and sets elf_errno.  If
+.I elf
+is NULL, NULL is returned and elf_errno is not set.
+
+.SH SEE ALSO
+.BR gelf_newehdr (3),
+.BR gelf_update_ehdr (3),
+.BR libelf (3),
+.BR elf (5)
+
+.SH ATTRIBUTES
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR gelf_getehdr ()
+T}	Thread safety	MT-Safe
+.TE
+
+.SH REPORTING BUGS
+Report bugs to <elfutils-devel@sourceware.org> or https://sourceware.org/bugzilla/.