Add man pages for some libelf functions

Add man pages for elf32_getehdr.3, elf64_getehdr.3, elf_errmsg.3,
elf_errno.3 and elf_version.3

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

diff --git a/doc/Makefile.am b/doc/Makefile.am
index d707f2adf19edfb156d87c11c5c8916793976d0a..db8526fc36f55b925f4bf6ce8ff5454c2459a693 100644 (file)
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -27,7 +27,15 @@ notrans_dist_man1_MANS= debuginfod-find.1
 
 # Section 3, Library calls
 # libelf man pages (all notrans)
-notrans_dist_man3_MANS=elf_update.3 elf_getdata.3 elf_clone.3 elf_begin.3
+notrans_dist_man3_MANS= elf_update.3 \
+                       elf_getdata.3 \
+                       elf_clone.3 \
+                       elf_begin.3 \
+                       elf32_getehdr.3 \
+                       elf64_getehdr.3 \
+                       elf_errmsg.3 \
+                       elf_errno.3 \
+                       elf_version.3
 
 # libdebuginfod man pages (also notrans)
 # Note we include them even when not building them because we want

diff --git a/doc/elf32_getehdr.3 b/doc/elf32_getehdr.3
new file mode 100644 (file)
index 0000000..dadc813
--- /dev/null
+++ b/doc/elf32_getehdr.3
@@ -0,0 +1,40 @@
+.TH ELF32_GETEHDR 3 2024-06-26 "Libelf" "Libelf Programmer's Manual"
+.SH NAME
+elf32_getehdr \- retrieve the ELF header for a 32-bit ELF descriptor
+
+.SH SYNOPSIS
+.nf
+#include <libelf.h>
+
+Elf32_Ehdr *elf32_getehdr(Elf *elf);
+.fi
+
+.SH DESCRIPTION
+.B elf32_getehdr
+retrieves the ELF header for the given 32-bit ELF descriptor
+.I elf.
+The ELF header contains crucial metadata about the ELF file, such as the type, machine, version, entry point, program header table offset, and section header table offset. See
+.BR elf (5)
+for more information regarding the ELF header.
+
+.SH PARAMETERS
+.TP
+.I elf
+Pointer to the ELF descriptor from which to retrieve the ELF header.
+
+.SH RETURN VALUE
+On success,
+.B elf32_getehdr
+returns a pointer to the
+.B Elf32_Ehdr
+structure. If the ELF descriptor is invalid or not a 32-bit ELF, it returns NULL and sets an error code retrievable by
+.BR elf_errno (3).
+
+.SH SEE ALSO
+.BR elf64_getehdr (3),
+.BR elf_begin (3),
+.BR elf_errno (3),
+.BR elf (5)
+
+.SH REPORTING BUGS
+Report bugs to <elfutils-devel@sourceware.org> or https://sourceware.org/bugzilla/.

diff --git a/doc/elf64_getehdr.3 b/doc/elf64_getehdr.3
new file mode 100644 (file)
index 0000000..95b6558
--- /dev/null
+++ b/doc/elf64_getehdr.3
@@ -0,0 +1,40 @@
+.TH ELF64_GETEHDR 3 2024-06-26 "Libelf" "Libelf Programmer's Manual"
+.SH NAME
+elf64_getehdr \- retrieve the ELF header for a 64-bit ELF descriptor
+
+.SH SYNOPSIS
+.nf
+#include <libelf.h>
+
+Elf64_Ehdr *elf64_getehdr(Elf *elf);
+.fi
+
+.SH DESCRIPTION
+.B elf64_getehdr
+retrieves the ELF header for the given 64-bit ELF descriptor
+.I elf.
+The ELF header contains crucial metadata about the ELF file, such as the type, machine, version, entry point, program header table offset, and section header table offset. See
+.BR elf (5)
+for more information regarding the ELF header.
+
+.SH PARAMETERS
+.TP
+.I elf
+Pointer to the ELF descriptor from which to retrieve the ELF header.
+
+.SH RETURN VALUE
+On success,
+.B elf64_getehdr
+returns a pointer to the
+.B Elf64_Ehdr
+structure. If the ELF descriptor is invalid or not a 64-bit ELF, it returns NULL and sets an error code retrievable by
+.BR elf_errno (3).
+
+.SH SEE ALSO
+.BR elf32_getehdr (3),
+.BR elf_begin (3),
+.BR elf_errno (3),
+.BR elf (5)
+
+.SH REPORTING BUGS
+Report bugs to <elfutils-devel@sourceware.org> or https://sourceware.org/bugzilla/.

