share/man/man3elf/elf_flagdata.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_FLAGDATA 3ELF "Jul 11, 2001"
   7 .SH NAME
   8 elf_flagdata, elf_flagehdr, elf_flagelf, elf_flagphdr, elf_flagscn,
   9 elf_flagshdr \- manipulate flags
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 cc [ \fIflag\fR ... ] \fIfile\fR ... \fB-lelf\fR [ \fIlibrary\fR ... ]
  14 #include <libelf.h>
  15
  16 \fBunsigned\fR \fBelf_flagdata\fR(\fBElf_Data *\fR\fIdata\fR, \fBElf_Cmd\fR \fIcmd\fR, \fBunsigned\fR \fIflags\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBunsigned\fR \fBelf_flagehdr\fR(\fBElf *\fR\fIelf\fR, \fBElf_Cmd\fR \fIcmd\fR, \fBunsigned\fR \fIflags\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBunsigned\fR \fBelf_flagelf\fR(\fBElf *\fR\fIelf\fR, \fBElf_Cmd\fR \fIcmd\fR, \fBunsigned\fR \fIflags\fR);
  27 .fi
  28
  29 .LP
  30 .nf
  31 \fBunsigned\fR \fBelf_flagphdr\fR(\fBElf *\fR\fIelf\fR, \fBElf_Cmd\fR \fIcmd\fR, \fBunsigned\fR \fIflags\fR);
  32 .fi
  33
  34 .LP
  35 .nf
  36 \fBunsigned\fR \fBelf_flagscn\fR(\fBElf_Scn *\fR\fIscn\fR, \fBElf_Cmd\fR \fIcmd\fR, \fBunsigned\fR \fIflags\fR);
  37 .fi
  38
  39 .LP
  40 .nf
  41 \fBunsigned\fR \fBelf_flagshdr\fR(\fBElf_Scn *\fR\fIscn\fR, \fBElf_Cmd\fR \fIcmd\fR, \fBunsigned\fR \fIflags\fR);
  42 .fi
  43
  44 .SH DESCRIPTION
  45 .sp
  46 .LP
  47 These functions manipulate the flags associated with various structures of an
  48 \fBELF\fR file. Given an \fBELF\fR descriptor (\fIelf\fR), a data descriptor
  49 (\fIdata\fR), or a section descriptor (\fIscn\fR), the functions may set or
  50 clear the associated status bits, returning the updated bits. A null descriptor
  51 is allowed, to simplify error handling; all functions return \fB0\fR for this
  52 degenerate case.
  53 .sp
  54 .LP
  55 \fIcmd\fR may have the following values:
  56 .sp
  57 .ne 2
  58 .na
  59 \fB\fBELF_C_CLR\fR\fR
  60 .ad
  61 .RS 13n
  62 The functions clear the bits that are asserted in \fIflags\fR. Only the
  63 non-zero bits in \fIflags\fR are cleared; zero bits do not change the status of
  64 the descriptor.
  65 .RE
  66
  67 .sp
  68 .ne 2
  69 .na
  70 \fB\fBELF_C_SET\fR\fR
  71 .ad
  72 .RS 13n
  73 The functions set the bits that are asserted in \fIflags\fR. Only the non-zero
  74 bits in \fIflags\fR are set; zero bits do not change the status of the
  75 descriptor.
  76 .RE
  77
  78 .sp
  79 .LP
  80 Descriptions of the defined \fIflags\fR bits appear below:
  81 .sp
  82 .ne 2
  83 .na
  84 \fB\fBELF_F_DIRTY\fR\fR
  85 .ad
  86 .RS 16n
  87 When the program intends to write an \fBELF\fR file, this flag asserts the
  88 associated information needs to be written to the file. Thus, for example, a
  89 program that wished to update the \fBELF\fR header of an existing file would
  90 call \fBelf_flagehdr()\fR with this bit set in \fIflags\fR and \fIcmd\fR equal
  91 to \fBELF_C_SET\fR. A later call to \fBelf_update()\fR would write the marked
  92 header to the file.
  93 .RE
  94
  95 .sp
  96 .ne 2
  97 .na
  98 \fB\fBELF_F_LAYOUT\fR\fR
  99 .ad
 100 .RS 16n
 101 Normally, the library decides how to arrange an output file. That is, it
 102 automatically decides where to place sections, how to align them in the file,
 103 etc. If this bit is set for an \fBELF\fR descriptor, the program assumes
 104 responsibility for determining all file positions. This bit is meaningful only
 105 for \fBelf_flagelf()\fR and applies to the entire file associated with the
 106 descriptor.
 107 .RE
 108
 109 .sp
 110 .LP
 111 When a flag bit is set for an item, it affects all the subitems as well. Thus,
 112 for example, if the program sets the \fBELF_F_DIRTY\fR bit with
 113 \fBelf_flagelf()\fR, the entire logical file is ``dirty.''
 114 .SH EXAMPLES
 115 .LP
 116 \fBExample 1 \fRA sample display of calling the \fBelf_flagdata()\fR function.
 117 .sp
 118 .LP
 119 The following fragment shows how one might mark the \fBELF\fR header to be
 120 written to the output file:
 121
 122 .sp
 123 .in +2
 124 .nf
 125 \fB/* dirty ehdr \|.\|.\|. */
 126 ehdr = elf32_getehdr(elf);
 127 elf_flagehdr(elf, ELF_C_SET, ELF_F_DIRTY);\fR
 128 .fi
 129 .in -2
 130
 131 .SH ATTRIBUTES
 132 .sp
 133 .LP
 134 See \fBattributes\fR(5) for descriptions of the following attributes:
 135 .sp
 136
 137 .sp
 138 .TS
 139 box;
 140 c | c
 141 l | l .
 142 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 143 _
 144 Interface Stability     Stable
 145 _
 146 MT-Level        MT-Safe
 147 .TE
 148
 149 .SH SEE ALSO
 150 .sp
 151 .LP
 152 \fBelf\fR(3ELF), \fBelf32_getehdr\fR(3ELF), \fBelf_getdata\fR(3ELF),
 153 \fBelf_update\fR(3ELF), \fBattributes\fR(5)