xref: /illumos-gate/usr/src/man/man3elf/elf_rawfile.3elf (revision 0ccfe5834c3b867c1b6c273cae02ec8922bc0fd2)
te
Copyright 1989 AT&T Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
ELF_RAWFILE 3ELF "Jul 11, 2001"
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.