Hi Aaron,
On Mon, 2025-06-02 at 21:22 -0400, Aaron Merey wrote:
> 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
OK, just describes elf_begin now.
> .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.
May be -1 when also given a ref (or must be the same fd as the fd
associated with ref)?
> +.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.
I didn't believe this, but it is true. How useless...
Maybe mention it also ignores ref?
> +.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.
Maybe sort the MMAP variants last as a group?
Maybe mention The MMAP variants are an elfutils libelf extension
possibly not available with other libelf implementations?
Also once the mmap size is set it might fail to extend the size if
mremap cannot grow the mmap in place. This is a real problem that make
ELF_C_RDWR_MMAP often only useful for in-place changes or removing
data. Don't know how to best add this warning. How to use the MMAP
variants is kind of tricky.
> +.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.
> +
Should mention that if the ref is an AR file it will return an Elf
descriptor for the next available object member (see elf_next?). And
that otherwise ref is returned with the reference count updated, so to
dispose of it you need to call elf_end one extra time (see elf_end?).
> .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.
Except if the command is ELF_NULL, and when ref is given and it isn't
an AR file, ref is returned (with the reference count updated).
> +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)
> +
Maybe add elf_next and elf_rand to explain the behavior when the Elf
descriptor (or ref) is an AR file?
> .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/.
