Hi Aaron,
On Mon, 2025-08-04 at 23:24 -0400, Aaron Merey wrote:
> Signed-off-by: Aaron Merey <ame...@redhat.com>
> ---
> v2: replace "open memory buffer" with "open file descriptor". Clarify
> behavior when image is NULL as well as the minimum size of the image.
>
> doc/Makefile.am | 1 +
> doc/elf_memory.3 | 85 ++++++++++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 86 insertions(+)
> create mode 100644 doc/elf_memory.3
>
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index b8511577..e99f685d 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -64,6 +64,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
> elf_getscn.3 \
> elf_hash.3 \
> elf_kind.3 \
> + elf_memory.3 \
> elf_ndxscn.3 \
> elf_nextscn.3 \
> elf_rawfile.3 \
OK.
> diff --git a/doc/elf_memory.3 b/doc/elf_memory.3
> new file mode 100644
> index 00000000..c6620aa5
> --- /dev/null
> +++ b/doc/elf_memory.3
> @@ -0,0 +1,85 @@
> +.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.
> +
> +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.
I still think this is not really giving enough/correct information
about the "mode" the memory needs to be in for it to be handled
"correctly" by libelf (or other libraries).
There are a couple of libelf functions that rely on the underlying
memory to be writable. In particular when calling elf_compress libelf
might want to update the underlying Shdr data. See e.g. commit
81981fdfd. Something similar might happen when calling some libdwfl
functions that might try to apply relocations in the Elf image.
So, yes, writing, updating or modifying the memory image while it is
used by libelf isn't permitted (it would really confuse libelf). But if
the memory is read-only some libelf "update" functions might not work
(and crash because they assume they may change the memory bits).
> +.PP
> +Internally,
> +.BR elf_memory ()
> +is equivalent to calling
> +.BR elf_begin ()
> +to create a descriptor from an open file descriptor with command
> +.B ELF_C_READ_MMAP_PRIVATE
> +and a NULL parent.
OK. Although that might be a bit too much implementation details.
> +.SH PARAMETERS
> +.TP
> +.I image
> +A pointer to a memory buffer that contains the complete contents of an ELF
> file
> +or archive. If NULL, this function fails and returns NULL.
> +
> +.TP
> +.I size
> +The size in bytes of the memory region pointed to by
> +.IR image .
> +Must be at least as much as a full ELF header and should cover the entire ELF
> +object.
OK.
> +.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)
> +
> +.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/.
> +
OK.
Thanks,
Mark
