Hi Aaron, On Mon, Jun 30, 2025 at 11:12:18PM -0400, Aaron Merey wrote: > Signed-off-by: Aaron Merey <ame...@redhat.com> > --- > doc/Makefile.am | 1 + > doc/elf_memory.3 | 84 ++++++++++++++++++++++++++++++++++++++++++++++++ > 2 files changed, 85 insertions(+) > create mode 100644 doc/elf_memory.3 > > diff --git a/doc/Makefile.am b/doc/Makefile.am > index 3ed04cd7..e5b12133 100644 > --- a/doc/Makefile.am > +++ b/doc/Makefile.am > @@ -63,6 +63,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \ > elf_getscn.3 \ > elf_hash.3 \ > elf_kind.3 \ > + elf_memory.3 \ > elf_ndxscn.3 \ > elf_update.3 \ > elf_version.3 \
OK. > diff --git a/doc/elf_memory.3 b/doc/elf_memory.3 > new file mode 100644 > index 00000000..88d259ca > --- /dev/null > +++ b/doc/elf_memory.3 > @@ -0,0 +1,84 @@ > +.TH ELF_MEMORY 3 2025-06-23 "Libelf" "Libelf Programmer's Manual" > + > +.SH NAME > +elf_memory \- create an ELF descriptor from a memory buffer > +.SH SYNOPSIS > +.nf > +#include <libelf.h> > + > +.B Elf * elf_memory(char *" image ", size_t" size "); OK. > + > +.fi > +.SH DESCRIPTION > +The > +.BR elf_memory () > +function creates a new ELF descriptor from a memory region containing an ELF > +object. This function is used when the ELF data is already present in memory > +rather than being read from a file descriptor. > + OK. > +The memory pointed to by > +.I image > +must contain a complete ELF file or archive. The contents must remain valid > +and unmodified for the lifetime of the resulting ELF descriptor. > + > +The ELF descriptor returned by > +.BR elf_memory () > +is opened in read-only mode using ELF_C_READ_MMAP_PRIVATE (see > +.BR elf_begin ). > +Writing, updating, or modifying this ELF descriptor is not permitted. Yeah, hmmm. There has been some debate on that. Originally it was like ELF_C_READ, then ELF_C_READ_MMAP and now ELF_C_READ_MMAP_PRIVATE. See https://sourceware.org/bugzilla/show_bug.cgi?id=31225 Crash when using elf_memory() on a compressed section; fixed with s/ELF_C_READ/ELF_C_READ_MMAP/ commit cc44ac6740797a23cd0af0cb22bd828d569224b8 libelf: Treat elf_memory as if using ELF_C_READ_MMAP commit 81981fdfd8f776508579da60d29e068359c61e6a libelf: Treat elf_memory image as writable So while it is still treated as "read-only" it also allows modifications in place. It is complicated. > +.PP > +Internally, > +.BR elf_memory () > +is equivalent to calling > +.BR elf_begin () > +to create a descriptor from an open memory buffer with command > +.B ELF_C_READ_MMAP_PRIVATE > +and a NULL parent. Open memory buffer? Do you mean from an open file descriptor? > +.SH PARAMETERS > +.TP > +.I image > +A pointer to a memory buffer that contains the complete contents of an ELF > file > +or archive. Should not be NULL. Fails and returns NULL when image is NULL. > + > +.TP > +.I size > +The size in bytes of the memory region pointed to by > +.IR image . > +Must be greater than zero and cover the entire ELF object. Size must be at least a full ELF header. > +.SH RETURN VALUE > +On success, > +.BR elf_memory () > +returns a pointer to an > +.B Elf > +descriptor representing the archive or ELF file contained in > +.IR image . > + > +On failure, it returns NULL and sets an error code retrievable by > +.BR elf_errmsg (3). OK. > + > +.SH SEE ALSO > +.BR elf_begin (3), > +.BR elf_errmsg (3), > +.BR libelf (3), > +.BR elf (5) OK. > +.SH ATTRIBUTES > +.TS > +allbox; > +lbx lb lb > +l l l. > +Interface Attribute Value > +T{ > +.na > +.nh > +.BR elf_memory () > +T} Thread safety MT-Safe > +.TE > + > +.SH REPORTING BUGS > +Report bugs to <elfutils-devel@sourceware.org> or > https://sourceware.org/bugzilla/. > + > -- > 2.49.0 >
