elf_rawfile.3e (2010 09)

e
elf_rawfile(3E) elf_rawfile(3E)
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 ini-
tial 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 dupli-
cate 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.
SEE ALSO
elf(3E), elf_begin(3E), elf_cntl(3E), elf_getdata(3E), elf_getehdr(3E), elf_getident(3E), elf_kind(3E).
HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1