ELF_RAWFILE(3E)						       ELF_RAWFILE(3E)

NAME    [Toc]    [Back]

     elf_rawfile - retrieve uninterpreted file contents

SYNOPSIS    [Toc]    [Back]

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

     #include <libelf.h>

     char *elf_rawfile(Elf *elf, size_t	*ptr);
     #define _LIBELF_XTND_64
     char *elf_rawfile(Elf *elf, Elf64_Xword *ptr);

DESCRIPTION    [Toc]    [Back]

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

SEE ALSO    [Toc]    [Back]

     elf(3E), elf_begin(3E), elf_cntl(3E), elf_getdata(3E), elf_getehdr(3E),
     elf_getident(3E), elf_kind(3E).

NOTE    [Toc]    [Back]

     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.




									Page 1






ELF_RAWFILE(3E)						       ELF_RAWFILE(3E)



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

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


									PPPPaaaaggggeeee 2222