| 1 | .TH STDIO 3S |
| 2 | .SH NAME |
| 3 | stdio \- standard buffered input/output package |
| 4 | .SH SYNOPSIS |
| 5 | .B #include <stdio.h> |
| 6 | .PP |
| 7 | .SM |
| 8 | .B FILE |
| 9 | .B *stdin; |
| 10 | .br |
| 11 | .SM |
| 12 | .B FILE |
| 13 | .B *stdout; |
| 14 | .br |
| 15 | .SM |
| 16 | .B FILE |
| 17 | .B *stderr; |
| 18 | .SH DESCRIPTION |
| 19 | The functions described in Sections 3S constitute an efficient |
| 20 | user-level buffering scheme. |
| 21 | The in-line macros |
| 22 | .I getc |
| 23 | and |
| 24 | .IR putc (3) |
| 25 | handle characters quickly. |
| 26 | The higher level routines |
| 27 | .I "gets, fgets, scanf, fscanf, fread," |
| 28 | .I "puts, fputs, printf, fprintf, fwrite" |
| 29 | all use |
| 30 | .I getc |
| 31 | and |
| 32 | .I putc; |
| 33 | they can be freely intermixed. |
| 34 | .PP |
| 35 | A file with associated buffering is called a |
| 36 | .I stream, |
| 37 | and is declared to be a pointer to a defined type |
| 38 | .SM |
| 39 | .B FILE. |
| 40 | .IR Fopen (3) |
| 41 | creates certain descriptive data for a stream |
| 42 | and returns a pointer to designate the stream in all |
| 43 | further transactions. |
| 44 | There are three normally open streams with constant |
| 45 | pointers declared in |
| 46 | the include file and associated with the standard open files: |
| 47 | .TP 10n |
| 48 | .BR stdin |
| 49 | standard input file |
| 50 | .br |
| 51 | .ns |
| 52 | .TP |
| 53 | .B stdout |
| 54 | standard output file |
| 55 | .br |
| 56 | .ns |
| 57 | .TP |
| 58 | .BR stderr |
| 59 | standard error file |
| 60 | .PP |
| 61 | A constant `pointer' |
| 62 | .SM |
| 63 | .B NULL |
| 64 | (0) |
| 65 | designates no stream at all. |
| 66 | .PP |
| 67 | An integer constant |
| 68 | .SM |
| 69 | .B EOF |
| 70 | (\-1) is returned |
| 71 | upon end of file or error by integer functions that |
| 72 | deal with streams. |
| 73 | .PP |
| 74 | Any routine that uses the standard input/output package |
| 75 | must include the header file <stdio.h> of pertinent |
| 76 | macro definitions. |
| 77 | The functions and constants mentioned in sections labeled 3S |
| 78 | are declared in the include file |
| 79 | and need no further declaration. |
| 80 | The constants, and the following `functions' are |
| 81 | implemented as macros; redeclaration of these names |
| 82 | is perilous: |
| 83 | .I getc, |
| 84 | .I getchar, |
| 85 | .I putc, |
| 86 | .I putchar, |
| 87 | .I feof, |
| 88 | .I ferror, |
| 89 | .IR fileno . |
| 90 | .SH "SEE ALSO" |
| 91 | open(2), close(2), read(2), write(2) |
| 92 | .SH DIAGNOSTICS |
| 93 | The value |
| 94 | .SM |
| 95 | .B EOF |
| 96 | is returned uniformly to indicate that a |
| 97 | .SM |
| 98 | .B FILE |
| 99 | pointer has not been initialized with |
| 100 | .I fopen, |
| 101 | input (output) has been attempted on an output (input) stream, |
| 102 | or a |
| 103 | .SM |
| 104 | .B FILE |
| 105 | pointer designates corrupt or otherwise unintelligible |
| 106 | .SM |
| 107 | .B FILE |
| 108 | data. |