'\" te
.\" Copyright (c) 2006, 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 EXTENDEDFILE 5 "Apr 18, 2006"
.SH NAME
extendedFILE \- enable extended FILE facility usage
.SH SYNOPSIS
.LP
.nf
$ ulimit \fB-n\fR \fIN_file_descriptors\fR
$ LD_PRELOAD_32=/usr/lib/extendedFILE.so.1 \fIapplication\fR [\fIarg\fR...]
.fi

.SH DESCRIPTION
.sp
.LP
The \fBextendedFILE.so.1\fR is not a library but an enabler of the extended
FILE facility.
.sp
.LP
The extended FILE facility allows 32-bit processes to use any valid file
descriptor with the standard I/O (see \fBstdio\fR(3C)) C library functions.
Historically, 32-bit applications have been limited to using the first 256
numerical file descriptors for use with standard I/O streams.  By using the
extended FILE facility this limitation is lifted. Any valid file descriptor can
be used with standard I/O. See the NOTES section of
\fBenable_extended_FILE_stdio\fR(3C).
.sp
.LP
The extended FILE facility is enabled from the shell level before an
application is launched. The file descriptor limit must also be raised. The
syntax for raising the file descriptor limit is
.sp
.in +2
.nf
$ ulimit -n \fImax_file_descriptors\fR
$ LD_PRELOAD_32=/usr/lib/extendedFILE.so.1 \fIapplication\fR [\fIarg\fR...]
.fi
.in -2

.sp
.LP
where \fImax_file_descriptors\fR is the maximum number of file descriptors
desired. See \fBlimit\fR(1). The maximum value is the same as the maximum value
for \fBopen\fR(2).
.SH ENVIRONMENT VARIABLES
.sp
.LP
The following environment variables control the behavior of the extended FILE
facility.
.sp
.ne 2
.na
\fB\fB_STDIO_BADFD\fR\fR
.ad
.RS 23n
This variable takes an integer representing the lowest file descriptor, which
will be made unallocatable. This action provides a protection mechanism so that
applications that abuse interfaces do not experience silent data corruption.
The value must be between 3 and 255 inclusive.
.RE

.sp
.ne 2
.na
\fB\fB_STDIO_BADFD_SIGNAL\fR\fR
.ad
.RS 23n
This variable takes an integer or string representing any valid signal. See
\fBsignal.h\fR(3HEAD) for valid values or strings. This environment variable
causes the specified signal to be sent to the application if certain
exceptional cases are detected during the use of this facility. The default
signal is \fBSIGABRT\fR.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRLimit the number of file descriptors and FILE standard I/O
structures.
.sp
.LP
The following example limits the number of file descriptors and FILE standard
I/O structures to 1000.

.sp
.in +2
.nf
$ ulimit -n 1000
$ LD_PRELOAD_32=/usr/lib/extendedFILE.so.1 application [arg...]
.fi
.in -2

.LP
\fBExample 2 \fREnable the extended FILE facility.
.sp
.LP
The following example enables the extended FILE facility. See
\fBenable_extended_FILE_stdio\fR(3C) for more examples.

.sp
.in +2
.nf
$ ulimit -n 1000
$ _STDIO_BADFD=100 _STDIO_BADFD_SIGNAL=SIGABRT \e
   LD_PRELOAD_32=/usr/lib/extendedFILE.so.1  \e
   application [arg ...]
.fi
.in -2

.LP
\fBExample 3 \fRSet up the extended FILE environment and start the application.
.sp
.LP
The following shell script first sets up the proper extended FILE environment
and then starts the application:

.sp
.in +2
.nf
#!/bin/sh
if [ $# = 0 ]; then
   echo "usage: $0 application [arguments...]"
   exit 1
fi
ulimit -n 1000
# _STDIO_BADFD=196; export _STDIO_BADFD
# _STDIO_BADFD_SIGNAL=SIGABRT; export _STDIO_BADFD_SIGNAL
LD_PRELOAD_32=/usr/lib/extendedFILE.so.1; export LD_PRELOAD_32
"$@"
.fi
.in -2

.SH FILES
.sp
.ne 2
.na
\fB\fB/usr/lib/extendedFILE.so.1\fR\fR
.ad
.RS 30n
enabling library
.RE

.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	Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBlimit\fR(1), \fBopen\fR(2), \fBenable_extended_FILE_stdio\fR(3C),
\fBfdopen\fR(3C), \fBfopen\fR(3C), \fBpopen\fR(3C), \fBsignal.h\fR(3HEAD),
\fBstdio\fR(3C), \fBattributes\fR(5)
.SH WARNINGS
.sp
.LP
The following displayed message
.sp
.in +2
.nf
Application violated extended FILE safety mechanism.
Please read the man page for extendedFILE.
Aborting
.fi
.in -2
.sp

.sp
.LP
is an indication that your application is modifying the internal file
descriptor field of the \fBFILE\fR structure from standard I/O. Continued use
of this extended FILE facility could harm your data.  Do not use the extended
FILE facility with your application.