From 920a9ac8875d82e8014bf5f3afa6d85dbf00b6cb Mon Sep 17 00:00:00 2001 From: Aaron Merey Date: Thu, 13 Jun 2024 15:20:03 -0400 Subject: [PATCH] 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 --- doc/Makefile.am | 6 +++++- doc/elf32_getehdr.3 | 36 ++++++++++++++++++++++++++++++++++++ doc/elf64_getehdr.3 | 36 ++++++++++++++++++++++++++++++++++++ doc/elf_errmsg.3 | 26 ++++++++++++++++++++++++++ doc/elf_errno.3 | 24 ++++++++++++++++++++++++ doc/elf_version.3 | 23 +++++++++++++++++++++++ 6 files changed, 150 insertions(+), 1 deletion(-) create mode 100644 doc/elf32_getehdr.3 create mode 100644 doc/elf64_getehdr.3 create mode 100644 doc/elf_errmsg.3 create mode 100644 doc/elf_errno.3 create mode 100644 doc/elf_version.3 diff --git a/doc/Makefile.am b/doc/Makefile.am index 0c094af2..6a858c59 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -18,7 +18,11 @@ ## along with this program. If not, see . 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 index 00000000..4dbb3886 --- /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 + +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 or https://sourceware.org/bugzilla/. diff --git a/doc/elf64_getehdr.3 b/doc/elf64_getehdr.3 new file mode 100644 index 00000000..acf9a125 --- /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 + +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 or https://sourceware.org/bugzilla/. diff --git a/doc/elf_errmsg.3 b/doc/elf_errmsg.3 new file mode 100644 index 00000000..1031b581 --- /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 + +.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 or https://sourceware.org/bugzilla/. diff --git a/doc/elf_errno.3 b/doc/elf_errno.3 new file mode 100644 index 00000000..e25f5207 --- /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 + +.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 or https://sourceware.org/bugzilla/. diff --git a/doc/elf_version.3 b/doc/elf_version.3 new file mode 100644 index 00000000..fd309ae1 --- /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 + +.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 or https://sourceware.org/bugzilla/. -- 2.45.2