ELFRAWFILE(3E)                                                ELFRAWFILE(3E)



NAME
     elfrawfile - retrieve uninterpreted file contents

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

     #include <libelf.h>

     char *elfrawfile(Elf *elf, sizet *ptr);

     #define LIBELFXTND64
     char *elfrawfile(Elf *elf, Elf64Xword *ptr);

DESCRIPTION
     elfrawfile 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 elfrawfile to retrieve the bytes for an
     archive member.

     A program may not close or disable [see elfcntl(3E)] the file descriptor
     associated with elf before the initial call to elfrawfile, because
     elfrawfile 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.

     elfrawdata [see elfgetdata(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), elfbegin(3E), elfcntl(3E), elfgetdata(3E), elfgetehdr(3E),
     elfgetident(3E), elfkind(3E).

NOTE
     A program that uses elfrawfile 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 elfgetehdr,
     elfgetdata, 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
     elfrawfile 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

ELFRAWFILE(3E)                                                ELFRAWFILE(3E)



     Multiple calls to elfrawfile with the same ELF descriptor return the
     same value; the library does not create duplicate copies of the file.

     The use of a sizet in a 32-bit compile with elfrawfile 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 LIBELFXTND64 is
     defined at compile-time, then instead of linking with -lelf, link with
     -lelf_xtnd.  There is a corresponding -ldwarfxtnd.  It is essential that
     a 32-bit application compiled with _LIBELF_XTND_64 be *entirely* compiled
     with LIBELFXTND64 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