1stdio(3C) Standard C Library Functions stdio(3C)
2
6 stdio - standard buffered input/output package
7
9 #include <stdio.h>
10 extern FILE *stdin;
13 extern FILE *stdout;
16 extern FILE *stderr;
19
22 The standard I/O functions described in section 3C of this manual con‐
23 stitute an efficient, user-level I/O buffering scheme. The in-line
24 macros getc() and putc() handle characters quickly. The macros
25 getchar(3C) and putchar(3C), and the higher-level routines fgetc(3C),
26 fgets(3C), fprintf(3C), fputc(3C), fputs(3C), fread(3C), fscanf(3C),
27 fwrite(3C), gets(3C), getw(3C), printf(3C), puts(3C), putw(3C), and
28 scanf(3C) all use or act as if they use getc() and putc(); they can be
29 freely intermixed.
30 A file with associated buffering is called a stream (see Intro(3)) and
33 is declared to be a pointer to a defined type FILE. The fopen(3C) func‐
34 tion creates certain descriptive data for a stream and returns a
35 pointer to designate the stream in all further transactions. Normally,
36 there are three open streams with constant pointers declared in the
37 <stdio.h> header and associated with the standard open files:
38 stdin standard input file
40 stdout standard output file
43 stderr standard error file
46 The following symbolic values in <unistd.h> define the file descriptors
50 that will be associated with the C-language stdin, stdout and stderr
51 when the application is started:
52 STDIN_FILENO Standard input value 0 stdin
57 STDOUT_FILENO Standard output value 1 stdout
58 STDERR_FILENO Standard error value 2 stderr
59 The constant NULL designates a null pointer.
63 The integer-constant EOF is returned upon end-of-file or error by most
66 integer functions that deal with streams (see the individual descrip‐
67 tions for details).
68 The integer constant BUFSIZ specifies the size of the buffers used by
71 the particular implementation.
72 The integer constant FILENAME_MAX specifies the number of bytes needed
75 to hold the longest pathname of a file allowed by the implementation.
76 If the system does not impose a maximum limit, this value is the recom‐
77 mended size for a buffer intended to hold a file's pathname.
78 The integer constant FOPEN_MAX specifies the minimum number of files
81 that the implementation guarantees can be open simultaneously. Note
82 that no more than 255 files may be opened using fopen(), and only file
83 descriptors 0 through 255 can be used in a stream.
84 The functions and constants mentioned in the entries of section 3S of
87 this manual are declared in that header and need no further declara‐
88 tion. The constants and the following "functions" are implemented as
89 macros (redeclaration of these names is perilous): getc(), getchar(),
90 putc(), putchar(), ferror(3C), feof(3C), clearerr(3C), and fileno(3C).
91 There are also function versions of getc(), getchar(), putc(),
92 putchar(), ferror(), feof(), clearerr(), and fileno().
93 Output streams, with the exception of the standard error stream stderr,
96 are by default buffered if the output refers to a file and line-
97 buffered if the output refers to a terminal. The standard error output
98 stream stderr is by default unbuffered, but use of freopen() (see
99 fopen(3C)) will cause it to become buffered or line-buffered. When an
100 output stream is unbuffered, information is queued for writing on the
101 destination file or terminal as soon as written; when it is buffered,
102 many characters are saved up and written as a block. When it is line-
103 buffered, each line of output is queued for writing on the destination
104 terminal as soon as the line is completed (that is, as soon as a new-
105 line character is written or terminal input is requested). The setbuf()
106 or setvbuf() functions (both described on the setbuf(3C) manual page)
107 may be used to change the stream's buffering strategy.
108 Interactions of Other FILE-Type C Functions
110 A single open file description can be accessed both through streams and
111 through file descriptors. Either a file descriptor or a stream will be
112 called a handle on the open file description to which it refers; an
113 open file description may have several handles.
114 Handles can be created or destroyed by user action without affecting
117 the underlying open file description. Some of the ways to create them
118 include fcntl(2), dup(2), fdopen(3C), fileno(3C) and fork(2) (which
119 duplicates existing ones into new processes). They can be destroyed by
120 at least fclose(3C) and close(2), and by the exec functions (see
121 exec(2)), which close some file descriptors and destroy streams.
122 A file descriptor that is never used in an operation and could affect
125 the file offset (for example read(2), write(2), or lseek(2)) is not
126 considered a handle in this discussion, but could give rise to one (as
127 a consequence of fdopen(), dup(), or fork(), for example). This excep‐
128 tion does include the file descriptor underlying a stream, whether cre‐
129 ated with fopen() or fdopen(), as long as it is not used directly by
130 the application to affect the file offset. (The read() and write()
131 functions implicitly affect the file offset; lseek() explicitly
132 affects it.)
133 If two or more handles are used, and any one of them is a stream, their
136 actions shall be coordinated as described below. If this is not done,
137 the result is undefined.
138 A handle that is a stream is considered to be closed when either an
141 fclose() or freopen(3C) is executed on it (the result of freopen() is
142 a new stream for this discussion, which cannot be a handle on the same
143 open file description as its previous value) or when the process owning
144 that stream terminates the exit(2) or abort(3C). A file descriptor is
145 closed by close(), _exit() (see exit(2)), or by one of the exec func‐
146 tions when FD_CLOEXEC is set on that file descriptor.
147 For a handle to become the active handle, the actions below must be
150 performed between the last other user of the first handle (the current
151 active handle) and the first other user of the second handle (the
152 future active handle). The second handle then becomes the active han‐
153 dle. All activity by the application affecting the file offset on the
154 first handle shall be suspended until it again becomes the active han‐
155 dle. (If a stream function has as an underlying function that affects
156 the file offset, the stream function will be considered to affect the
157 file offset. The underlying functions are described below.)
158 The handles need not be in the same process for these rules to apply.
161 Note that after a fork(), two handles exist where one existed before.
162 The application shall assure that, if both handles will ever be
163 accessed, that they will both be in a state where the other could
164 become the active handle first. The application shall prepare for a
165 fork() exactly as if it were a change of active handle. (If the only
166 action performed by one of the processes is one of the exec functions
167 or _exit(), the handle is never accessed in that process.)
168 1. For the first handle, the first applicable condition below
170 shall apply. After the actions required below are taken, the
171 handle may be closed if it is still open.
172 a. If it is a file descriptor, no action is required.
174 b. If the only further action to be performed on any handle
176 to this open file description is to close it, no action
177 need be taken.
178 c. If it is a stream that is unbuffered, no action need be
180 taken.
181 d. If it is a stream that is line-buffered and the last
183 character written to the stream was a newline (that is,
184 as if a putc('\n') was the most recent operation on that
185 stream), no action need be taken.
186 e. If it is a stream that is open for writing or append
188 (but not also open for reading), either an fflush(3C)
189 shall occur or the stream shall be closed.
190 f. If the stream is open for reading and it is at the end
192 of the file ( feof(3C) is true), no action need be
193 taken.
194 g. If the stream is open with a mode that allows reading
196 and the underlying open file description refers to a
197 device that is capable of seeking, either an fflush()
198 shall occur or the stream shall be closed.
199 h. Otherwise, the result is undefined.
201 2. For the second handle: if any previous active handle has
203 called a function that explicitly changed the file offset,
204 except as required above for the first handle, the applica‐
205 tion shall perform an lseek() or an fseek(3C) (as appropri‐
206 ate to the type of the handle) to an appropriate location.
207 3. If the active handle ceases to be accessible before the
209 requirements on the first handle above have been met, the
210 state of the open file description becomes undefined. This
211 might occur, for example, during a fork() or an _exit().
212 4. The exec functions shall be considered to make inaccessible
214 all streams that are open at the time they are called, inde‐
215 pendent of what streams or file descriptors may be available
216 to the new process image.
217 5. Implementation shall assure that an application, even one
219 consisting of several processes, shall yield correct results
220 (no data is lost or duplicated when writing, all data is
221 written in order, except as requested by seeks) when the
222 rules above are followed, regardless of the sequence of han‐
223 dles used. If the rules above are not followed, the result
224 is unspecified. When these rules are followed, it is imple‐
225 mentation defined whether, and under what conditions, all
226 input is seen exactly once.
227 Use of stdio in Multithreaded Applications
229 All the stdio functions are safe unless they have the _unlocked suffix.
230 Each FILE pointer has its own lock to guarantee that only one thread
231 can access it. In the case that output needs to be synchronized, the
232 lock for the FILE pointer can be acquired before performing a series of
233 stdio operations. For example:
234 FILE iop;
236 flockfile(iop);
237 fprintf(iop, "hello ");
238 fprintf(iop, "world);
239 fputc(iop, 'a');
240 funlockfile(iop);
241 will print everything out together, blocking other threads that might
245 want to write to the same file between calls to fprintf().
246 An unlocked interface is available in case performace is an issue. For
249 example:
250 flockfile(iop);
252 while (!feof(iop)) {
253 *c++ = getc_unlocked(iop);
254 }
255 funlockfile(iop);
256
259 Invalid stream pointers usually cause grave disorder, possibly includ‐
260 ing program termination. Individual function descriptions describe the
261 possible error conditions.
262
264 close(2), lseek(2), open(2), pipe(2), read(2), write(2), ctermid(3C),
265 cuserid(3C), fclose(3C), ferror(3C), fopen(3C), fread(3C), fseek(3C),
266 flockfile(3C), getc(3C), gets(3C), popen(3C), printf(3C), putc(3C),
267 puts(3C), scanf(3C), setbuf(3C), system(3C), tmpfile(3C), tmpnam(3C),
268 ungetc(3C)
269SunOS 5.11 18 May 2005 stdio(3C)