Commit | Line | Data |
---|---|---|
95f51977 C |
1 | .\" @(#)p9 6.1 (Berkeley) 4/25/86 |
2 | .\" | |
c9528a00 C |
3 | .sp 100 |
4 | .TL | |
5 | .ft R | |
6 | Appendix \(em The Standard I/O Library | |
7 | .AU | |
8 | D. M. Ritchie | |
9 | .AI | |
10 | .MH | |
11 | .PP | |
12 | The standard I/O library | |
13 | was designed with the following goals in mind. | |
14 | .IP 1. | |
15 | It must be as efficient as possible, both in time and in space, | |
16 | so that there will be no hesitation in using it | |
17 | no matter how critical the application. | |
18 | .IP 2. | |
19 | It must be simple to use, and also free of the magic | |
20 | numbers and mysterious calls | |
21 | whose use mars the understandability and portability | |
22 | of many programs using older packages. | |
23 | .IP 3. | |
24 | The interface provided should be applicable on all machines, | |
25 | whether or not the programs which implement it are directly portable | |
26 | to other systems, | |
27 | or to machines other than the PDP-11 running a version of | |
28 | .UC UNIX . | |
29 | .SH | |
30 | 1. General Usage | |
31 | .PP | |
32 | Each program using the library must have the line | |
33 | .P1 | |
34 | #include <stdio.h> | |
35 | .P2 | |
36 | which defines certain macros and variables. | |
37 | The routines are in the normal C library, | |
38 | so no special library argument is needed for loading. | |
39 | All names in the include file intended only for internal use begin | |
40 | with an underscore | |
41 | .UL _ | |
42 | to reduce the possibility | |
43 | of collision with a user name. | |
44 | The names intended to be visible outside the package are | |
45 | .IP \f3stdin\f1 10 | |
46 | The name of the standard input file | |
47 | .IP \f3stdout\f1 10 | |
48 | The name of the standard output file | |
49 | .IP \f3stderr\f1 10 | |
50 | The name of the standard error file | |
51 | .IP \f3EOF\f1 10 | |
52 | is actually \-1, and is the value returned by | |
53 | the read routines on end-of-file or error. | |
54 | .IP \f3NULL\f1 10 | |
55 | is a notation for the null pointer, returned by | |
56 | pointer-valued functions | |
57 | to indicate an error | |
58 | .IP \f3FILE\f1 10 | |
59 | expands to | |
60 | .UL struct | |
61 | .UL _iob | |
62 | and is a useful | |
63 | shorthand when declaring pointers | |
64 | to streams. | |
65 | .IP \f3BUFSIZ\f1 10 | |
66 | is a number (viz. 512) | |
67 | of the size suitable for an I/O buffer supplied by the user. | |
68 | See | |
69 | .UL setbuf , | |
70 | below. | |
71 | .IP \f3getc,\ getchar,\ putc,\ putchar,\ feof,\ ferror,\ f\&ileno\f1 10 | |
72 | .br | |
73 | are defined as macros. | |
74 | Their actions are described below; | |
75 | they are mentioned here | |
76 | to point out that it is not possible to | |
77 | redeclare them | |
78 | and that they are not actually functions; | |
79 | thus, for example, they may not have breakpoints set on them. | |
80 | .PP | |
81 | The routines in this package | |
82 | offer the convenience of automatic buffer allocation | |
83 | and output flushing where appropriate. | |
84 | The names | |
85 | .UL stdin , | |
86 | .UL stdout , | |
87 | and | |
88 | .UL stderr | |
89 | are in effect constants and may not be assigned to. | |
90 | .SH | |
91 | 2. Calls | |
92 | .nr PD .4v | |
93 | .LP | |
94 | .UL FILE\ *fopen(filename,\ type)\ char\ *filename,\ *type; | |
95 | .nr PD 0 | |
96 | .IP | |
97 | .br | |
98 | opens the file and, if needed, allocates a buffer for it. | |
99 | .UL filename | |
100 | is a character string specifying the name. | |
101 | .UL type | |
102 | is a character string (not a single character). | |
103 | It may be | |
104 | .UL \&"r" , | |
105 | .UL \&"w" , | |
106 | or | |
107 | .UL \&"a" | |
108 | to indicate | |
109 | intent to read, write, or append. | |
110 | The value returned is a file pointer. | |
111 | If it is | |
112 | .UL NULL | |
113 | the attempt to open failed. | |
114 | .ne 3 | |
115 | .nr PD .4v | |
116 | .LP | |
117 | .UL FILE\ *freopen(filename,\ type,\ ioptr)\ char\ *filename,\ *type;\ FILE\ *ioptr; | |
118 | .nr PD 0 | |
119 | .IP | |
120 | .br | |
121 | The stream named by | |
122 | .UL ioptr | |
123 | is closed, if necessary, and then reopened | |
124 | as if by | |
125 | .UL fopen . | |
126 | If the attempt to open fails, | |
127 | .UL NULL | |
128 | is returned, | |
129 | otherwise | |
130 | .UL ioptr , | |
131 | which will now refer to the new file. | |
132 | Often the reopened stream is | |
133 | .UL stdin | |
134 | or | |
135 | .UL stdout . | |
136 | .nr PD .4v | |
137 | .LP | |
138 | .UL int\ getc(ioptr)\ FILE\ *ioptr; | |
139 | .nr PD 0 | |
140 | .IP | |
141 | returns the next character from the stream named by | |
142 | .UL ioptr , | |
143 | which is a pointer to a file such as returned by | |
144 | .UL fopen , | |
145 | or the name | |
146 | .UL stdin . | |
147 | The integer | |
148 | .UL EOF | |
149 | is returned on end-of-file or when | |
150 | an error occurs. | |
151 | The null character | |
152 | .UL \e0 | |
153 | is a legal character. | |
154 | .nr PD .4v | |
155 | .LP | |
156 | .UL int\ fgetc(ioptr)\ FILE\ *ioptr; | |
157 | .nr PD 0 | |
158 | .IP | |
159 | .br | |
160 | acts like | |
161 | .UL getc | |
162 | but is a genuine function, | |
163 | not a macro, | |
164 | so it can be pointed to, passed as an argument, etc. | |
165 | .nr PD .4v | |
166 | .LP | |
167 | .UL putc(c,\ ioptr)\ FILE\ *ioptr; | |
168 | .nr PD 0 | |
169 | .IP | |
170 | .br | |
171 | .UL putc | |
172 | writes the character | |
173 | .UL c | |
174 | on the output stream named by | |
175 | .UL ioptr , | |
176 | which is a value returned from | |
177 | .UL fopen | |
178 | or perhaps | |
179 | .UL stdout | |
180 | or | |
181 | .UL stderr . | |
182 | The character is returned as value, | |
183 | but | |
184 | .UL EOF | |
185 | is returned on error. | |
186 | .nr PD .4v | |
187 | .LP | |
188 | .UL fputc(c,\ ioptr)\ FILE\ *ioptr; | |
189 | .nr PD 0 | |
190 | .IP | |
191 | .br | |
192 | acts like | |
193 | .UL putc | |
194 | but is a genuine | |
195 | function, not a macro. | |
196 | .nr PD .4v | |
197 | .LP | |
198 | .UL fclose(ioptr)\ FILE\ *ioptr; | |
199 | .nr PD 0 | |
200 | .IP | |
201 | .br | |
202 | The file corresponding to | |
203 | .UL ioptr | |
204 | is closed after any buffers are emptied. | |
205 | A buffer allocated by the I/O system is freed. | |
206 | .UL fclose | |
207 | is automatic on normal termination of the program. | |
208 | .nr PD .4v | |
209 | .LP | |
210 | .UL fflush(ioptr)\ FILE\ *ioptr; | |
211 | .nr PD 0 | |
212 | .IP | |
213 | .br | |
214 | Any buffered information on the (output) stream named by | |
215 | .UL ioptr | |
216 | is written out. | |
217 | Output files are normally buffered | |
218 | if and only if they are not directed to the terminal; | |
219 | however, | |
220 | .UL stderr | |
221 | always starts off unbuffered and remains so unless | |
222 | .UL setbuf | |
223 | is used, or unless it is reopened. | |
224 | .nr PD .4v | |
225 | .LP | |
226 | .UL exit(errcode); | |
227 | .nr PD 0 | |
228 | .IP | |
229 | .br | |
230 | terminates the process and returns its argument as status | |
231 | to the parent. | |
232 | This is a special version of the routine | |
233 | which calls | |
234 | .UL fflush | |
235 | for each output file. | |
236 | To terminate without flushing, | |
237 | use | |
238 | .UL _exit . | |
239 | .nr PD .4v | |
240 | .LP | |
241 | .UL feof(ioptr)\ FILE\ *ioptr; | |
242 | .nr PD 0 | |
243 | .IP | |
244 | .br | |
245 | returns non-zero when end-of-file | |
246 | has occurred on the specified input stream. | |
247 | .nr PD .4v | |
248 | .LP | |
249 | .UL ferror(ioptr)\ FILE\ *ioptr; | |
250 | .nr PD 0 | |
251 | .IP | |
252 | .br | |
253 | returns non-zero when an error has occurred while reading | |
254 | or writing the named stream. | |
255 | The error indication lasts until the file has been closed. | |
256 | .nr PD .4v | |
257 | .LP | |
258 | .UL getchar(); | |
259 | .nr PD 0 | |
260 | .IP | |
261 | .br | |
262 | is identical to | |
263 | .UL getc(stdin) . | |
264 | .nr PD .4v | |
265 | .LP | |
266 | .UL putchar(c); | |
267 | .nr PD 0 | |
268 | .IP | |
269 | .br | |
270 | is identical to | |
271 | .UL putc(c,\ stdout) . | |
272 | .nr PD .4v | |
273 | .nr PD .4v | |
274 | .ne 2 | |
275 | .LP | |
276 | .UL char\ *fgets(s,\ n,\ ioptr)\ char\ *s;\ FILE\ *ioptr; | |
277 | .nr PD 0 | |
278 | .IP | |
279 | .br | |
280 | reads up to | |
281 | .UL n-1 | |
282 | characters from the stream | |
283 | .UL ioptr | |
284 | into the character pointer | |
285 | .UL s . | |
286 | The read terminates with a newline character. | |
287 | The newline character is placed in the buffer | |
288 | followed by a null character. | |
289 | .UL fgets | |
290 | returns the first argument, | |
291 | or | |
292 | .UL NULL | |
293 | if error or end-of-file occurred. | |
294 | .nr PD .4v | |
295 | .nr PD .4v | |
296 | .LP | |
297 | .UL fputs(s,\ ioptr)\ char\ *s;\ FILE\ *ioptr; | |
298 | .nr PD 0 | |
299 | .IP | |
300 | .br | |
301 | writes the null-terminated string (character array) | |
302 | .UL s | |
303 | on the stream | |
304 | .UL ioptr . | |
305 | No newline is appended. | |
306 | No value is returned. | |
307 | .nr PD .4v | |
308 | .LP | |
309 | .UL ungetc(c,\ ioptr)\ FILE\ *ioptr; | |
310 | .nr PD 0 | |
311 | .IP | |
312 | .br | |
313 | The argument character | |
314 | .UL c | |
315 | is pushed back on the input stream named by | |
316 | .UL ioptr . | |
317 | Only one character may be pushed back. | |
318 | .ne 5 | |
319 | .nr PD .4v | |
320 | .LP | |
321 | .UL printf(format,\ a1,\ ...)\ char\ *format; | |
322 | .br | |
323 | .UL fprintf(ioptr,\ format,\ a1,\ ...)\ FILE\ *ioptr;\ char\ *format; | |
324 | .br | |
325 | .UL sprintf(s,\ format,\ a1,\ ...)char\ *s,\ *format; | |
326 | .br | |
327 | .nr PD 0 | |
328 | .IP | |
329 | .UL printf | |
330 | writes on the standard output. | |
331 | .UL fprintf | |
332 | writes on the named output stream. | |
333 | .UL sprintf | |
334 | puts characters in the character array (string) | |
335 | named by | |
336 | .UL s . | |
337 | The specifications are as described in section | |
338 | .UL printf (3) | |
339 | of the | |
340 | .ul | |
341 | .UC UNIX | |
342 | .ul | |
343 | Programmer's Manual. | |
344 | .nr PD .4v | |
345 | .LP | |
346 | .UL scanf(format,\ a1,\ ...)\ char\ *format; | |
347 | .br | |
348 | .UL fscanf(ioptr,\ format,\ a1,\ ...)\ FILE\ *ioptr;\ char\ *format; | |
349 | .br | |
350 | .UL sscanf(s,\ format,\ a1,\ ...)\ char\ *s,\ *format; | |
351 | .nr PD 0 | |
352 | .IP | |
353 | .br | |
354 | .UL scanf | |
355 | reads from the standard input. | |
356 | .UL fscanf | |
357 | reads from the named input stream. | |
358 | .UL sscanf | |
359 | reads from the character string | |
360 | supplied as | |
361 | .UL s . | |
362 | .UL scanf | |
363 | reads characters, interprets | |
364 | them according to a format, and stores the results in its arguments. | |
365 | Each routine expects as arguments | |
366 | a control string | |
367 | .UL format , | |
368 | and a set of arguments, | |
369 | .I | |
370 | each of which must be a pointer, | |
371 | .R | |
372 | indicating where the converted input should be stored. | |
373 | .if t .sp .4v | |
374 | .UL scanf | |
375 | returns as its value the number of successfully matched and assigned input | |
376 | items. | |
377 | This can be used to decide how many input items were found. | |
378 | On end of file, | |
379 | .UL EOF | |
380 | is returned; note that this is different | |
381 | from 0, which means that the next input character does not | |
382 | match what was called for in the control string. | |
383 | .RE | |
384 | .nr PD .4v | |
385 | .LP | |
386 | .UL fread(ptr,\ sizeof(*ptr),\ nitems,\ ioptr)\ FILE\ *ioptr; | |
387 | .nr PD 0 | |
388 | .IP | |
389 | .br | |
390 | reads | |
391 | .UL nitems | |
392 | of data beginning at | |
393 | .UL ptr | |
394 | from file | |
395 | .UL ioptr . | |
396 | No advance notification | |
397 | that binary I/O is being done is required; | |
398 | when, for portability reasons, | |
399 | it becomes required, it will be done | |
400 | by adding an additional character to the mode-string on the | |
401 | .UL fopen | |
402 | call. | |
403 | .nr PD .4v | |
404 | .LP | |
405 | .UL fwrite(ptr,\ sizeof(*ptr),\ nitems,\ ioptr)\ FILE\ *ioptr; | |
406 | .nr PD 0 | |
407 | .IP | |
408 | .br | |
409 | Like | |
410 | .UL fread , | |
411 | but in the other direction. | |
412 | .nr PD .4v | |
413 | .LP | |
414 | .UL rewind(ioptr)\ FILE\ *ioptr; | |
415 | .nr PD 0 | |
416 | .IP | |
417 | .br | |
418 | rewinds the stream | |
419 | named by | |
420 | .UL ioptr . | |
421 | It is not very useful except on input, | |
422 | since a rewound output file is still open only for output. | |
423 | .nr PD .4v | |
424 | .LP | |
425 | .UL system(string)\ char\ *string; | |
426 | .nr PD 0 | |
427 | .IP | |
428 | .br | |
429 | The | |
430 | .UL string | |
431 | is executed by the shell as if typed at the terminal. | |
432 | .nr PD .4v | |
433 | .LP | |
434 | .UL getw(ioptr)\ FILE\ *ioptr; | |
435 | .nr PD 0 | |
436 | .IP | |
437 | .br | |
438 | returns the next word from the input stream named by | |
439 | .UL ioptr . | |
440 | .UL EOF | |
441 | is returned on end-of-file or error, | |
442 | but since this a perfectly good | |
443 | integer | |
444 | .UL feof | |
445 | and | |
446 | .UL ferror | |
447 | should be used. | |
448 | A ``word'' is 16 bits on the | |
449 | .UC PDP-11. | |
450 | .nr PD .4v | |
451 | .LP | |
452 | .UL putw(w,\ ioptr)\ FILE\ *ioptr; | |
453 | .nr PD 0 | |
454 | .IP | |
455 | .br | |
456 | writes the integer | |
457 | .UL w | |
458 | on the named output stream. | |
459 | .nr PD .4v | |
460 | .LP | |
461 | .UL setbuf(ioptr,\ buf)\ FILE\ *ioptr;\ char\ *buf; | |
462 | .nr PD 0 | |
463 | .IP | |
464 | .br | |
465 | .UL setbuf | |
466 | may be used after a stream has been opened | |
467 | but before I/O has started. | |
468 | If | |
469 | .UL buf | |
470 | is | |
471 | .UL NULL , | |
472 | the stream will be unbuffered. | |
473 | Otherwise the buffer supplied will be used. | |
474 | It must be a character array of sufficient size: | |
475 | .P1 | |
476 | char buf[BUFSIZ]; | |
477 | .P2 | |
478 | .nr PD .4v | |
479 | .LP | |
480 | .UL fileno(ioptr)\ FILE\ *ioptr; | |
481 | .nr PD 0 | |
482 | .IP | |
483 | .br | |
484 | returns the integer file descriptor associated with the file. | |
485 | .nr PD .4v | |
486 | .LP | |
487 | .UL fseek(ioptr,\ offset,\ ptrname)\ FILE\ *ioptr;\ long\ offset; | |
488 | .nr PD 0 | |
489 | .IP | |
490 | .br | |
491 | The location of the next byte in the stream | |
492 | named by | |
493 | .UL ioptr | |
494 | is adjusted. | |
495 | .UL offset | |
496 | is a long integer. | |
497 | If | |
498 | .UL ptrname | |
499 | is 0, the offset is measured from the beginning of the file; | |
500 | if | |
501 | .UL ptrname | |
502 | is 1, the offset is measured from the current read or | |
503 | write pointer; | |
504 | if | |
505 | .UL ptrname | |
506 | is 2, the offset is measured from the end of the file. | |
507 | The routine accounts properly for any buffering. | |
508 | (When this routine is used on | |
509 | .UC UNIX \& non- | |
510 | systems, | |
511 | the offset must be a value returned from | |
512 | .UL ftell | |
513 | and the ptrname must be 0). | |
514 | .ne 3 | |
515 | .nr PD .4v | |
516 | .LP | |
517 | .UL long\ ftell(ioptr)\ FILE\ *ioptr; | |
518 | .nr PD 0 | |
519 | .IP | |
520 | .br | |
521 | The byte offset, measured from the beginning of the file, | |
522 | associated with the named stream is returned. | |
523 | Any buffering is properly accounted for. | |
524 | (On | |
525 | .UC UNIX \& non- | |
526 | systems the value of this call is useful only | |
527 | for handing to | |
528 | .UL fseek , | |
529 | so as to position the file to the same place it was when | |
530 | .UL ftell | |
531 | was called.) | |
532 | .nr PD .4v | |
533 | .LP | |
534 | .UL getpw(uid,\ buf)\ char\ *buf; | |
535 | .nr PD 0 | |
536 | .IP | |
537 | .br | |
538 | The password file is searched for the given integer user ID. | |
539 | If an appropriate line is found, it is copied into | |
540 | the character array | |
541 | .UL buf , | |
542 | and 0 is returned. | |
543 | If no line is found corresponding to the user ID | |
544 | then 1 is returned. | |
545 | .nr PD .4v | |
546 | .LP | |
547 | .UL char\ *malloc(num); | |
548 | .nr PD 0 | |
549 | .IP | |
550 | .br | |
551 | allocates | |
552 | .UL num | |
553 | bytes. | |
554 | The pointer returned is sufficiently well aligned to be usable for any purpose. | |
555 | .UL NULL | |
556 | is returned if no space is available. | |
557 | .nr PD .4v | |
558 | .LP | |
559 | .UL char\ *calloc(num,\ size); | |
560 | .nr PD 0 | |
561 | .IP | |
562 | .br | |
563 | allocates space for | |
564 | .UL num | |
565 | items each of size | |
566 | .UL size . | |
567 | The space is guaranteed to be set to 0 and the pointer is | |
568 | sufficiently well aligned to be usable for any purpose. | |
569 | .UL NULL | |
570 | is returned if no space is available . | |
571 | .nr PD .4v | |
572 | .LP | |
573 | .UL cfree(ptr)\ char\ *ptr; | |
574 | .nr PD 0 | |
575 | .IP | |
576 | .br | |
577 | Space is returned to the pool used by | |
578 | .UL calloc . | |
579 | Disorder can be expected if the pointer was not obtained | |
580 | from | |
581 | .UL calloc . | |
582 | .nr PD .4v | |
583 | .LP | |
584 | The following are macros whose definitions may be obtained by including | |
585 | .UL <ctype.h> . | |
586 | .nr PD .4v | |
587 | .LP | |
588 | .UL isalpha(c) | |
589 | returns non-zero if the argument is alphabetic. | |
590 | .nr PD .4v | |
591 | .LP | |
592 | .UL isupper(c) | |
593 | returns non-zero if the argument is upper-case alphabetic. | |
594 | .nr PD .4v | |
595 | .LP | |
596 | .UL islower(c) | |
597 | returns non-zero if the argument is lower-case alphabetic. | |
598 | .nr PD .4v | |
599 | .LP | |
600 | .UL isdigit(c) | |
601 | returns non-zero if the argument is a digit. | |
602 | .nr PD .4v | |
603 | .LP | |
604 | .UL isspace(c) | |
605 | returns non-zero if the argument is a spacing character: | |
606 | tab, newline, carriage return, vertical tab, | |
607 | form feed, space. | |
608 | .nr PD .4v | |
609 | .LP | |
610 | .UL ispunct(c) | |
611 | returns non-zero if the argument is | |
612 | any punctuation character, i.e., not a space, letter, | |
613 | digit or control character. | |
614 | .nr PD .4v | |
615 | .LP | |
616 | .UL isalnum(c) | |
617 | returns non-zero if the argument is a letter or a digit. | |
618 | .nr PD .4v | |
619 | .LP | |
620 | .UL isprint(c) | |
621 | returns non-zero if the argument is printable \(em | |
622 | a letter, digit, or punctuation character. | |
623 | .nr PD .4v | |
624 | .LP | |
625 | .UL iscntrl(c) | |
626 | returns non-zero if the argument is a control character. | |
627 | .nr PD .4v | |
628 | .LP | |
629 | .UL isascii(c) | |
630 | returns non-zero if the argument is an ascii character, i.e., less than octal 0200. | |
631 | .nr PD .4v | |
632 | .LP | |
633 | .UL toupper(c) | |
634 | returns the upper-case character corresponding to the lower-case | |
635 | letter | |
636 | .UL c. | |
637 | .nr PD .4v | |
638 | .LP | |
639 | .UL tolower(c) | |
640 | returns the lower-case character corresponding to the upper-case | |
641 | letter | |
642 | .UL c . |