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 is
present,
elf
is null, or an error occurs, the return value is
a null pointer, with zero optionally stored through
ptr.
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.
Printable version
