Signed-off-by: Aaron Merey <ame...@redhat.com>
---
v2: Address Mark's suggestions
https://patchwork.sourceware.org/project/elfutils/patch/20250603012245.411580-1-ame...@redhat.com/
doc/elf_begin.3 | 118 ++++++++++++++++++++++++++++++++++++++----------
1 file changed, 93 insertions(+), 25 deletions(-)
diff --git a/doc/elf_begin.3 b/doc/elf_begin.3
index 6a1d0c27..4d68562f 100644
--- a/doc/elf_begin.3
+++ b/doc/elf_begin.3
@@ -1,37 +1,105 @@
-.\" 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.
+If \fIref\fP is non-NULL, then \fIfildes\fP must either be -1 or be set to the
+same file descriptor as the one associated with \fIref\fP.
+.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. Ignores
+\fIref\fP.
+.TP
+\fBELF_C_READ\fP
+Open an ELF descriptor for reading.
+.TP
+\fBELF_C_WRITE\fP
+Open an ELF descriptor for writing. The descriptor initially refers to an
+empty file.
+.TP
+\fBELF_C_RDWR\fP
+Open an ELF descriptor for reading and writing.
+.TP
+\fBELF_C_READ_MMAP\fP
+Open an ELF descriptor for reading using mmap, if available. The
+\fBELF_C_*_MMAP\fP commands are an elfutils libelf extension and may not be
+available in other libelf implementations. Once the mmap size is set attempts
+to extend the size may fail. Therefore, \fBELF_C_*_MMAP\fP commands tend to be
+more useful for in-place modifications or removal of data from an ELF
+descriptor.
+.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_MMAP\fP
+Open an ELF descriptor for reading and writing 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.
+.RE
+.TP
+\fIref\fP
+A reference to an existing \fBElf\fP descriptor. If not NULL, this will be
+used to duplicate a previous ELF descriptor. The reference count associated
+with \fIref\fP will be incremented and \fBelf_end(3)\fP will need to be called
+an additional time to deallocate \fIref\fP. \fIref\fP must have been opened
+with read/write permissions consistent with \fIcmd\fP. If \fIref\fP is an AR
+file, then the ELF descriptor returned will be the first available object
member
+of the archive (see \fBelf_next(3)\fP for more information).
+
.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.
+If \fIcmd\fP is \fBELF_C_NULL\fP then NULL is returned. If \fIref\fP is
+non-NULL and isn't an AR file, then a copy of \fIref\fP is returned. On
+failure, \fBelf_begin()\fP returns NULL and sets an internal error
+state that can be retrieved with \fBelf_errmsg(3)\fP.
+
+.SH SEE ALSO
+.BR mmap (2),
+.BR elf_clone (3),
+.BR elf_end (3),
+.BR elf_rand (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