diff --git a/doc/elf_errmsg.3 b/doc/elf_errmsg.3
new file mode 100644 (file)
index 0000000..2732d69
--- /dev/null
+++ b/doc/elf_errmsg.3
@@ -0,0 +1,26 @@
+.TH ELF_ERRMSG 3 2024-06-24 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf_errmsg \- return the error message string for a given libelf error code.
+
+.SH SYNOPSIS
+.B #include <libelf.h>
+
+.BI "const char *elf_errmsg(int " err ");"
+
+.SH DESCRIPTION
+The \fBelf_errmsg\fP function retrieves a human-readable string corresponding to the most recent error code set by a libelf library function. If \fIerr\fP is 0, the function returns the error message for the most recent error code. If \fIerr\fP is non-zero, the function returns the error message for the specified error code.
+
+.SH PARAMETERS
+.TP
+.I err
+An \fIint\fP value specifying the error code. If this value is 0, the function returns the error message for the most recent error or NULL if none occurred. If this value is -1, the behaviour is similar to the previous case except that a legal string will be returned instead of NULL.
+
+.SH RETURN VALUE
+The \fBelf_errmsg\fP function returns a string containing the error message. If there is no corresponding error message, it returns NULL.
+
+.SH SEE ALSO
+.BR elf_errno (3)
+
+.SH REPORTING BUGS
+Report bugs to <elfutils-devel@sourceware.org> or https://sourceware.org/bugzilla/.

diff --git a/doc/elf_errno.3 b/doc/elf_errno.3
new file mode 100644 (file)
index 0000000..1629321
--- /dev/null
+++ b/doc/elf_errno.3
@@ -0,0 +1,24 @@
+.TH ELF_ERRNO 3 2024-06-24 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf_errno \- retrieve the error code of the last failing libelf function call.
+
+.SH SYNOPSIS
+.B #include <libelf.h>
+
+.BI "int elf_errno(void);"
+
+.SH DESCRIPTION
+The \fBelf_errno\fP function retrieves the error code of the last failing libelf library function. This error code indicates the type of error that occurred during the failing function call.  Each thread maintains its own separate error code.
+
+.SH PARAMETERS
+This function does not take any parameters.
+
+.SH RETURN VALUE
+The \fBelf_errno\fP function returns an integer representing the most recent error code for the current thread. If no error has occurred, it returns 0. If an error occurred, the function returns a non-zero error code that corresponds to the specific error.  Error codes can be passed to \fBelf_errmsg\fP in order to create a string describing the error.
+
+.SH SEE ALSO
+.BR elf_errmsg (3)
+
+.SH REPORTING BUGS
+Report bugs to <elfutils-devel@sourceware.org> or https://sourceware.org/bugzilla/.

diff --git a/doc/elf_version.3 b/doc/elf_version.3
new file mode 100644 (file)
index 0000000..8309b4e
--- /dev/null
+++ b/doc/elf_version.3
@@ -0,0 +1,23 @@
+.TH ELF_VERSION 3 2024-06-26 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf_version \- set the ELF version for libelf.
+
+.SH SYNOPSIS
+.B #include <libelf.h>
+
+.BI "unsigned int elf_version(unsigned int " version ");"
+
+.SH DESCRIPTION
+The \fBelf_version\fP function sets libelf's ELF version to the specified value. This function must be called before any other libelf functions are used.
+
+.SH PARAMETERS
+.TP
+.I version
+An \fIunsigned int\fP value specifying the desired ELF version for the library.  This is should be set to \fBEV_CURRENT\fP to indicate the current ELF version. At this time the only supported ELF version is \fBEV_CURRENT\fP.
+
+.SH RETURN VALUE
+The \fBelf_version\fP function returns \fBEV_CURRENT\fP if \fIversion\fP is supported and sets the library's ELF version to this value.  If the given \fIversion\fP is \fBEV_NONE\fP, then this function returns \fBEV_CURRENT\fP and does not set the library's ELF version.  If the specified version is not supported, this function returns \fBEV_NONE\fP.
+
+.SH REPORTING BUGS
+Report bugs to <elfutils-devel@sourceware.org> or https://sourceware.org/bugzilla/.