![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to p3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / share / doc / ps2 / 03.uprog|
Return to p3 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / share / doc / ps2 / 03.uprog |
1.1 root 1: .\" @(#)p3 6.3 (Berkeley) 5/10/86
2: .\"
3: .NH
4: THE STANDARD I/O LIBRARY
5: .PP
6: The ``Standard I/O Library''
7: is a collection of routines
8: intended to provide
9: efficient
10: and portable
11: I/O services
12: for most C programs.
13: The standard I/O library is available on each system that supports C,
14: so programs that confine
15: their system interactions
16: to its facilities
17: can be transported from one system to another essentially without change.
18: .PP
19: In this section, we will discuss the basics of the standard I/O library.
20: The appendix contains a more complete description of its capabilities.
21: .NH 2
22: File Access
23: .PP
24: The programs written so far have all
25: read the standard input and written the standard output,
26: which we have assumed are magically pre-defined.
27: The next step
28: is to write a program that accesses
29: a file that is
30: .ul
31: not
32: already connected to the program.
33: One simple example is
34: .IT wc ,
35: which counts the lines, words and characters
36: in a set of files.
37: For instance, the command
38: .P1
39: wc x.c y.c
40: .P2
41: prints the number of lines, words and characters
42: in
43: .UL x.c
44: and
45: .UL y.c
46: and the totals.
47: .PP
48: The question is how to arrange for the named files
49: to be read \(em
50: that is, how to connect the file system names
51: to the I/O statements which actually read the data.
52: .PP
53: The rules are simple.
54: Before it can be read or written
55: a file has to be
56: .ul
57: opened
58: by the standard library function
59: .UL fopen .
60: .UL fopen
61: takes an external name
62: (like
63: .UL x.c
64: or
65: .UL y.c ),
66: does some housekeeping and negotiation with the operating system,
67: and returns an internal name
68: which must be used in subsequent
69: reads or writes of the file.
70: .PP
71: This internal name is actually a pointer,
72: called a
73: .IT file
74: .IT pointer ,
75: to a structure
76: which contains information about the file,
77: such as the location of a buffer,
78: the current character position in the buffer,
79: whether the file is being read or written,
80: and the like.
81: Users don't need to know the details,
82: because part of the standard I/O definitions
83: obtained by including
84: .UL stdio.h
85: is a structure definition called
86: .UL FILE .
87: The only declaration needed for a file pointer
88: is exemplified by
89: .P1
90: FILE *fp, *fopen();
91: .P2
92: This says that
93: .UL fp
94: is a pointer to a
95: .UL FILE ,
96: and
97: .UL fopen
98: returns a pointer to
99: a
100: .UL FILE .
101: .UL FILE \& (
102: is a type name, like
103: .UL int ,
104: not a structure tag.
105: .PP
106: The actual call to
107: .UL fopen
108: in a program
109: is
110: .P1
111: fp = fopen(name, mode);
112: .P2
113: The first argument of
114: .UL fopen
115: is the
116: name
117: of the file,
118: as a character string.
119: The second argument is the
120: mode,
121: also as a character string,
122: which indicates how you intend to
123: use the file.
124: The only allowable modes are
125: read
126: .UL \&"r" ), (
127: write
128: .UL \&"w" ), (
129: or append
130: .UL \&"a" ). (
131: .PP
132: If a file that you open for writing or appending does not exist,
133: it is created
134: (if possible).
135: Opening an existing file for writing causes the old contents
136: to be discarded.
137: Trying to read a file that does not exist
138: is an error,
139: and there may be other causes of error
140: as well
141: (like trying to read a file
142: when you don't have permission).
143: If there is any error,
144: .UL fopen
145: will return the null pointer
146: value
147: .UL NULL
148: (which is defined as zero in
149: .UL stdio.h ).
150: .PP
151: The next thing needed is a way to read or write the file
152: once it is open.
153: There are several possibilities,
154: of which
155: .UL getc
156: and
157: .UL putc
158: are the simplest.
159: .UL getc
160: returns the next character from a file;
161: it needs the file pointer to tell it what file.
162: Thus
163: .P1
164: c = getc(fp)
165: .P2
166: places in
167: .UL c
168: the next character from the file referred to by
169: .UL fp ;
170: it returns
171: .UL EOF
172: when it reaches end of file.
173: .UL putc
174: is the inverse of
175: .UL getc :
176: .P1
177: putc(c, fp)
178: .P2
179: puts the character
180: .UL c
181: on the file
182: .UL fp
183: and returns
184: .UL c .
185: .UL getc
186: and
187: .UL putc
188: return
189: .UL EOF
190: on error.
191: .PP
192: When a program is started, three files are opened automatically,
193: and file pointers are provided for them.
194: These files are the standard input,
195: the standard output,
196: and the standard error output;
197: the corresponding file pointers are
198: called
199: .UL stdin ,
200: .UL stdout ,
201: and
202: .UL stderr .
203: Normally these are all connected to the terminal,
204: but
205: may be redirected to files or pipes as described in
206: Section 2.2.
207: .UL stdin ,
208: .UL stdout
209: and
210: .UL stderr
211: are pre-defined in the I/O library
212: as the standard input, output and error files;
213: they may be used anywhere an object of type
214: .UL FILE\ *
215: can be.
216: They are
217: constants, however,
218: .ul
219: not
220: variables,
221: so don't try to assign to them.
222: .PP
223: With some of the preliminaries out of the way,
224: we can now write
225: .IT wc .
226: The basic design
227: is one that has been found
228: convenient for many programs:
229: if there are command-line arguments, they are processed in order.
230: If there are no arguments, the standard input
231: is processed.
232: This way the program can be used stand-alone
233: or as part of a larger process.
234: .P1
235: #include <stdio.h>
236:
237: main(argc, argv) /* wc: count lines, words, chars */
238: int argc;
239: char *argv[];
240: {
241: int c, i, inword;
242: FILE *fp, *fopen();
243: long linect, wordct, charct;
244: long tlinect = 0, twordct = 0, tcharct = 0;
245:
246: i = 1;
247: fp = stdin;
248: do {
249: if (argc > 1 && (fp=fopen(argv[i], "r")) == NULL) {
250: fprintf(stderr, "wc: can't open %s\en", argv[i]);
251: continue;
252: }
253: linect = wordct = charct = inword = 0;
254: while ((c = getc(fp)) != EOF) {
255: charct++;
256: if (c == '\en')
257: linect++;
258: if (c == ' ' || c == '\et' || c == '\en')
259: inword = 0;
260: else if (inword == 0) {
261: inword = 1;
262: wordct++;
263: }
264: }
265: printf("%7ld %7ld %7ld", linect, wordct, charct);
266: printf(argc > 1 ? " %s\en" : "\en", argv[i]);
267: fclose(fp);
268: tlinect += linect;
269: twordct += wordct;
270: tcharct += charct;
271: } while (++i < argc);
272: if (argc > 2)
273: printf("%7ld %7ld %7ld total\en", tlinect, twordct, tcharct);
274: exit(0);
275: }
276: .P2
277: The function
278: .UL fprintf
279: is identical to
280: .UL printf ,
281: save that the first argument is a file pointer
282: that specifies the file to be
283: written.
284: .PP
285: The function
286: .UL fclose
287: is the inverse of
288: .UL fopen ;
289: it breaks the connection between the file pointer and the external name
290: that was established by
291: .UL fopen ,
292: freeing the
293: file pointer for another file.
294: Since there is a limit on the number
295: of files
296: that a program may have open simultaneously,
297: it's a good idea to free things when they are no longer needed.
298: There is also another reason to call
299: .UL fclose
300: on an output file
301: \(em it flushes the buffer
302: in which
303: .UL putc
304: is collecting output.
305: .UL fclose \& (
306: is called automatically for each open file
307: when a program terminates normally.)
308: .NH 2
309: Error Handling \(em Stderr and Exit
310: .PP
311: .UL stderr
312: is assigned to a program in the same way that
313: .UL stdin
314: and
315: .UL stdout
316: are.
317: Output written on
318: .UL stderr
319: appears on the user's terminal
320: even if the standard output is redirected.
321: .IT wc
322: writes its diagnostics on
323: .UL stderr
324: instead of
325: .UL stdout
326: so that if one of the files can't
327: be accessed for some reason,
328: the message
329: finds its way to the user's terminal instead of disappearing
330: down a pipeline
331: or into an output file.
332: .PP
333: The program actually signals errors in another way,
334: using the function
335: .UL exit
336: to terminate program execution.
337: The argument of
338: .UL exit
339: is available to whatever process
340: called it (see Section 6),
341: so the success or failure
342: of the program can be tested by another program
343: that uses this one as a sub-process.
344: By convention, a return value of 0
345: signals that all is well;
346: non-zero values signal abnormal situations.
347: .PP
348: .UL exit
349: itself
350: calls
351: .UL fclose
352: for each open output file,
353: to flush out any buffered output,
354: then calls
355: a routine named
356: .UL _exit .
357: The function
358: .UL _exit
359: causes immediate termination without any buffer flushing;
360: it may be called directly if desired.
361: .NH 2
362: Miscellaneous I/O Functions
363: .PP
364: The standard I/O library provides several other I/O functions
365: besides those we have illustrated above.
366: .PP
367: Normally output with
368: .UL putc ,
369: etc., is buffered (except to
370: .UL stderr );
371: to force it out immediately, use
372: .UL fflush(fp) .
373: .PP
374: .UL fscanf
375: is identical to
376: .UL scanf ,
377: except that its first argument is a file pointer
378: (as with
379: .UL fprintf )
380: that specifies the file from which the input comes;
381: it returns
382: .UL EOF
383: at end of file.
384: .PP
385: The functions
386: .UL sscanf
387: and
388: .UL sprintf
389: are identical to
390: .UL fscanf
391: and
392: .UL fprintf ,
393: except that the first argument names a character string
394: instead of a file pointer.
395: The conversion is done from the string
396: for
397: .UL sscanf
398: and into it for
399: .UL sprintf .
400: .PP
401: .UL fgets(buf,\ size,\ fp)
402: copies the next line from
403: .UL fp ,
404: up to and including a newline,
405: into
406: .UL buf ;
407: at most
408: .UL size-1
409: characters are copied;
410: it returns
411: .UL NULL
412: at end of file.
413: .UL fputs(buf,\ fp)
414: writes the string in
415: .UL buf
416: onto file
417: .UL fp .
418: .PP
419: The function
420: .UL ungetc(c,\ fp)
421: ``pushes back'' the character
422: .UL c
423: onto the input stream
424: .UL fp ;
425: a subsequent call to
426: .UL getc ,
427: .UL fscanf ,
428: etc.,
429: will encounter
430: .UL c .
431: Only one character of pushback per file is permitted.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.