Signed-off-by: Aaron Merey <ame...@redhat.com> --- doc/Makefile.am | 1 + doc/elf_getdata_rawchunk.3 | 133 +++++++++++++++++++++++++++++++++++++ 2 files changed, 134 insertions(+) create mode 100644 doc/elf_getdata_rawchunk.3
diff --git a/doc/Makefile.am b/doc/Makefile.am index 3b63dc38..8afda0bd 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -66,6 +66,7 @@ notrans_dist_man3_MANS= elf32_checksum.3 \ elf_flagshdr.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..3b7f644f --- /dev/null +++ b/doc/elf_getdata_rawchunk.3 @@ -0,0 +1,133 @@ +.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. + +If a descriptor for the same offset, size, and type has previously been requested, +the cached result is returned. Otherwise, the data is loaded and prepared according +to the conditions below. + +If the ELF descriptor is backed by a memory-mapped file and the file offset yields +a pointer suitably aligned for the given +.I type , +the buffer is returned as a direct pointer into the mapped file. If alignment +constraints are not met, or if the file is not memory-mapped, a copy of the data is +allocated and returned instead. The returned buffer is always read-only and must not +be modified. + +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. + +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). + +.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. The result is cached and shared between repeated calls using the same arguments. + +.SH SEE ALSO +.BR elf (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.49.0