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 87de4f0beb7ff3fd389eefa18e519d9823910270..7bb048a756530695d113203dc0f2a5114def9963 100644 (file)
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -18,7 +18,11 @@
 ## along with this program.  If not, see <http://www.gnu.org/licenses/>.
 EXTRA_DIST = COPYING-GFDL README
 dist_man1_MANS=readelf.1 elfclassify.1 srcfiles.1
-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
+
 notrans_dist_man7_MANS=
 notrans_dist_man8_MANS=
 notrans_dist_man1_MANS=

diff --git a/doc/elf32_getehdr.3 b/doc/elf32_getehdr.3
new file mode 100644 (file)
index 0000000..4dbb388
--- /dev/null
+++ b/doc/elf32_getehdr.3
@@ -0,0 +1,36 @@
+.TH ELF32_GETEHDR 3
+.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.
+
+.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)
+
+.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..acf9a12
--- /dev/null
+++ b/doc/elf64_getehdr.3
@@ -0,0 +1,36 @@
+.TH ELF64_GETEHDR 3
+.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.
+
+.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 elf64_getehdr (3),
+.BR elf_begin (3)
+
+.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..1031b58
--- /dev/null
+++ b/doc/elf_errmsg.3
@@ -0,0 +1,26 @@
+.TH ELF_ERRMSG 3
+
+.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. If this value is non-zero, the function returns the error message for the specified error code.
+
+.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..e25f520
--- /dev/null
+++ b/doc/elf_errno.3
@@ -0,0 +1,24 @@
+.TH ELF_ERRNO 3
+
+.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.
+
+.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. 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..fd309ae
--- /dev/null
+++ b/doc/elf_version.3
@@ -0,0 +1,23 @@
+.TH ELF_VERSION 3
+
+.SH NAME
+elf_version \- set the ELF library version
+
+.SH SYNOPSIS
+.B #include <libelf.h>
+
+.BI "unsigned int elf_version(unsigned int " version ");"
+
+.SH DESCRIPTION
+The \fBelf_version\fP function sets the library'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 library version. This is should be set to \fBEV_CURRENT\fP to indicate the current version of the library. At this time the only supported \fIversion\fP values are \fBEV_CURRENT\fP and \fBEV_NONE\fP.
+
+.SH RETURN VALUE
+The \fBelf_version\fP function returns \fBEV_CURRENT\fP when \fIversion\fP is supported. If the specified version is not supported, it returns \fBEV_NONE\fP.
+
+.SH REPORTING BUGS
+Report bugs to <elfutils-devel@sourceware.org> or https://sourceware.org/bugzilla/.