Hi Aaron,
On Mon, Aug 04, 2025 at 11:24:42PM -0400, Aaron Merey wrote:
> Signed-off-by: Aaron Merey <ame...@redhat.com>
> ---
> v2: Some rewording. Describe differences between elf_rawdata and
> elf_getdata. Also mention that the returned Elf_Data is owned by
> libelf and should not be manually freed.
>
> doc/Makefile.am | 1 +
> doc/elf_rawdata.3 | 100 ++++++++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 101 insertions(+)
> create mode 100644 doc/elf_rawdata.3
>
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index f1e074f9..8ad9eb13 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -84,6 +84,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
> elf_newscn.3 \
> elf_nextscn.3 \
> elf_rand.3 \
> + elf_rawdata.3 \
> elf_rawfile.3 \
> elf_scnshndx.3 \
> elf_strptr.3 \
OK.
> diff --git a/doc/elf_rawdata.3 b/doc/elf_rawdata.3
> new file mode 100644
> index 00000000..bf731745
> --- /dev/null
> +++ b/doc/elf_rawdata.3
> @@ -0,0 +1,100 @@
> +.TH ELF_RAWDATA 3 2025-06-30 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +elf_rawdata - Retrieve unprocessed section data from an ELF section.
> +
> +.SH SYNOPSIS
> +.nf
> +#include <libelf.h>
> +
> +.BI "Elf_Data *elf_rawdata(Elf_Scn *" scn ", Elf_Data *" data ");"
> +.fi
OK.
> +.SH DESCRIPTION
> +The
> +.BR elf_rawdata ()
> +function returns a pointer to an
> +.B Elf_Data
> +structure containing the unprocessed (raw) contents of the section
> +identified by
> +.IR scn .
> +This raw view reflects the exact on-disk binary layout of the ELF file
> +with no modifications made for endianness or memory alignment. Use
> +.BR elf_getdata (3)
> +to acquire a view of the data that has been translated to the in-memory
> +format.
> +
> +If
> +.I data
> +is NULL,
> +the raw data of the section is returned. If
> +.I data
> +is not NULL and raw data has not been initialized, the call fails.
> +
> +For compressed sections (i.e., with the
> +.B SHF_COMPRESSED
> +flag), the returned
> +.B Elf_Data
> +contains the compressed form, and its
> +.B d_type
> +is
> +.BR ELF_T_CHDR .
> +
> +For sections of type
> +.B SHT_NOBITS ,
> +the
> +.B d_buf
> +pointer is NULL.
> +
> +The
> +.I Elf_Data *
> +returned by this function and it's
> +.I d_buf
> +are owned by libelf and should not be freed. They are only valid until
> +.BR elf_end (3)
> +is called on the
> +.I Elf
> +descriptor associated with
> +.IR scn .
OK.
> +.SH PARAMETERS
> +.TP
> +.I scn
> +A section descriptor returned from
> +.BR elf_getscn (3)
> +or
> +.BR elf_nextscn (3) .
> +If NULL, then this function returns NULL.
> +
> +.TP
> +.I data
> +Must be NULL on initial invocation. Any other use is not supported.
> +
> +.SH RETURN VALUE
> +Returns a pointer to an
> +.B Elf_Data
> +descriptor describing the raw contents of the section. On failure, NULL
> +is returned and elf_errno is set.
OK.
> +.SH SEE ALSO
> +.BR elf_getdata (3),
> +.BR elf_getscn (3),
> +.BR elf_compress (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_rawdata ()
> +T} Thread safety MT-Safe
> +.TE
> +
> +.SH REPORTING BUGS
> +Report bugs to <elfutils-devel@sourceware.org> or
> https://sourceware.org/bugzilla/.
OK.
Thanks,
Mark
