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

   1 '\" te
   2 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
   3 .\" Copyright 1989 AT&T
   4 .\" 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.
   5 .\"  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
   6 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH ELF_GETIDENT 3ELF "Jun 18, 2009"
   8 .SH NAME
   9 elf_getident, elf_getphdrnum, elf_getshdrnum, elf_getshdrstrndx, elf_getphnum,
  10 elf_getshnum, elf_getshstrndx \- retrieve \fBELF\fR header data
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 cc [ \fIflag\fR ... ] \fIfile\fR ... \fB-lelf\fR [ \fIlibrary\fR ... ]
  15 #include <libelf.h>
  16
  17 \fBchar *\fR\fBelf_getident\fR(\fBElf *\fR\fIelf\fR, \fBsize_t *\fR\fIdst\fR);
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBint\fR \fBelf_getphdrnum\fR(\fBElf *\fR\fIelf\fR, \fBsize_t *\fR\fIdst\fR);
  23 .fi
  24
  25 .LP
  26 .nf
  27 \fBint\fR \fBelf_getshdrnum\fR(\fBElf *\fR\fIelf\fR, \fBsize_t *\fR\fIdst\fR);
  28 .fi
  29
  30 .LP
  31 .nf
  32 \fBint\fR \fBelf_getshdrstrndx\fR(\fBElf *\fR\fIelf\fR, \fBsize_t *\fR\fIdst\fR);
  33 .fi
  34
  35 .SS "Obsolete Interfaces"
  36 .LP
  37 .nf
  38 \fBint\fR \fBelf_getphnum\fR(\fBElf *\fR\fIelf\fR, \fBsize_t *\fR\fIdst\fR);
  39 .fi
  40
  41 .LP
  42 .nf
  43 \fBint\fR \fBelf_getshnum\fR(\fBElf *\fR\fIelf\fR, \fBsize_t *\fR\fIdst\fR);
  44 .fi
  45
  46 .LP
  47 .nf
  48 \fBint\fR \fBelf_getshstrndx\fR(\fBElf *\fR\fIelf\fR, \fBsize_t *\fR\fIdst\fR);
  49 .fi
  50
  51 .SH DESCRIPTION
  52 .sp
  53 .LP
  54 As \fBelf\fR(3ELF) explains, \fBELF\fR provides a framework for various classes
  55 of files, where basic objects might have 32 or 64 bits. To accommodate these
  56 differences, without forcing the larger sizes on smaller machines, the initial
  57 bytes in an \fBELF\fR file hold identification information common to all file
  58 classes. The \fBe_ident\fR of every \fBELF\fR header has \fBEI_NIDENT\fR bytes
  59 with interpretations described in the following table.
  60 .sp
  61
  62 .sp
  63 .TS
  64 l l l
  65 l l l .
  66 \fBe_ident Index\fR     \fBValue\fR     \fBPurpose\fR
  67
  68 \fBEI_MAG0\fR   \fBELFMAG0\fR   File identification
  69 \fBEI_MAG1\fR   \fBELFMAG1\fR
  70 \fBEI_MAG2\fR   \fBELFMAG2\fR
  71 \fBEI_MAG3\fR   \fBELFMAG3\fR
  72
  73 \fBEI_CLASS\fR  \fBELFCLASSNONE\fR      File class
  74         \fBELFCLASS32\fR
  75         \fBELFCLASS64\fR
  76
  77 \fBEI_DATA\fR   \fBELFDATANONE\fR       Data encoding
  78         \fBELFDATA2LSB\fR
  79         \fBELFDATA2MSB\fR
  80
  81 \fBEI_VERSION\fR        \fBEV_CURRENT\fR        File version
  82
  83 7-15    0       Unused, set to zero
  84 .TE
  85
  86 .sp
  87 .LP
  88 Other kinds of files might have identification data, though they would not
  89 conform to \fBe_ident\fR. See \fBelf_kind\fR(3ELF) for information on other
  90 kinds of files.
  91 .sp
  92 .LP
  93 The \fBelf_getident()\fR function returns a pointer to the initial bytes of the
  94 file. If the library recognizes the file, a conversion from the file image to
  95 the memory image can occur. The identification bytes are guaranteed to be
  96 unmodified, though the size of the unmodified area depends on the file type. If
  97 the \fIdst\fR argument is non-null, the library stores the number of
  98 identification bytes in the location to which \fIdst\fR points. If no data are
  99 present, \fIelf\fR is \fINULL\fR, or an error occurs, the return value is a
 100 null pointer, with \fB0\fR stored through \fIdst\fR, if \fIdst\fR is non-null.
 101 .sp
 102 .LP
 103 The \fBelf_getphdrnum()\fR function obtains the number of program headers
 104 recorded in the \fBELF\fR file. The number of sections in a file is typically
 105 recorded in the \fBe_phnum\fR field of the \fBELF\fR header. A file that
 106 requires the \fBELF\fR extended program header records the value \fBPN_XNUM\fR
 107 in the \fBe_phnum\fR field and records the number of sections in the
 108 \fBsh_info\fR field of section header 0. See USAGE. The \fIdst\fR argument
 109 points to the location where the number of sections is stored. If \fIelf\fR is
 110 \fINULL\fR or an error occurs, \fBelf_getphdrnum()\fR returns \fB\(mi1\fR\&.
 111 .sp
 112 .LP
 113 The \fBelf_getshdrnum()\fR function obtains the number of sections recorded in
 114 the \fBELF\fR file. The number of sections in a file is typically recorded in
 115 the \fBe_shnum\fR field of the \fBELF\fR header. A file that requires \fBELF\fR
 116 extended section records the value \fB0\fR in the \fBe_shnum\fR field and
 117 records the number of sections in the \fBsh_size\fR field of section header 0.
 118 See USAGE. The \fIdst\fR argument points to the location where the number of
 119 sections is stored. If a call to \fBelf_newscn\fR(3ELF) that uses the same
 120 \fIelf\fR descriptor is performed, the value obtained by \fBelf_getshnum()\fR
 121 is valid only after a successful call to \fBelf_update\fR(3ELF). If \fIelf\fR
 122 is \fINULL\fR or an error occurs, \fBelf_getshdrnum()\fR returns \fB\(mi1\fR\&.
 123 .sp
 124 .LP
 125 The \fBelf_getshdrstrndx()\fR function obtains the section index of the string
 126 table associated with the section headers in the \fBELF\fR file. The section
 127 header string table index is typically recorded in the \fBe_shstrndx\fR field
 128 of the \fBELF\fR header. A file that requires \fBELF\fR extended section
 129 records the value \fBSHN_XINDEX\fR in the \fBe_shstrndx\fR field and records
 130 the string table index in the \fBsh_link\fR field of section header 0. See
 131 USAGE. The \fIdst\fR argument points to the location where the section header
 132 string table index is stored. If \fIelf\fR is \fINULL\fR or an error occurs,
 133 \fBelf_getshdrstrndx()\fR returns \fB\(mi1\fR\&.
 134 .sp
 135 .LP
 136 The \fBelf_getphnum()\fR, \fBelf_getshnum()\fR, and \fBelf_getshstrndx()\fR
 137 functions behave in a manner similar to \fBelf_getphdrnum()\fR,
 138 \fBelf_getshdrnum()\fR, and \fBelf_getshdrstrndx()\fR, respectively, except
 139 that they return 0 if \fIelf\fR is \fINULL\fR or an error occurs. Because these
 140 return values differ from those used by some other systems, they are therefore
 141 non-portable and their use is discouraged. The \fBelf_getphdrnum()\fR,
 142 \fBelf_getshdrnum()\fR, and \fBelf_getshdrstrndx()\fR functions should be used
 143 instead.
 144 .SH USAGE
 145 .sp
 146 .LP
 147 ELF extended sections allow an ELF file to contain more than \fB0xff00\fR
 148 (\fBSHN_LORESERVE\fR) section. ELF extended program headers allow an ELF file
 149 to contain \fB0xffff\fR (\fBPN_XNUM\fR) or more program headers. See the
 150 \fILinker and Libraries Guide\fR for more information.
 151 .SH RETURN VALUES
 152 .sp
 153 .LP
 154 Upon successful completion, the \fBelf_getident()\fR function returns 1.
 155 Otherwise, it return 0.
 156 .sp
 157 .LP
 158 Upon successful completion, the \fBelf_getphdrnum()\fR, \fBelf_getshdrnum()\fR,
 159 and  \fBelf_getshdrstrndx()\fR  functions return 0. Otherwise, they return -1.
 160 .sp
 161 .LP
 162 Upon successful completion, the \fBelf_getphnum()\fR, \fBelf_getshnum()\fR, and
 163 \fBelf_getshstrndx()\fR  functions return 1. Otherwise, they return 0.
 164 .SH ATTRIBUTES
 165 .sp
 166 .LP
 167 See \fBattributes\fR(5) for descriptions of the following attributes:
 168 .sp
 169
 170 .sp
 171 .TS
 172 box;
 173 c | c
 174 l | l .
 175 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 176 _
 177 Interface Stability     See below.
 178 _
 179 MT-Level        MT-Safe
 180 .TE
 181
 182 .sp
 183 .LP
 184 The \fBelf_getident()\fR, \fBelf_getphdrnum()\fR, \fBelf_getshdrnum()\fR, and
 185 \fBelf_getshdrstrndx()\fR functions are Committed. The \fBelf_getphnum()\fR,
 186 \fBelf_getshnum()\fR, and  \fBelf_getshstrndx()\fR functions are Committed
 187 (Obsolete).
 188 .SH SEE ALSO
 189 .sp
 190 .LP
 191 \fBelf\fR(3ELF), \fBelf32_getehdr\fR(3ELF), \fBelf_begin\fR(3ELF),
 192 \fBelf_kind\fR(3ELF), \fBelf_newscn\fR(3ELF), \fBelf_rawfile\fR(3ELF),
 193 \fBelf_update\fR(3ELF), \fBlibelf\fR(3LIB), \fBattributes\fR(5)
 194 .sp
 195 .LP
 196 \fILinker and Libraries Guide\fR