1enable_extended_FILE_stdioS(t3aCn)dard C Library Functeinoanbsle_extended_FILE_stdio(3C)
2
6 enable_extended_FILE_stdio - enable extended FILE facility within stan‐
7 dard I/O
8
10 #include <stdio.h>
11 #include <stdio_ext.h>
12 #include <signal.h>
13 int enable_extended_FILE_stdio(int low_fd, int signal_action);
15
18 The enable_extended_FILE_stdio() function enables the use of the
19 extended FILE facility (see NOTES) and determines which, if any, signal
20 will be sent when an application uses FILE->_file inappropriately.
21 The low_fd argument specifies the lowest file descriptor in the range 3
24 through 255 that the application wants to be selected as the unallocat‐
25 able file descriptor. File descriptors 0, 1, and 2 cannot be used
26 because they are reserved for use as the default file descriptors
27 underlying the stdin, stdout, and stderr standard I/O streams. The
28 low_fd argument can also be set to −1 to request that
29 enable_extended_FILE_stdio() select a "reasonable" unallocatable file
30 descriptor. In this case, enable_extended_FILE_stdio() will first
31 attempt to reserve a relatively large file descriptor, but will keep
32 trying to find an unallocatable file descriptor until it is known that
33 no file descriptor can be reserved.
34 The signal_action argument specifies the signal that will be sent to
37 the process when the unallocatable file descriptor is used as a file
38 descriptor argument to any system call except close(2). If sig‐
39 nal_action is −1, the default signal (SIGABRT) will be sent. If sig‐
40 nal_action is 0, no signal will be sent. Otherwise, the signal speci‐
41 fied by signal_action will be sent.
42 The enable_extended_FILE_stdio() function calls
45 unallocatablefd = fcntl(low_fd, F_BADFD, action);
47 to reserve the unallocatable file descriptor and set the signal to be
51 sent if the unallocatable file descriptor is used in a system call. If
52 the fcntl(2) call succeeds, the extended FILE facility is enabled and
53 the unallocatable file descriptor is saved for later use by the stan‐
54 dard I/O functions. When an attempt is made to open a standard I/O
55 stream (see fdopen(3C), fopen(3C), and popen(3C)) with an underlying
56 file descriptor greater than 255, the file descriptor is stored in an
57 auxiliary location and the field formerly known as FILE->_file is set
58 to the unallocatable file descriptor.
59 If the file descriptor limit for the process is less than or equal to
62 256 (the system default), the application needs to raise the limit (see
63 getrlimit(2)) for the extended FILE facility to be useful. The
64 enable_extended_FILE_stdio() function does not attempt to change the
65 file descriptor limit.
66 This function is used by the extendedFILE(5) preloadable library to
69 enable the extended FILE facility.
70
72 Upon successful completion, enable_extended_FILE_stdio() returns 0.
73 Otherwise, −1 is returned and errno is set to indicate the error.
74
76 The enable_extended_FILE_stdio() function will fail if:
77 EAGAIN All file descriptors in the inclusive range 3 through 255
79 refer to files that are currently open in the process.
80 EBADF The low_fd argument is greater than 255, or is less than 3
83 and not equal to -1.
84 EEXIST A file descriptor has already been marked by an earlier call
87 to fcntl().
88 EINVAL The signal_action argument is not −1, is not 0, and is not a
91 valid signal number.
92
95 The enable_extended_FILE_stdio() function is available only in the
96 32-bit compilation environment.
97 The fdopen(3C), fopen(3C), and popen(3C) functions all enable the use
100 of the extended FILE facility. For source changes, a trailing F charac‐
101 ter in the mode argument can be used with any of these functions if the
102 FILE *fptr is used only within the context of a single function or
103 group of functions and not meant to be returned to a caller. All of
104 the source code to the application must then be recompiled, thereby
105 exposing any improper usage of the FILE structure fields.
106 The F character must not be used if the FILE *fptr is to be returned to
109 a caller. The calling application might not understand how to process
110 it. Alternatively, the enable_extended_FILE_stdio() function can be
111 used at a higher level in the code.
112 Use extendedFILE(5) for binary relief.
115
117 Example 1 Increase the file limit and enable the extended FILE facil‐
118 ity.
119 The following example demonstrates how to programmatically increase the
122 file limit and enable extended FILE facility.
123 (void) getrlimit(RLIMIT_NOFILE, &rlp);
126 rlp.rlim_cur = 1000; /* set the desired number of file descriptors */
127 retval = setrlimit(RLIMIT_NOFILE, &lrp);
128 if (retval == -1) {
129 /* error */
130 }
131 /* enable extended FILE facility */
133 retval = enable_extended_FILE_stdio(-1, SIGABRT);
134 if (retval == -1) {
135 /* error */
136 }
137
140 See attributes(5) for descriptions of the following attributes:
141 ┌─────────────────────────────┬─────────────────────────────┐
146 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
147 ├─────────────────────────────┼─────────────────────────────┤
148 │Availability │SUNWcsl (32-bit) │
149 ├─────────────────────────────┼─────────────────────────────┤
150 │Interface Stability │Evolving │
151 ├─────────────────────────────┼─────────────────────────────┤
152 │MT-Level │Safe │
153 └─────────────────────────────┴─────────────────────────────┘
154
156 close(2), fcntl(2), getrlimit(2), fdopen(3C), fopen(3C), popen(3C),
157 signal.h(3HEAD), stdio(3C), attributes(5), extendedFILE(5)
158
160 Historically, 32-bit Solaris applications have been limited to using
161 only the file descriptors 0 through 255 with the standard I/O functions
162 (see stdio(3C)) in the C library. The extended FILE facility allows
163 well-behaved 32-bit applications to use any valid file descriptor with
164 the standard I/O functions.
165 For the purposes of the extended FILE facility, a well-behaved applica‐
168 tion is one that:
169 o does not directly access any fields in the FILE structure
171 pointed to by the FILE pointer associated with any standard
172 I/O stream,
173 o checks all return values from standard I/O functions for
175 error conditions, and
176 o behaves appropriately when an error condition is reported.
178 The extended FILE facility generates EBADF error returns and optionally
181 delivers a signal to the calling process on most attempts to use the
182 file descriptor formerly stored in FILE->_file as an argument to a sys‐
183 tem call when a file descriptor value greater than 255 is being used to
184 access the file underlying the corresponding FILE pointer. The only
185 exception is that calls to the close() system call will return an EBADF
186 error in this case, but will not deliver the signal. The FILE->_file
187 has been renamed to help applications quickly detect code that needs to
188 be updated.
189 The extended FILE facility should only be used by well-behaved applica‐
192 tions. Although the extended FILE facility reports errors, applica‐
193 tions that directly reference FILE->_file should be updated to use pub‐
194 lic interfaces rather than rely on implementation details that no
195 longer work as the application expects (see __fbufsize(3C) and
196 fileno(3C).
197 This facility takes great care to avoid problems in well-behaved appli‐
200 cations while maintaining maximum compatibility. It also attempts to
201 catch dangerous behavior in applications that are not well-behaved as
202 soon as possible and to notify those applications as soon as bad behav‐
203 ior is detected.
204 There are, however, limitations. For example, if an application
207 enables this facility and is linked with an object file that had a
208 standard I/O stream using an extended FILE pointer, and then used the
209 sequence
210 (void) close(FILE->_file);
212 FILE->_file = myfd;
213 to attempt to change the file descriptor associated with the stream,
217 undesired results can occur. The close() function will fail, but since
218 this usage ignores the return status, the application proceeds to per‐
219 form low level I/O on FILE->_file while calls to standard I/O functions
220 would continue to use the original, extended FILE pointer. If the
221 application continues using standard I/O functions after changing
222 FILE->_file, silent data corruption could occur because the application
223 thinks it has changed file descriptors with the above assignment but
224 the actual standard I/O file descriptor is stored in the auxiliary
225 location. The chances for corruption are even higher if myfd has a
226 value greater than 255 and is truncated by the assignment to the 8-bit
227 _file field.
228 Since the_file field has been renamed, attempts to recompile this code
231 will fail. The application should be changed not to use this field in
232 the FILE structure.
233 The application should not use this facility if it uses _file directly,
236 including using the fileno() macro that was provided in stdio.h(3HEAD)
237 in Solaris 2.0 through 2.7.
238SunOS 5.11 18 Apr 2006 enable_extended_FILE_stdio(3C)