NAME

elf_rawfile - retrieve uninterpreted file contents

SYNOPSIS

cc [flag ...] file ...  -lelf [library ...]

#include <libelf.h>

char *elf_rawfile(Elf *elf, size_t *ptr);

DESCRIPTION

elf_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 ALSO

elf(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.  Multiple calls to elf_rawfile with the same ELF
descriptor return the same value; the library does not
create duplicate copies of the file.