elf_rawfile(3E)

NAME
     elf_rawfile - Retrieves 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);

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 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.  See elf_cntl(3E) for details.  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 is a related function, providing access to sections within
     a file.  See elf_getdata(3E) for details.

     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.

NOTES
     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.

     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 application 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 that 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.

SEE ALSO
     elf(3E), elf_begin(3E), elf_cntl(3E), elf_getdata(3E),
     elf_getehdr(3E), elf_getident(3E), elf_kind(3E)