doc: Update elf_begin.3

Signed-off-by: Aaron Merey <[email protected]>

1 files changed, 99 insertions, 25 deletions

diff --git a/doc/elf_begin.3 b/doc/elf_begin.3
index 6a1d0c27..d753a2d3 100644
--- a/doc/elf_begin.3
+++ b/doc/elf_begin.3
@@ -1,37 +1,111 @@
-.\" Modified Thu Sep 5 2017 by Ben Woodard <[email protected]>
-.\"
-.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 \fBELF_C_*_MMAP\fP commands
+invoke mmap with MAP_SHARED.  See \fBmmap(2)\fP for more information.
+.RE
+.TP
+\fIref\fP
+A reference to an existing Elf descriptor.  If \fIref\fP refers to regular
+ELF binary (not an AR file), then \fBelf_begin\fP will duplicate \fIref\fP.
+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 refers to 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).
+
+\fIref\fP may be NULL, in which case this argument is ignored.
+
 .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_next (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 <[email protected]> or https://sourceware.org/bugzilla/.