share/man/man3elf/elf_getscn.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_GETSCN 3ELF "Jul 11, 2001"
   7 .SH NAME
   8 elf_getscn, elf_ndxscn, elf_newscn, elf_nextscn \- get section information
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 cc [ \fIflag\fR ... ] \fIfile\fR ... \fB-lelf\fR [ \fIlibrary\fR ... ]
  13 #include <libelf.h>
  14
  15 \fBElf_Scn *\fR\fBelf_getscn\fR(\fBElf *\fR\fIelf\fR, \fBsize_t\fR \fIindex\fR);
  16 .fi
  17
  18 .LP
  19 .nf
  20 \fBsize_t\fR \fBelf_ndxscn\fR(\fBElf_Scn *\fR\fIscn\fR);
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fBElf_Scn *\fR\fBelf_newscn\fR(\fBElf *\fR\fIelf\fR);
  26 .fi
  27
  28 .LP
  29 .nf
  30 \fBElf_Scn *\fR\fBelf_nextscn\fR(\fBElf *\fR\fIelf\fR, \fBElf_Scn *\fR\fIscn\fR);
  31 .fi
  32
  33 .SH DESCRIPTION
  34 .sp
  35 .LP
  36 These functions provide indexed and sequential access to the sections
  37 associated with the \fBELF\fR descriptor \fIelf\fR. If the program is building
  38 a new file, it is responsible for creating the file's \fBELF\fR header before
  39 creating sections; see \fBelf32_getehdr\fR(3ELF).
  40 .sp
  41 .LP
  42 The \fBelf_getscn()\fR function returns a section descriptor, given an
  43 \fIindex\fR into the file's section header table. Note that the first ``real''
  44 section has an index of \fB1\fR. Although a program can get a section
  45 descriptor for the section whose \fIindex\fR is \fB0\fR (\fBSHN_UNDEF\fR, the
  46 undefined section), the section has no data and the section header is ``empty''
  47 (though present). If the specified section does not exist, an error occurs, or
  48 \fIelf\fR is \fINULL\fR, \fBelf_getscn()\fR returns a null pointer.
  49 .sp
  50 .LP
  51 The \fBelf_newscn()\fR function creates a new section and appends it to the
  52 list for \fIelf\fR. Because the \fBSHN_UNDEF\fR section is required and not
  53 ``interesting'' to applications, the library creates it automatically. Thus the
  54 first call to \fBelf_newscn()\fR for an \fBELF\fR descriptor with no existing
  55 sections returns a descriptor for section 1. If an error occurs or \fIelf\fR is
  56 \fINULL\fR, \fBelf_newscn()\fR returns a null pointer.
  57 .sp
  58 .LP
  59 After creating a new section descriptor, the program can use
  60 \fBelf32_getshdr()\fR to retrieve the newly created, ``clean'' section header.
  61 The new section descriptor will have no associated data (see
  62 \fBelf_getdata\fR(3ELF)). When creating a new section in this way, the library
  63 updates the \fBe_shnum\fR member of the \fBELF\fR header and sets the
  64 \fBELF_F_DIRTY\fR bit for the section (see \fBelf_flagdata\fR(3ELF)). If the
  65 program is building a new file, it is responsible for creating the file's
  66 \fBELF\fR header (see \fBelf32_getehdr\fR(3ELF)) before creating new sections.
  67 .sp
  68 .LP
  69 The \fBelf_nextscn()\fR function takes an existing section descriptor,
  70 \fIscn\fR, and returns a section descriptor for the next higher section. One
  71 may use a null \fIscn\fR to obtain a section descriptor for the section whose
  72 index is \fB1\fR (skipping the section whose index is \fBSHN_UNDEF\fR). If no
  73 further sections are present or an error occurs, \fBelf_nextscn()\fR returns a
  74 null pointer.
  75 .sp
  76 .LP
  77 The \fBelf_ndxscn()\fR function takes an existing section descriptor,
  78 \fIscn\fR, and returns its section table index. If \fIscn\fR is null or an
  79 error occurs, \fBelf_ndxscn()\fR returns \fBSHN_UNDEF\fR.
  80 .SH EXAMPLES
  81 .LP
  82 \fBExample 1 \fRA sample of calling \fBelf_getscn()\fR function.
  83 .sp
  84 .LP
  85 An example of sequential access appears below. Each pass through the loop
  86 processes the next section in the file; the loop terminates when all sections
  87 have been processed.
  88
  89 .sp
  90 .in +2
  91 .nf
  92 \fBscn = 0;
  93 while ((scn = elf_nextscn(elf, scn)) != 0)
  94 {
  95         /* process section */
  96 }\fR
  97 .fi
  98 .in -2
  99
 100 .SH ATTRIBUTES
 101 .sp
 102 .LP
 103 See \fBattributes\fR(5) for descriptions of the following attributes:
 104 .sp
 105
 106 .sp
 107 .TS
 108 box;
 109 c | c
 110 l | l .
 111 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 112 _
 113 Interface Stability     Stable
 114 _
 115 MT-Level        MT-Safe
 116 .TE
 117
 118 .SH SEE ALSO
 119 .sp
 120 .LP
 121 \fBelf\fR(3ELF), \fBelf32_getehdr\fR(3ELF), \fBelf32_getshdr\fR(3ELF),
 122 \fBelf_begin\fR(3ELF), \fBelf_flagdata\fR(3ELF), \fBelf_getdata\fR(3ELF),
 123 \fBlibelf\fR(3LIB), \fBattributes\fR(5)