ELF_RAWFILE(3E)ELF_RAWFILE(3E)NAMEelf_rawfile - retrieve uninterpreted file contents
SYNOPSIS
cc [flag ...] file ... -lelf [library ...]
#include <libelf.h>
char *elf_rawfile(Elf *elf, size_t *ptr);
#define _LIBELF_XTND_64
char *elf_rawfile(Elf *elf, Elf64_Xword *ptr);
DESCRIPTIONelf_rawfile returns a pointer to an uninterpreted byte image of the file.
This function should be used only to retrieve a file being read. For
example, a program might use elf_rawfile to retrieve the bytes for an
archive member.
A program may not close or disable [see elf_cntl(3E)] the file descriptor
associated with elf before the initial call to elf_rawfile, because
elf_rawfile might have to read the data from the file if it does not
already have the original bytes in memory. Generally, this function is
more efficient for unknown file types than for object files. The library
implicitly translates object files in memory, while it leaves unknown
files unmodified. Thus asking for the uninterpreted image of an object
file may create a duplicate copy in memory.
elf_rawdata [see elf_getdata(3E)] is a related function, providing access
to sections within a file.
If ptr is non-null, the library also stores the file's size, in bytes, in
the location to which ptr points. If no data are present, elf is null,
or an error occurs, the return value is a null pointer, with zero
optionally stored through ptr.
SEE ALSOelf(3E), elf_begin(3E), elf_cntl(3E), elf_getdata(3E), elf_getehdr(3E),
elf_getident(3E), elf_kind(3E).
NOTE
A program that uses elf_rawfile and that also interprets the same file as
an object file potentially has two copies of the bytes in memory. If
such a program requests the raw image first, before it asks for
translated information (through such functions as elf_getehdr,
elf_getdata, and so on), the library ``freezes'' its original memory copy
for the raw image. It then uses this frozen copy as the source for
creating translated objects, without reading the file again.
Consequently, the application should view the raw file image returned by
elf_rawfile as a read-only buffer, unless it wants to alter its own view
of data subsequently translated. In any case, the application may alter
the translated objects without changing bytes visible in the raw image.
Page 1
ELF_RAWFILE(3E)ELF_RAWFILE(3E)
Multiple calls to elf_rawfile with the same ELF descriptor return the
same value; the library does not create duplicate copies of the file.
The use of a size_t in a 32-bit compile with elf_rawfile is unfortunate,
since that makes it impossible to deal with certain object files. If,
when the 32-bit app is compiled, _LIBELF_XTND_64 is defined, then the
function interface changes to have 64-bit fields. If _LIBELF_XTND_64 is
defined at compile-time, then instead of linking with -lelf, link with
-lelf_xtnd. There is a corresponding -ldwarf_xtnd. It is essential that
a 32-bit application compiled with _LIBELF_XTND_64 be *entirely* compiled
with _LIBELF_XTND_64 defined.
Applications which are built as 64-bit applications can ignore
_LIBELF_XTND_64: it has no effect on them and 64-bit applications always
link with -lelf never with -lelf_xtnd.
Page 2
