Signed-off-by: Aaron Merey <ame...@redhat.com>
---
v2: Remove mention of implementation details. Mention that conversion
to native byte order and direct access alignment resembles elf_getdata.
Mention elf_errmsg.
On Mon, Jul 7, 2025 at 1:26 PM Mark Wielaard <m...@klomp.org> wrote:
>
> Nice overview of ELF data types. But might there be a better place for
> this? I would assume elf_data, but that man page is currently very bare
> bones.
When I update the bare bones man pages including elf_data I'll move
the Elf_Type description there.
> Speaking of thread safety...
> This should be MT-Safe and documented that way.
>
> But is it really?
> The code takes a read lock on elf->lock. Checks whether it can find an
> existing Elf_Data_Chunk. If yes, it returns that one. Which seems fine.
> But if not it inserts the dummy chunk without actually data,
> allocates/creates the data, drops the rdlock (!), takes a write lock
> and overwrites the dummy chunk with the real data, drops the lock again
> and returns the data.
>
> What if at (!) another call gets the read lock first before the current
> thread can (re)take the write lock? That other thread could find the
> existing dummy key already in the cache and return the dummy data?
I've posted a patch that fixes this race condition.
doc/Makefile.am | 1 +
doc/elf_getdata_rawchunk.3 | 140 +++++++++++++++++++++++++++++++++++++
2 files changed, 141 insertions(+)
create mode 100644 doc/elf_getdata_rawchunk.3
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 791a68da..fbe69980 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -67,6 +67,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \
elf_getarsym.3 \
elf_getbase.3 \
elf_getdata.3 \
+ elf_getdata_rawchunk.3 \
elf_getscn.3 \
elf_hash.3 \
elf_kind.3 \
diff --git a/doc/elf_getdata_rawchunk.3 b/doc/elf_getdata_rawchunk.3
new file mode 100644
index 00000000..9660b1f1
--- /dev/null
+++ b/doc/elf_getdata_rawchunk.3
@@ -0,0 +1,140 @@
+.TH ELF_GETDATA_RAWCHUNK 3 2025-06-30 "Libelf" "Libelf Programmer's Manual"
+
+.SH NAME
+elf_getdata_rawchunk \- create a raw data descriptor from a file offset
+
+.SH SYNOPSIS
+.nf
+#include <libelf.h>
+
+.B Elf_Data * elf_getdata_rawchunk("Elf *elf", "int64_t offset", "size_t
size", "Elf_Type type");
+.fi
+
+.SH DESCRIPTION
+The
+.BR elf_getdata_rawchunk ()
+function returns an
+.B Elf_Data
+descriptor that refers to a raw region of the ELF file, starting at the
+given file
+.I offset
+and spanning
+.I size
+bytes. This is used to access arbitrary byte ranges in the ELF file that may
+not correspond to any section or segment.
+
+The returned
+.B Elf_Data
+.I d_buf
+will be properly aligned for the requested
+.IR type .
+
+If the file’s byte order matches the host, and alignment permits, the raw data
is
+returned as-is. If the file’s byte order differs, the buffer is converted into
native
+byte order and aligned for direct access. This behaves like
+.BR elf_getdata (),
+and not
+.BR elf_rawdata ().
+The contents of the return value's
+.I d_buf
+are a decoded representation.
+
+The returned data is not associated with any section or update mechanism. It
will not
+be included in any output written by
+.BR elf_update (3).
+It is also owned by libelf and is valid until
+.BR elf_end ()
+is called on
+.IR elf .
+
+.SH PARAMETERS
+.TP
+.I elf
+A pointer to an
+.B Elf
+descriptor representing the ELF file.
+
+.TP
+.I offset
+The starting file offset in bytes. This must lie within the bounds of the file.
+
+.TP
+.I size
+The number of bytes to include in the data chunk, starting at
+.IR offset .
+
+.TP
+.I type
+An
+.B Elf_Type
+enumeration value indicating the intended interpretation of the data. Values
include:
+
+.RS
+.TP
+.B ELF_T_BYTE
+Raw bytes.
+.TP
+.B ELF_T_ADDR, ELF_T_OFF, ELF_T_HALF, ELF_T_WORD, ELF_T_XWORD, ELF_T_SWORD,
ELF_T_SXWORD
+Integer and pointer types.
+.TP
+.B ELF_T_EHDR, ELF_T_SHDR, ELF_T_PHDR
+ELF file, section, and program headers.
+.TP
+.B ELF_T_SYM, ELF_T_DYN, ELF_T_REL, ELF_T_RELA, ELF_T_RELR
+Symbols and relocations.
+.TP
+.B ELF_T_NHDR, ELF_T_CHDR, ELF_T_NHDR8
+ELF note headers and compressed data headers.
+.TP
+.B ELF_T_VDEF, ELF_T_VDAUX, ELF_T_VNEED, ELF_T_VNAUX
+Versioning structures.
+.TP
+.B ELF_T_SYMINFO, ELF_T_MOVE, ELF_T_LIB
+Other ELF metadata.
+.TP
+.B ELF_T_GNUHASH
+GNU-style hash table.
+.TP
+.B ELF_T_AUXV
+Auxiliary vectors.
+.RE
+
+.SH RETURN VALUE
+Returns a pointer to an
+.B Elf_Data
+descriptor on success.
+
+Returns NULL if any arguments are invalid, or if memory allocation or file
reading
+fails. An error code is set which can be retrieved with
+.BR elf_errmsg ().
+The result is cached and shared between repeated calls using the same
arguments.
+
+.SH SEE ALSO
+.BR elf (3),
+.BR elf_errmsg (3),
+.BR elf_getdata (3),
+.BR elf_getscn (3),
+.BR elf_rawdata (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_getdata_rawchunk ()
+T} Thread safety MT-Safe
+.TE
+
+.SH REPORTING BUGS
+Report bugs to <elfutils-devel@sourceware.org> or
https://sourceware.org/bugzilla/.
+
+.SH HISTORY
+.B elf_getdata_rawchunk
+first appeared in elfutils 0.130. This function is a elfutils libelf
extension and
+may not be available in other libelf implementations.
--
2.50.1
