usr/src/man/man3elf/elf_rawfile.3elf

   1 '\" te
   2 .\"  Copyright 1989 AT&T  Copyright (c) 2001, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH ELF_RAWFILE 3ELF "Jul 11, 2001"
   7 .SH NAME
   8 elf_rawfile \- retrieve uninterpreted file contents
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 cc [ \fIflag\fR... ] \fIfile\fR ... \fB-lelf\fR [ \fIlibrary\fR ... ]
  13 #include <libelf.h>
  14
  15 \fBchar *\fR\fBelf_rawfile\fR(\fBElf *\fR\fIelf\fR, \fBsize_t *\fR\fIptr\fR);
  16 .fi
  17
  18 .SH DESCRIPTION
  19 .sp
  20 .LP
  21 The \fBelf_rawfile()\fR function returns a pointer to an uninterpreted byte
  22 image of the file. This function should be used only to retrieve a file being
  23 read. For example, a program might use \fBelf_rawfile()\fR to retrieve the
  24 bytes for an archive member.
  25 .sp
  26 .LP
  27 A program may not close or disable (see \fBelf_cntl\fR(3ELF)) the file
  28 descriptor associated with \fIelf\fR before the initial call to
  29 \fBelf_rawfile()\fR \fB,\fR because \fBelf_rawfile()\fR might have to read the
  30 data from the file if it does not already have the original bytes in memory.
  31 Generally, this function is more efficient for unknown file types than for
  32 object files. The library implicitly translates object files in memory, while
  33 it leaves unknown files unmodified. Thus, asking for the uninterpreted image of
  34 an object file may create a duplicate copy in memory.
  35 .sp
  36 .LP
  37 \fBelf_rawdata()\fR is a related function, providing access to sections within
  38 a file. See \fBelf_getdata\fR(3ELF).
  39 .sp
  40 .LP
  41 If \fIptr\fR is non-null, the library also stores the file's size, in bytes, in
  42 the location to which \fIptr\fR points. If no data are present, \fIelf\fR is
  43 null, or an error occurs, the return value is a null pointer, with \fB0\fR
  44 stored through \fIptr\fR, if  \fIptr\fR is non-null.
  45 .SH ATTRIBUTES
  46 .sp
  47 .LP
  48 See \fBattributes\fR(5) for descriptions of the following attributes:
  49 .sp
  50
  51 .sp
  52 .TS
  53 box;
  54 c | c
  55 l | l .
  56 ATTRIBUTE TYPE  ATTRIBUTE VALUE
  57 _
  58 Interface Stability     Stable
  59 _
  60 MT-Level        MT-Safe
  61 .TE
  62
  63 .SH SEE ALSO
  64 .sp
  65 .LP
  66 \fBelf\fR(3ELF), \fBelf32_getehdr\fR(3ELF), \fBelf_begin\fR(3ELF),
  67 \fBelf_cntl\fR(3ELF), \fBelf_getdata\fR(3ELF), \fBelf_getident\fR(3ELF),
  68 \fBelf_kind\fR(3ELF), \fBlibelf\fR(3LIB), \fBattributes\fR(5)
  69 .SH NOTES
  70 .sp
  71 .LP
  72 A program that uses \fBelf_rawfile()\fR and that also interprets the same file
  73 as an object file potentially has two copies of the bytes in memory. If such a
  74 program requests the raw image first, before it asks for translated information
  75 (through such functions as \fBelf32_getehdr()\fR, \fBelf_getdata()\fR, and so
  76 on), the library ``freezes'' its original memory copy for the raw image. It
  77 then uses this frozen copy as the source for creating translated objects,
  78 without reading the file again. Consequently, the application should view the
  79 raw file image returned by \fBelf_rawfile()\fR as a read-only buffer, unless it
  80 wants to alter its own view of data subsequently translated. In any case, the
  81 application may alter the translated objects without changing bytes visible in
  82 the raw image.
  83 .sp
  84 .LP
  85 Multiple calls to \fBelf_rawfile()\fR with the same \fBELF\fR descriptor return
  86 the same value; the library does not create duplicate copies of the file.