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
> 

Reply via email to