elf_rawfile(3E)           UNIX System V(ELF Library)            elf_rawfile(3E)


NAME
      elfrawfile - retrieve uninterpreted file contents

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

      #include <libelf.h>
      char *elfrawfile(Elf *elf, sizet *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.

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



10/89                                                                    Page 1