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