8322 nl: misleading-indentation

[unleashed/tickless.git] / usr / src / man / man3c / enable_extended_FILE_stdio.3c

'\" te
.\" Copyright 2014 Nexenta Systems, Inc.  All rights reserved.
.\" 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 ENABLE_EXTENDED_FILE_STDIO 3C "Oct 22, 2014"
.SH NAME
enable_extended_FILE_stdio \- enable extended FILE facility within standard I/O
.SH SYNOPSIS
.LP
.nf
#include <stdio.h>
#include <stdio_ext.h>
#include <signal.h>

\fBint\fR \fBenable_extended_FILE_stdio\fR(\fBint\fR \fIlow_fd\fR, \fBint\fR \fIsignal_action\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBenable_extended_FILE_stdio()\fR function enables the use of the extended
FILE facility (see NOTES) and determines which, if any, signal will be sent
when an application uses \fBFILE\fR->\fI_file\fR inappropriately.
.sp
.LP
The \fIlow_fd\fR argument specifies the lowest file descriptor in the range 3
through 255 that the application wants to be selected as the unallocatable file
descriptor.  File descriptors 0, 1, and 2 cannot be used because they are
reserved for use as the default file descriptors underlying the \fBstdin\fR,
\fBstdout\fR, and \fBstderr\fR standard I/O streams.  The \fIlow_fd\fR argument
can also be set to \(mi1 to request that \fBenable_extended_FILE_stdio()\fR
select a "reasonable" unallocatable file descriptor.  In this case,
\fBenable_extended_FILE_stdio()\fR will first attempt to reserve a relatively
large file descriptor, but will keep trying to find an unallocatable file
descriptor until it is known that no file descriptor can be reserved.
.sp
.LP
The \fIsignal_action\fR argument specifies the signal that will be sent to the
process when the unallocatable file descriptor is used as a file descriptor
argument to any system call except \fBclose\fR(2). If \fIsignal_action\fR is
\(mi1, the default signal (\fBSIGABRT\fR) will be sent. If \fIsignal_action\fR
is 0, no signal will be sent. Otherwise, the signal specified by
\fIsignal_action\fR will be sent.
.sp
.LP
The \fBenable_extended_FILE_stdio()\fR function calls
.sp
.in +2
.nf
unallocatablefd = fcntl(low_fd, F_BADFD, action);
.fi
.in -2

.sp
.LP
to reserve the unallocatable file descriptor and set the signal to be sent if
the unallocatable file descriptor is used in a system call.  If the
\fBfcntl\fR(2) call succeeds, the extended FILE facility is enabled and the
unallocatable file descriptor is saved for later use by the standard I/O
functions.  When an attempt is made to open a standard I/O stream (see
\fBfdopen\fR(3C), \fBfopen\fR(3C), and \fBpopen\fR(3C)) with an underlying file
descriptor greater than 255, the file descriptor is stored in an auxiliary
location and the field formerly known as \fBFILE\fR->\fI_file\fR is set to the
unallocatable file descriptor.
.sp
.LP
If the file descriptor limit for the process is less than or equal to 256 (the
system default), the application needs to raise the limit (see
\fBgetrlimit\fR(2)) for the extended FILE facility to be useful. The
\fBenable_extended_FILE_stdio()\fR function does not attempt to change the file
descriptor limit.
.sp
.LP
This function is used by the \fBextendedFILE\fR(5) preloadable library to
enable the extended FILE facility.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBenable_extended_FILE_stdio()\fR returns 0.
Otherwise, \(mi1 is returned and \fBerrno\fR is set to indicate the error.
.SH ERRORS
.sp
.LP
The \fBenable_extended_FILE_stdio()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBEAGAIN\fR\fR
.ad
.RS 10n
All file descriptors in the inclusive range 3 through 255 refer to files that
are currently open in the process.
.RE

.sp
.ne 2
.na
\fB\fBEBADF\fR\fR
.ad
.RS 10n
The \fIlow_fd\fR argument is greater than 255, or is less than 3 and not equal
to -1.
.RE

.sp
.ne 2
.na
\fB\fBEEXIST\fR\fR
.ad
.RS 10n
A file descriptor has already been marked by an earlier call to \fBfcntl()\fR.
.RE

.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
The \fIsignal_action\fR argument is not \(mi1, is not 0, and is not a valid
signal number.
.RE

.SH USAGE
.sp
.LP
The \fBenable_extended_FILE_stdio()\fR function is available only in the 32-bit
compilation environment.
.sp
.LP
The \fBfdopen\fR(3C), \fBfopen\fR(3C), and \fBpopen\fR(3C) functions all enable
the use of the extended FILE facility. For source changes, a trailing \fBF\fR
character in the \fImode\fR argument can be used with any of these functions if
the \fBFILE *\fR\fIfptr\fR is used only within the context of a single function
or group of functions and not meant to be returned to a caller.  All of the
source code to the application must then be recompiled, thereby exposing any
improper usage of the \fBFILE\fR structure fields.
.sp
.LP
The \fBF\fR character must not be used if the \fBFILE *\fR\fIfptr\fR is to be
returned to a caller.  The calling application might not understand how to
process it. Alternatively, the \fBenable_extended_FILE_stdio()\fR function can
be used at a higher level in the code.
.sp
.LP
Use \fBextendedFILE\fR(5) for binary relief.
.SH EXAMPLES
.LP
\fBExample 1 \fRIncrease the file limit and enable the extended FILE facility.
.sp
.LP
The following example demonstrates how to programmatically increase the file
limit and enable extended FILE facility.

.sp
.in +2
.nf
(void) getrlimit(RLIMIT_NOFILE, &rlp);
rlp.rlim_cur = 1000;  /* set the desired number of file descriptors */
retval = setrlimit(RLIMIT_NOFILE, &lrp);
if (retval == -1) {
    /* error */
}

/* enable extended FILE facility */
retval = enable_extended_FILE_stdio(-1, SIGABRT);
if (retval == -1) {
    /* error */
}
.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     Evolving
_
MT-Level        Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBclose\fR(2), \fBfcntl\fR(2), \fBgetrlimit\fR(2), \fBfdopen\fR(3C),
\fBfopen\fR(3C), \fBpopen\fR(3C), \fBsignal.h\fR(3HEAD), \fBstdio\fR(3C),
\fBattributes\fR(5), \fBextendedFILE\fR(5)
.SH NOTES
.sp
.LP
Historically, 32-bit Solaris applications have been limited to using only the
file descriptors 0 through 255 with the standard I/O functions (see
\fBstdio\fR(3C)) in the C library. The extended FILE facility allows
well-behaved 32-bit applications to use any valid file descriptor with the
standard I/O functions.
.sp
.LP
For the purposes of the extended FILE facility, a well-behaved application is
one that:
.RS +4
.TP
.ie t \(bu
.el o
does not directly access any fields in the \fBFILE\fR structure pointed to by
the \fBFILE\fR pointer associated with any standard I/O stream,
.RE
.RS +4
.TP
.ie t \(bu
.el o
checks all return values from standard I/O functions for error conditions, and
.RE
.RS +4
.TP
.ie t \(bu
.el o
behaves appropriately when an error condition is reported.
.RE
.sp
.LP
The extended FILE facility generates \fBEBADF\fR error returns and optionally
delivers a signal to the calling process on most attempts to use the file
descriptor formerly stored in \fBFILE\fR->\fI_file\fR as an argument to a
system call when a file descriptor value greater than 255 is being used to
access the file underlying the corresponding \fBFILE\fR pointer.  The only
exception is that calls to the \fBclose()\fR system call will return an
\fBEBADF\fR error in this case, but will not deliver the signal. The
\fBFILE\fR->\fI_file\fR has been renamed to help applications quickly detect
code that needs to be updated.
.sp
.LP
The extended FILE facility should only be used by well-behaved applications.
Although the extended FILE facility reports errors, applications that directly
reference \fBFILE\fR->\fI_file\fR should be updated to use public interfaces
rather than rely on implementation details that no longer work as the
application expects (see \fB__fbufsize\fR(3C) and \fBfileno\fR(3C).
.sp
.LP
This facility takes great care to avoid problems in well-behaved applications
while maintaining maximum compatibility. It also attempts to catch dangerous
behavior in applications that are not well-behaved as soon as possible and to
notify those applications as soon as bad behavior is detected.
.sp
.LP
There are, however, limitations.  For example, if an application enables this
facility and is linked with an object file that had a standard I/O stream using
an extended \fBFILE\fR pointer, and then used the sequence
.sp
.in +2
.nf
(void) close(FILE->_file);
FILE->_file = myfd;
.fi
.in -2

.sp
.LP
to attempt to change the file descriptor associated with the stream, undesired
results can occur. The \fBclose()\fR function will fail, but since this usage
ignores the return status, the application proceeds to perform low level I/O on
\fBFILE\fR->\fI_file\fR while calls to standard I/O functions would continue to
use the original, extended \fBFILE\fR pointer.  If the application continues
using standard I/O functions after changing \fBFILE\fR->\fI_file\fR, silent
data corruption could occur because the application thinks it has changed file
descriptors with the above assignment but the actual standard I/O file
descriptor is stored in the auxiliary location. The chances for corruption are
even higher if \fImyfd\fR has a value greater than 255 and is truncated by the
assignment to the 8-bit \fI_file\fR field.
.sp
.LP
Since the \fI_file\fR field has been renamed, attempts to recompile this code
will fail.  The application should be changed not to use this field in the
\fBFILE\fR structure.
.sp
.LP
The application should not use this facility if it uses \fI_file\fR directly,
including using the \fBfileno()\fR macro that was provided in
\fBstdio.h\fR(3HEAD) in Solaris 2.0 through 2.7.