[13/16] doc: Add elf_rawdata.3

Message ID 20250701031248.1106390-13-amerey@redhat.com
State Superseded
Delegated to: Mark Wielaard
Headers
Series [01/16] doc: Add elf_memory.3 |

Commit Message

Aaron Merey July 1, 2025, 3:12 a.m. UTC
  Signed-off-by: Aaron Merey <amerey@redhat.com>
---
 doc/Makefile.am   |  1 +
 doc/elf_rawdata.3 | 97 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 98 insertions(+)
 create mode 100644 doc/elf_rawdata.3
  

Comments

Mark Wielaard July 9, 2025, 9:39 p.m. UTC | #1
Hi Aaron,

On Mon, Jun 30, 2025 at 11:12:30PM -0400, Aaron Merey wrote:
> Signed-off-by: Aaron Merey <amerey@redhat.com>
> ---
>  doc/Makefile.am   |  1 +
>  doc/elf_rawdata.3 | 97 +++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 98 insertions(+)
>  create mode 100644 doc/elf_rawdata.3
> 
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index 374e5d49..7d5a3eef 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -83,6 +83,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
>  			elf_newscn.3 \
>  			elf_nextscn.3 \
>  			elf_rand.3 \
> +			elf_rawdata.3 \
>  			elf_update.3 \
>  			elf_version.3 \
>  			libelf.3

OK.

> diff --git a/doc/elf_rawdata.3 b/doc/elf_rawdata.3
> new file mode 100644
> index 00000000..c441edeb
> --- /dev/null
> +++ b/doc/elf_rawdata.3
> @@ -0,0 +1,97 @@
> +.TH ELF_RAWDATA 3 2025-06-30 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +elf_rawdata - Retrieve unprocessed section data from an ELF descriptor.

... 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 binary layout in the ELF file, without any
> +conversion or translation.

That is a very long way to say the data is as on-disk.  Maybe add
something about the difference with elf_getdata, which returns the
data translated into the in-memory format?

> +If
> +.I data
> +is
> +.B NULL ,
> +the raw data of the section is returned.
> +If
> +.I data
> +is not
> +.B NULL ,
> +and raw data has not been initialized, the call fails.

That last one surprised me. Although it makes sense, since it gets the
on-disk section contents there is only one buffer to represent that.

> +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
> +.B NULL .

OK.

> +The data buffer may come directly from the memory-mapped file or may be
> +allocated and populated on first access.

Maybe the important thing is that the Elf_Data and d_buf pointer are
owned by libelf, should not be freed and are only valid till elf_end
is called?

> +.SH PARAMETERS
> +.TP
> +.I scn
> +A section descriptor returned from
> +.BR elf_getscn (3)
> +or
> +.BR elf_nextscn (3) .
> +Must not be
> +.B NULL .

If NULL, the call returns NULL.

> +.TP
> +.I data
> +Must be
> +.B 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,
> +.B NULL
> +is returned.

OK.

> +.SH SEE ALSO
> +.BR elf_getdata (3),
> +.BR elf_getscn (3),
> +.BR elf_compress (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_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
  

Patch

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 374e5d49..7d5a3eef 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -83,6 +83,7 @@  notrans_dist_man3_MANS= elf32_checksum.3 \
 			elf_newscn.3 \
 			elf_nextscn.3 \
 			elf_rand.3 \
+			elf_rawdata.3 \
 			elf_update.3 \
 			elf_version.3 \
 			libelf.3
diff --git a/doc/elf_rawdata.3 b/doc/elf_rawdata.3
new file mode 100644
index 00000000..c441edeb
--- /dev/null
+++ b/doc/elf_rawdata.3
@@ -0,0 +1,97 @@ 
+.TH ELF_RAWDATA 3 2025-06-30 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf_rawdata - Retrieve unprocessed section data from an ELF descriptor.
+
+.SH SYNOPSIS
+.nf
+#include <libelf.h>
+
+.BI "Elf_Data *elf_rawdata(Elf_Scn *" scn ", Elf_Data *" data ");"
+.fi
+
+.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 binary layout in the ELF file, without any
+conversion or translation.
+
+If
+.I data
+is
+.B NULL ,
+the raw data of the section is returned.
+If
+.I data
+is not
+.B 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
+.B NULL .
+
+The data buffer may come directly from the memory-mapped file or may be
+allocated and populated on first access.
+
+.SH PARAMETERS
+.TP
+.I scn
+A section descriptor returned from
+.BR elf_getscn (3)
+or
+.BR elf_nextscn (3) .
+Must not be
+.B NULL .
+
+.TP
+.I data
+Must be
+.B 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,
+.B NULL
+is returned.
+
+.SH SEE ALSO
+.BR elf_getdata (3),
+.BR elf_getscn (3),
+.BR elf_compress (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_rawdata ()
+T}	Thread safety	MT-Safe
+.TE
+
+.SH REPORTING BUGS
+Report bugs to <elfutils-devel@sourceware.org> or https://sourceware.org/bugzilla/.