ELF_RAWFILE(3ELF) ELF Library Functions ELF_RAWFILE(3ELF)
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
The
elf_rawfile() function 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(3ELF)) 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() is a related function, providing access to sections
within a file. See
elf_getdata(3ELF).
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
0 stored through
ptr, if
ptr is non-null.
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Stable |
+--------------------+-----------------+
|MT-Level | MT-Safe |
+--------------------+-----------------+
SEE ALSO
elf(3ELF),
elf32_getehdr(3ELF),
elf_begin(3ELF),
elf_cntl(3ELF),
elf_getdata(3ELF),
elf_getident(3ELF),
elf_kind(3ELF),
libelf(3LIB),
attributes(7)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
elf32_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.
July 11, 2001 ELF_RAWFILE(3ELF)
