1 .\" Copyright (C) Caldera International Inc. 2001-2002. All rights reserved.
3 .\" Redistribution and use in source and binary forms, with or without
4 .\" modification, are permitted provided that the following conditions are
7 .\" Redistributions of source code and documentation must retain the above
8 .\" copyright notice, this list of conditions and the following
11 .\" Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
15 .\" All advertising materials mentioning features or use of this software
16 .\" must display the following acknowledgement:
18 .\" This product includes software developed or owned by Caldera
19 .\" International, Inc. Neither the name of Caldera International, Inc.
20 .\" nor the names of other contributors may be used to endorse or promote
21 .\" products derived from this software without specific prior written
24 .\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
25 .\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
26 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
27 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
28 .\" DISCLAIMED. IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE
29 .\" FOR ANY DIRECT, INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR
30 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
32 .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
33 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
34 .\" OR OTHERWISE) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
35 .\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
39 .\" @(#)p3 8.1 (Berkeley) 6/8/93
42 THE STANDARD I/O LIBRARY
44 The ``Standard I/O Library''
45 is a collection of routines
51 The standard I/O library is available on each system that supports C,
52 so programs that confine
53 their system interactions
55 can be transported from one system to another essentially without change.
57 In this section, we will discuss the basics of the standard I/O library.
58 The appendix contains a more complete description of its capabilities.
62 The programs written so far have all
63 read the standard input and written the standard output,
64 which we have assumed are magically pre-defined.
66 is to write a program that accesses
70 already connected to the program.
73 which counts the lines, words and characters
75 For instance, the command
79 prints the number of lines, words and characters
86 The question is how to arrange for the named files
88 that is, how to connect the file system names
89 to the I/O statements which actually read the data.
92 Before it can be read or written
96 by the standard library function
99 takes an external name
104 does some housekeeping and negotiation with the operating system,
105 and returns an internal name
106 which must be used in subsequent
107 reads or writes of the file.
109 This internal name is actually a pointer,
114 which contains information about the file,
115 such as the location of a buffer,
116 the current character position in the buffer,
117 whether the file is being read or written,
119 Users don't need to know the details,
120 because part of the standard I/O definitions
121 obtained by including
123 is a structure definition called
125 The only declaration needed for a file pointer
149 fp = fopen(name, mode);
151 The first argument of
156 as a character string.
157 The second argument is the
159 also as a character string,
160 which indicates how you intend to
162 The only allowable modes are
170 If a file that you open for writing or appending does not exist,
173 Opening an existing file for writing causes the old contents
175 Trying to read a file that does not exist
177 and there may be other causes of error
179 (like trying to read a file
180 when you don't have permission).
181 If there is any error,
183 will return the null pointer
186 (which is defined as zero in
189 The next thing needed is a way to read or write the file
191 There are several possibilities,
198 returns the next character from a file;
199 it needs the file pointer to tell it what file.
206 the next character from the file referred to by
210 when it reaches end of file.
230 When a program is started, three files are opened automatically,
231 and file pointers are provided for them.
232 These files are the standard input,
234 and the standard error output;
235 the corresponding file pointers are
241 Normally these are all connected to the terminal,
243 may be redirected to files or pipes as described in
249 are pre-defined in the I/O library
250 as the standard input, output and error files;
251 they may be used anywhere an object of type
259 so don't try to assign to them.
261 With some of the preliminaries out of the way,
265 is one that has been found
266 convenient for many programs:
267 if there are command-line arguments, they are processed in order.
268 If there are no arguments, the standard input
270 This way the program can be used stand-alone
271 or as part of a larger process.
275 main(argc, argv) /* wc: count lines, words, chars */
281 long linect, wordct, charct;
282 long tlinect = 0, twordct = 0, tcharct = 0;
287 if (argc > 1 && (fp=fopen(argv[i], "r")) == NULL) {
288 fprintf(stderr, "wc: can't open %s\en", argv[i]);
291 linect = wordct = charct = inword = 0;
292 while ((c = getc(fp)) != EOF) {
296 if (c == ' ' || c == '\et' || c == '\en')
298 else if (inword == 0) {
303 printf("%7ld %7ld %7ld", linect, wordct, charct);
304 printf(argc > 1 ? " %s\en" : "\en", argv[i]);
309 } while (++i < argc);
311 printf("%7ld %7ld %7ld total\en", tlinect, twordct, tcharct);
319 save that the first argument is a file pointer
320 that specifies the file to be
327 it breaks the connection between the file pointer and the external name
328 that was established by
331 file pointer for another file.
332 Since there is a limit on the number
334 that a program may have open simultaneously,
335 it's a good idea to free things when they are no longer needed.
336 There is also another reason to call
339 \(em it flushes the buffer
342 is collecting output.
344 is called automatically for each open file
345 when a program terminates normally.)
347 Error Handling \(em Stderr and Exit
350 is assigned to a program in the same way that
357 appears on the user's terminal
358 even if the standard output is redirected.
360 writes its diagnostics on
364 so that if one of the files can't
365 be accessed for some reason,
367 finds its way to the user's terminal instead of disappearing
369 or into an output file.
371 The program actually signals errors in another way,
374 to terminate program execution.
377 is available to whatever process
378 called it (see Section 6),
379 so the success or failure
380 of the program can be tested by another program
381 that uses this one as a sub-process.
382 By convention, a return value of 0
383 signals that all is well;
384 non-zero values signal abnormal situations.
390 for each open output file,
391 to flush out any buffered output,
397 causes immediate termination without any buffer flushing;
398 it may be called directly if desired.
400 Miscellaneous I/O Functions
402 The standard I/O library provides several other I/O functions
403 besides those we have illustrated above.
407 etc., is buffered (except to
409 to force it out immediately, use
415 except that its first argument is a file pointer
418 that specifies the file from which the input comes;
431 except that the first argument names a character string
432 instead of a file pointer.
433 The conversion is done from the string
439 .UL fgets(buf,\ size,\ fp)
440 copies the next line from
442 up to and including a newline,
447 characters are copied;
459 ``pushes back'' the character
461 onto the input stream
469 Only one character of pushback per file is permitted.