share/man/man3elf/elf_update.3elf

   1 '\" te
   2 .\"  Copyright 1989 AT&T  Copyright (c) 1996, 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_UPDATE 3ELF "Jul 11, 2001"
   7 .SH NAME
   8 elf_update \- update an ELF descriptor
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 cc [ \fIflag\fR ... ] \fIfile\fR ... \fB-lelf\fR [ \fIlibrary\fR ... ]
  13 #include <libelf.h>
  14
  15 \fBoff_t\fR \fBelf_update\fR(\fBElf *\fR\fIelf\fR, \fBElf_Cmd\fR \fIcmd\fR);
  16 .fi
  17
  18 .SH DESCRIPTION
  19 .sp
  20 .LP
  21 The \fBelf_update()\fR function causes the library to examine the information
  22 associated with an \fBELF\fR descriptor, \fIelf\fR, and to recalculate the
  23 structural data needed to generate the file's image.
  24 .sp
  25 .LP
  26 The \fIcmd\fR argument can have the following values:
  27 .sp
  28 .ne 2
  29 .na
  30 \fB\fBELF_C_NULL\fR\fR
  31 .ad
  32 .RS 15n
  33 This value tells \fBelf_update()\fR to recalculate various values, updating
  34 only the \fBELF\fR descriptor's memory structures. Any modified structures are
  35 flagged with the \fBELF_F_DIRTY\fR bit. A program thus can update the
  36 structural information and then reexamine them without changing the file
  37 associated with the \fBELF\fR descriptor. Because this does not change the
  38 file, the \fBELF\fR descriptor may allow reading, writing, or both reading and
  39 writing (see  \fBelf_begin\fR(3ELF)).
  40 .RE
  41
  42 .sp
  43 .ne 2
  44 .na
  45 \fB\fBELF_C_WRITE\fR\fR
  46 .ad
  47 .RS 15n
  48 If \fIcmd\fR has this value, \fBelf_update()\fR duplicates its \fBELF_C_NULL\fR
  49 actions and also writes any ``dirty'' information associated with the \fBELF\fR
  50 descriptor to the file. That is, when a program has used
  51 \fBelf_getdata\fR(3ELF) or the \fBelf_flagdata\fR(3ELF) facilities to supply
  52 new (or update existing) information for an \fBELF\fR descriptor, those data
  53 will be examined, coordinated, translated if necessary (see
  54 \fBelf32_xlatetof\fR(3ELF)), and written to the file. When portions of the file
  55 are written, any \fBELF_F_DIRTY\fR bits are reset, indicating those items no
  56 longer need to be written to the file (see \fBelf_flagdata\fR(3ELF)). The
  57 sections' data are written in the order of their section header entries, and
  58 the section header table is written to the end of the file. When the \fBELF\fR
  59 descriptor was created with \fBelf_begin()\fR, it must have allowed writing the
  60 file. That is, the \fBelf_begin()\fR command must have been either
  61 \fBELF_C_RDWR\fR or \fBELF_C_WRITE\fR.
  62 .RE
  63
  64 .sp
  65 .LP
  66 If \fBelf_update()\fR succeeds, it returns the total size of the file image
  67 (not the memory image), in bytes. Otherwise an error occurred, and the function
  68 returns \fB\(mi1\fR\&.
  69 .sp
  70 .LP
  71 When updating the internal structures, \fBelf_update()\fR sets some members
  72 itself. Members listed below are the application's responsibility and retain
  73 the values given by the program.
  74 .sp
  75 .LP
  76 The following table shows ELF Header members:
  77 .sp
  78
  79 .sp
  80 .TS
  81 l l
  82 l l .
  83 Member  Notes
  84
  85 e_ident[EI_DATA]        Library controls other \fBe_ident\fR values
  86 e_type
  87 e_machine
  88 e_version
  89 e_entry
  90 e_phoff Only when \fBELF_F_LAYOUT\fR asserted
  91 e_shoff Only when \fBELF_F_LAYOUT\fR asserted
  92 e_flags
  93 e_shstrndx
  94 .TE
  95
  96 .sp
  97 .LP
  98 The following table shows the Program Header members:
  99 .sp
 100
 101 .sp
 102 .TS
 103 l l
 104 l l .
 105 Member  Notes
 106
 107 p_type  The application controls all
 108 p_offset        program header entries
 109 p_vaddr
 110 p_paddr
 111 p_filesz
 112 p_memsz
 113 p_flags
 114 p_align
 115 .TE
 116
 117 .sp
 118 .LP
 119 The following table shows the Section Header members:
 120 .sp
 121
 122 .sp
 123 .TS
 124 l l
 125 l l .
 126 Member  Notes
 127
 128 sh_name
 129 sh_type
 130 sh_flags
 131 sh_addr
 132 sh_offset       Only when \fBELF_F_LAYOUT\fR asserted
 133 sh_size Only when \fBELF_F_LAYOUT\fR asserted
 134 sh_link
 135 sh_info
 136 sh_addralign    Only when \fBELF_F_LAYOUT\fR asserted
 137 sh_entsize
 138 .TE
 139
 140 .sp
 141 .LP
 142 The following table shows the Data Descriptor members:
 143 .sp
 144
 145 .sp
 146 .TS
 147 l l
 148 l l .
 149 Member  Notes
 150
 151 d_buf
 152 d_type
 153 d_size
 154 d_off   Only when \fBELF_F_LAYOUT\fR asserted
 155 d_align
 156 d_version
 157 .TE
 158
 159 .sp
 160 .LP
 161 Note that the program is responsible for two particularly important members
 162 (among others) in the \fBELF\fR header. The \fBe_version\fR member controls the
 163 version of data structures written to the file. If the version is
 164 \fBEV_NONE\fR, the library uses its own internal version. The
 165 \fBe_ident[EI_DATA]\fR entry controls the data encoding used in the file. As a
 166 special case, the value may be \fBELFDATANONE\fR to request the native data
 167 encoding for the host machine. An error occurs in this case if the native
 168 encoding doesn't match a file encoding known by the library.
 169 .sp
 170 .LP
 171 Further note that the program is responsible for the \fBsh_entsize\fR section
 172 header member. Although the library sets it for sections with known types, it
 173 cannot reliably know the correct value for all sections. Consequently, the
 174 library relies on the program to provide the values for unknown section types.
 175 If the entry size is unknown or not applicable, the value should be set to
 176 \fB0\fR.
 177 .sp
 178 .LP
 179 When deciding how to build the output file, \fBelf_update()\fR obeys the
 180 alignments of individual data buffers to create output sections. A section's
 181 most strictly aligned data buffer controls the section's alignment. The library
 182 also inserts padding between buffers, as necessary, to ensure the proper
 183 alignment of each buffer.
 184 .SH ATTRIBUTES
 185 .sp
 186 .LP
 187 See \fBattributes\fR(5) for descriptions of the following attributes:
 188 .sp
 189
 190 .sp
 191 .TS
 192 box;
 193 c | c
 194 l | l .
 195 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 196 _
 197 Interface Stability     Stable
 198 _
 199 MT-Level        MT-Safe
 200 .TE
 201
 202 .SH SEE ALSO
 203 .sp
 204 .LP
 205 \fBelf\fR(3ELF), \fBelf32_fsize\fR(3ELF), \fBelf32_getehdr\fR(3ELF),
 206 \fBelf32_getshdr\fR(3ELF), \fBelf32_xlatetof\fR(3ELF), \fBelf_begin\fR(3ELF),
 207 \fBelf_flagdata\fR(3ELF), \fBelf_getdata\fR(3ELF), \fBlibelf\fR(3LIB),
 208 \fBattributes\fR(5)
 209 .SH NOTES
 210 .sp
 211 .LP
 212 As mentioned above, the \fBELF_C_WRITE\fR command translates data as necessary,
 213 before writing them to the file. This translation is \fInot\fR always
 214 transparent to the application program. If a program has obtained pointers to
 215 data associated with a file (for example, see \fBelf32_getehdr\fR(3ELF) and
 216 \fBelf_getdata\fR(3ELF)), the program should reestablish the pointers after
 217 calling \fBelf_update()\fR.