usr/src/man/man5/extendedFILE.5

   1 '\" te
   2 .\" Copyright (c) 2006, 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 EXTENDEDFILE 5 "Apr 18, 2006"
   7 .SH NAME
   8 extendedFILE \- enable extended FILE facility usage
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 $ ulimit \fB-n\fR \fIN_file_descriptors\fR
  13 $ LD_PRELOAD_32=/usr/lib/extendedFILE.so.1 \fIapplication\fR [\fIarg\fR...]
  14 .fi
  15
  16 .SH DESCRIPTION
  17 .sp
  18 .LP
  19 The \fBextendedFILE.so.1\fR is not a library but an enabler of the extended
  20 FILE facility.
  21 .sp
  22 .LP
  23 The extended FILE facility allows 32-bit processes to use any valid file
  24 descriptor with the standard I/O (see \fBstdio\fR(3C)) C library functions.
  25 Historically, 32-bit applications have been limited to using the first 256
  26 numerical file descriptors for use with standard I/O streams.  By using the
  27 extended FILE facility this limitation is lifted. Any valid file descriptor can
  28 be used with standard I/O. See the NOTES section of
  29 \fBenable_extended_FILE_stdio\fR(3C).
  30 .sp
  31 .LP
  32 The extended FILE facility is enabled from the shell level before an
  33 application is launched. The file descriptor limit must also be raised. The
  34 syntax for raising the file descriptor limit is
  35 .sp
  36 .in +2
  37 .nf
  38 $ ulimit -n \fImax_file_descriptors\fR
  39 $ LD_PRELOAD_32=/usr/lib/extendedFILE.so.1 \fIapplication\fR [\fIarg\fR...]
  40 .fi
  41 .in -2
  42
  43 .sp
  44 .LP
  45 where \fImax_file_descriptors\fR is the maximum number of file descriptors
  46 desired. See \fBlimit\fR(1). The maximum value is the same as the maximum value
  47 for \fBopen\fR(2).
  48 .SH ENVIRONMENT VARIABLES
  49 .sp
  50 .LP
  51 The following environment variables control the behavior of the extended FILE
  52 facility.
  53 .sp
  54 .ne 2
  55 .na
  56 \fB\fB_STDIO_BADFD\fR\fR
  57 .ad
  58 .RS 23n
  59 This variable takes an integer representing the lowest file descriptor, which
  60 will be made unallocatable. This action provides a protection mechanism so that
  61 applications that abuse interfaces do not experience silent data corruption.
  62 The value must be between 3 and 255 inclusive.
  63 .RE
  64
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fB_STDIO_BADFD_SIGNAL\fR\fR
  69 .ad
  70 .RS 23n
  71 This variable takes an integer or string representing any valid signal. See
  72 \fBsignal.h\fR(3HEAD) for valid values or strings. This environment variable
  73 causes the specified signal to be sent to the application if certain
  74 exceptional cases are detected during the use of this facility. The default
  75 signal is \fBSIGABRT\fR.
  76 .RE
  77
  78 .SH EXAMPLES
  79 .LP
  80 \fBExample 1 \fRLimit the number of file descriptors and FILE standard I/O
  81 structures.
  82 .sp
  83 .LP
  84 The following example limits the number of file descriptors and FILE standard
  85 I/O structures to 1000.
  86
  87 .sp
  88 .in +2
  89 .nf
  90 $ ulimit -n 1000
  91 $ LD_PRELOAD_32=/usr/lib/extendedFILE.so.1 application [arg...]
  92 .fi
  93 .in -2
  94
  95 .LP
  96 \fBExample 2 \fREnable the extended FILE facility.
  97 .sp
  98 .LP
  99 The following example enables the extended FILE facility. See
 100 \fBenable_extended_FILE_stdio\fR(3C) for more examples.
 101
 102 .sp
 103 .in +2
 104 .nf
 105 $ ulimit -n 1000
 106 $ _STDIO_BADFD=100 _STDIO_BADFD_SIGNAL=SIGABRT \e
 107    LD_PRELOAD_32=/usr/lib/extendedFILE.so.1  \e
 108    application [arg ...]
 109 .fi
 110 .in -2
 111
 112 .LP
 113 \fBExample 3 \fRSet up the extended FILE environment and start the application.
 114 .sp
 115 .LP
 116 The following shell script first sets up the proper extended FILE environment
 117 and then starts the application:
 118
 119 .sp
 120 .in +2
 121 .nf
 122 #!/bin/sh
 123 if [ $# = 0 ]; then
 124    echo "usage: $0 application [arguments...]"
 125    exit 1
 126 fi
 127 ulimit -n 1000
 128 # _STDIO_BADFD=196; export _STDIO_BADFD
 129 # _STDIO_BADFD_SIGNAL=SIGABRT; export _STDIO_BADFD_SIGNAL
 130 LD_PRELOAD_32=/usr/lib/extendedFILE.so.1; export LD_PRELOAD_32
 131 "$@"
 132 .fi
 133 .in -2
 134
 135 .SH FILES
 136 .sp
 137 .ne 2
 138 .na
 139 \fB\fB/usr/lib/extendedFILE.so.1\fR\fR
 140 .ad
 141 .RS 30n
 142 enabling library
 143 .RE
 144
 145 .SH ATTRIBUTES
 146 .sp
 147 .LP
 148 See \fBattributes\fR(5)  for descriptions of the following attributes:
 149 .sp
 150
 151 .sp
 152 .TS
 153 box;
 154 c | c
 155 l | l .
 156 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 157 _
 158 Interface Stability     Stable
 159 _
 160 MT-Level        Safe
 161 .TE
 162
 163 .SH SEE ALSO
 164 .sp
 165 .LP
 166 \fBlimit\fR(1), \fBopen\fR(2), \fBenable_extended_FILE_stdio\fR(3C),
 167 \fBfdopen\fR(3C), \fBfopen\fR(3C), \fBpopen\fR(3C), \fBsignal.h\fR(3HEAD),
 168 \fBstdio\fR(3C), \fBattributes\fR(5)
 169 .SH WARNINGS
 170 .sp
 171 .LP
 172 The following displayed message
 173 .sp
 174 .in +2
 175 .nf
 176 Application violated extended FILE safety mechanism.
 177 Please read the man page for extendedFILE.
 178 Aborting
 179 .fi
 180 .in -2
 181 .sp
 182
 183 .sp
 184 .LP
 185 is an indication that your application is modifying the internal file
 186 descriptor field of the \fBFILE\fR structure from standard I/O. Continued use
 187 of this extended FILE facility could harm your data.  Do not use the extended
 188 FILE facility with your application.