Signed-off-by: Aaron Merey <ame...@redhat.com>
---
doc/elf_begin.3 | 104 ++++++++++++++++++++++++++++++++++++------------
1 file changed, 79 insertions(+), 25 deletions(-)
diff --git a/doc/elf_begin.3 b/doc/elf_begin.3
index 6a1d0c27..cddd181f 100644
--- a/doc/elf_begin.3
+++ b/doc/elf_begin.3
@@ -1,37 +1,91 @@
-.\" Modified Thu Sep 5 2017 by Ben Woodard <wood...@redhat.com>
-.\"
-.TH ELF_BEGIN 3 2017-09-05 "Libelf" "Libelf Programmer's Manual"
+.TH ELF_BEGIN 3 2025-06-02 "Libelf" "Libelf Programmer's Manual"
+
.SH NAME
-elf_begin \- Return descriptor for ELF file.
-.nf
+elf_begin \- initialize an ELF descriptor
.SH SYNOPSIS
-.B #include <libelf.h>
-.sp
-.BI "Elf *elf_begin (int " filedes ", Elf_Cmd " cmd ", Elf *" ref ");"
-.BI "Elf *elf_clone (int " filedes ", Elf_Cmd " cmd ");"
-.BI "int elf_end (Elf *" elf ");"
+.nf
+#include <libelf.h>
+
+Elf *elf_begin(int fildes, Elf_Cmd cmd, Elf *ref);
.fi
.SH DESCRIPTION
-The
-.BR elf_begin ()
+Initialize and return a handle to an ELF file for use with the elfutils
+\fBlibelf\fP library and related elfutils libraries such as \fBlibdw\fP.
+
+The returned \fBElf\fP descriptor must be released using \fBelf_end(3)\fP.
+
+\fBelf_version(3)\fP must be called before using any \fBlibelf\fP library
+including \fBelf_begin(3)\fP.
+
+.SH PARAMETERS
+.TP
+\fIfildes\fP
+A file descriptor referring to an ELF object. The descriptor should be open
+for reading, and optionally for writing, depending on the intended operation.
+.TP
+\fIcmd\fP
+Specifies the action to perform. Common values include:
+.RS
+.TP
+\fBELF_C_NULL\fP
+Return a NULL pointer instead of initializing an ELF descriptor.
+.TP
+\fBELF_C_READ\fP
+Open an ELF descriptor for reading.
+.TP
+\fBELF_C_READ_MMAP\fP
+Open an ELF descriptor for reading using mmap, if available.
+.TP
+\fBELF_C_READ_MMAP_PRIVATE\fP
+Open an ELF descriptor for reading using mmap, if available. This command
+invokes mmap with MAP_PRIVATE whereas the other \fB*_MMAP\fP commands invoke
+mmap with MAP_SHARED. See \fBmmap(2)\fP for more information.
+.TP
+\fBELF_C_WRITE\fP
+Open an ELF descriptor for writing. The descriptor initially refers to an
+empty file.
+.TP
+\fBELF_C_WRITE_MMAP\fP
+Open an ELF descriptor for writing using mmap, if available. The descriptor
+initially refers to an empty file.
+.TP
+\fBELF_C_RDWR\fP
+Open an ELF descriptor for reading and writing.
+.TP
+\fBELF_C_RDWR_MMAP\fP
+Open an ELF descriptor for reading and writing using mmap, if available.
+
+.RE
+.TP
+\fIref\fP
+A reference to an existing \fBElf\fP descriptor. If not \fBNULL\fP, this will
be
+used to duplicate a previous ELF descriptor. \fIref\fP must have been opened
+with read/write permissions consistent with \fIcmd\fP.
+
.SH RETURN VALUE
-.SH ERRORS
-elf_begin ELF_E_NO_VERSION ELF_E_INVALID_FILE ELF_E_INVALID_CMD ELF_E_NOMEM
-elf_clone ELF_E_NOMEM
-elf_end
+On success, \fBelf_begin()\fP returns a pointer to a new Elf descriptor.
+On failure, it returns \fBNULL\fP and sets an internal error state that can be
+retrieved with \fBelf_errmsg(3)\fP.
+
+.SH SEE ALSO
+.BR mmap (2),
+.BR elf_end (3),
+.BR elf_clone (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;
-lbw29 lb lb
+lbx lb lb
l l l.
-Interface Attribute Value
+Interface Attribute Value
T{
-.BR elf_begin (),
-.BR elf_clone (),
-.BR elf_end ()
-T} Thread safety MT-Safe
+.na
+.nh
+.BR elf_begin ()
+T} Thread safety MT-Safe
.TE
-.SH SEE ALSO
+.SH REPORTING BUGS
+Report bugs to <elfutils-devel@sourceware.org> or
https://sourceware.org/bugzilla/.
--
2.49.0
