'\" te
.\"  Copyright 1989 AT&T  Copyright (c) 1996, Sun Microsystems, Inc.  All Rights Reserved
.\" 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.  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 the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH ELF_FLAGDATA 3ELF "Jul 11, 2001"
.SH NAME
elf_flagdata, elf_flagehdr, elf_flagelf, elf_flagphdr, elf_flagscn,
elf_flagshdr \- manipulate flags
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR ... ] \fIfile\fR ... \fB-lelf\fR [ \fIlibrary\fR ... ]
#include <libelf.h>

\fBunsigned\fR \fBelf_flagdata\fR(\fBElf_Data *\fR\fIdata\fR, \fBElf_Cmd\fR \fIcmd\fR, \fBunsigned\fR \fIflags\fR);
.fi

.LP
.nf
\fBunsigned\fR \fBelf_flagehdr\fR(\fBElf *\fR\fIelf\fR, \fBElf_Cmd\fR \fIcmd\fR, \fBunsigned\fR \fIflags\fR);
.fi

.LP
.nf
\fBunsigned\fR \fBelf_flagelf\fR(\fBElf *\fR\fIelf\fR, \fBElf_Cmd\fR \fIcmd\fR, \fBunsigned\fR \fIflags\fR);
.fi

.LP
.nf
\fBunsigned\fR \fBelf_flagphdr\fR(\fBElf *\fR\fIelf\fR, \fBElf_Cmd\fR \fIcmd\fR, \fBunsigned\fR \fIflags\fR);
.fi

.LP
.nf
\fBunsigned\fR \fBelf_flagscn\fR(\fBElf_Scn *\fR\fIscn\fR, \fBElf_Cmd\fR \fIcmd\fR, \fBunsigned\fR \fIflags\fR);
.fi

.LP
.nf
\fBunsigned\fR \fBelf_flagshdr\fR(\fBElf_Scn *\fR\fIscn\fR, \fBElf_Cmd\fR \fIcmd\fR, \fBunsigned\fR \fIflags\fR);
.fi

.SH DESCRIPTION
.sp
.LP
These functions manipulate the flags associated with various structures of an
\fBELF\fR file. Given an \fBELF\fR descriptor (\fIelf\fR), a data descriptor
(\fIdata\fR), or a section descriptor (\fIscn\fR), the functions may set or
clear the associated status bits, returning the updated bits. A null descriptor
is allowed, to simplify error handling; all functions return \fB0\fR for this
degenerate case.
.sp
.LP
\fIcmd\fR may have the following values:
.sp
.ne 2
.na
\fB\fBELF_C_CLR\fR\fR
.ad
.RS 13n
The functions clear the bits that are asserted in \fIflags\fR. Only the
non-zero bits in \fIflags\fR are cleared; zero bits do not change the status of
the descriptor.
.RE

.sp
.ne 2
.na
\fB\fBELF_C_SET\fR\fR
.ad
.RS 13n
The functions set the bits that are asserted in \fIflags\fR. Only the non-zero
bits in \fIflags\fR are set; zero bits do not change the status of the
descriptor.
.RE

.sp
.LP
Descriptions of the defined \fIflags\fR bits appear below:
.sp
.ne 2
.na
\fB\fBELF_F_DIRTY\fR\fR
.ad
.RS 16n
When the program intends to write an \fBELF\fR file, this flag asserts the
associated information needs to be written to the file. Thus, for example, a
program that wished to update the \fBELF\fR header of an existing file would
call \fBelf_flagehdr()\fR with this bit set in \fIflags\fR and \fIcmd\fR equal
to \fBELF_C_SET\fR. A later call to \fBelf_update()\fR would write the marked
header to the file.
.RE

.sp
.ne 2
.na
\fB\fBELF_F_LAYOUT\fR\fR
.ad
.RS 16n
Normally, the library decides how to arrange an output file. That is, it
automatically decides where to place sections, how to align them in the file,
etc. If this bit is set for an \fBELF\fR descriptor, the program assumes
responsibility for determining all file positions. This bit is meaningful only
for \fBelf_flagelf()\fR and applies to the entire file associated with the
descriptor.
.RE

.sp
.LP
When a flag bit is set for an item, it affects all the subitems as well. Thus,
for example, if the program sets the \fBELF_F_DIRTY\fR bit with
\fBelf_flagelf()\fR, the entire logical file is ``dirty.''
.SH EXAMPLES
.LP
\fBExample 1 \fRA sample display of calling the \fBelf_flagdata()\fR function.
.sp
.LP
The following fragment shows how one might mark the \fBELF\fR header to be
written to the output file:

.sp
.in +2
.nf
\fB/* dirty ehdr \|.\|.\|. */
ehdr = elf32_getehdr(elf);
elf_flagehdr(elf, ELF_C_SET, ELF_F_DIRTY);\fR
.fi
.in -2

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Stable
_
MT-Level	MT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBelf\fR(3ELF), \fBelf32_getehdr\fR(3ELF), \fBelf_getdata\fR(3ELF),
\fBelf_update\fR(3ELF), \fBattributes\fR(5)