| 1 | .\" Copyright (c) 1990, 1991 Regents of the University of California. |
| 2 | .\" All rights reserved. |
| 3 | .\" |
| 4 | .\" Redistribution and use in source and binary forms, with or without |
| 5 | .\" modification, are permitted provided that the following conditions |
| 6 | .\" are met: |
| 7 | .\" 1. Redistributions of source code must retain the above copyright |
| 8 | .\" notice, this list of conditions and the following disclaimer. |
| 9 | .\" 2. Redistributions in binary form must reproduce the above copyright |
| 10 | .\" notice, this list of conditions and the following disclaimer in the |
| 11 | .\" documentation and/or other materials provided with the distribution. |
| 12 | .\" 3. All advertising materials mentioning features or use of this software |
| 13 | .\" must display the following acknowledgement: |
| 14 | .\" This product includes software developed by the University of |
| 15 | .\" California, Berkeley and its contributors. |
| 16 | .\" 4. Neither the name of the University nor the names of its contributors |
| 17 | .\" may be used to endorse or promote products derived from this software |
| 18 | .\" without specific prior written permission. |
| 19 | .\" |
| 20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
| 21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| 22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| 23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE |
| 24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
| 25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
| 26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| 27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| 28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
| 29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| 30 | .\" SUCH DAMAGE. |
| 31 | .\" |
| 32 | .\" @(#)stdio.3 6.5 (Berkeley) 5/6/91 |
| 33 | .\" |
| 34 | .Dd May 6, 1991 |
| 35 | .Dt STDIO 3 |
| 36 | .Os BSD 4 |
| 37 | .Sh NAME |
| 38 | .Nm stdio |
| 39 | .Nd standard input/output library functions |
| 40 | .Sh SYNOPSIS |
| 41 | .Fd #include <stdio.h> |
| 42 | .Fd FILE *stdin; |
| 43 | .Fd FILE *stdout; |
| 44 | .Fd FILE *stderr; |
| 45 | .Sh DESCRIPTION |
| 46 | The standard |
| 47 | .Tn I/O |
| 48 | library provides a simple and efficient buffered stream |
| 49 | .Tn I/O |
| 50 | interface. |
| 51 | Input and ouput is mapped into logical data streams |
| 52 | and the physical |
| 53 | .Tn I/O |
| 54 | characteristics are concealed. The functions and macros are listed |
| 55 | below; more information is available from the individual man pages. |
| 56 | .Pp |
| 57 | A stream is associated with an external file (which may be a physical |
| 58 | device) by |
| 59 | .Em opening |
| 60 | a file, which may involve creating a new file. Creating an |
| 61 | existing file causes its former contents to be discarded. |
| 62 | If a file can support positioning requests (such as a disk file, as opposed |
| 63 | to a terminal) then a |
| 64 | .Em file position indicator |
| 65 | associated with the stream is positioned at the start of the file (byte |
| 66 | zero), unless the file is opened with appened mode. If append mode |
| 67 | is used, the position indicator will be placed the end-of-file. |
| 68 | The position indicator is maintained by subsequent reads, writes |
| 69 | and positioning requests. All input occurs as if the characters |
| 70 | were read by successive calls to the |
| 71 | .Xr fgetc 3 |
| 72 | function; all ouput takes place as if all characters were |
| 73 | read by successive calls to the |
| 74 | .Xr fputc 3 |
| 75 | function. |
| 76 | .Pp |
| 77 | A file is disassociated from a stream by |
| 78 | .Em closing |
| 79 | the file. |
| 80 | Ouput streams are flushed (any unwritten buffer contents are transferred |
| 81 | to the host environment) before the stream is disassociated from the file. |
| 82 | The value of a pointer to a |
| 83 | .Dv FILE |
| 84 | object is indeterminate after a file is closed (garbage). |
| 85 | .Pp |
| 86 | A file may be subsequently reopened, by the same or another program |
| 87 | execution, and its contents reclaimed or modified (if it can be repositioned |
| 88 | at the start). If the main function returns to its original caller, or |
| 89 | the |
| 90 | .Xr exit 3 |
| 91 | function is called, all open files are closed (hence all output |
| 92 | streams are flushed) before program termination. Other methods |
| 93 | of program termination, such as |
| 94 | .Xr abort 3 |
| 95 | do not bother about closing files properly. |
| 96 | .Pp |
| 97 | At program startup, three text streams are predefined and need not be |
| 98 | opened explicitly |
| 99 | \(em |
| 100 | .Em standard input |
| 101 | (for reading converntional input), |
| 102 | \(em |
| 103 | .Em standard output |
| 104 | (for writing converntional input), |
| 105 | and |
| 106 | .Em standard error |
| 107 | (for writing diagnostic output). |
| 108 | These streams are abbreviated |
| 109 | .Em stdin , stdout |
| 110 | and |
| 111 | .Em stderr . |
| 112 | When opened, the standard error stream |
| 113 | is not fully buffered; the standard input and output streams are |
| 114 | fully buffered if and only if the streams do not to refer to |
| 115 | an interactive device. |
| 116 | .Pp |
| 117 | Output streams that refer to terminal devices |
| 118 | are always line buffered by default; |
| 119 | pending output to such streams is written automatically |
| 120 | whenever an input stream that refers to a terminal device is read. |
| 121 | In cases where a large amount of computation is done after printing |
| 122 | part of a line on an output terminal, it is necessary to |
| 123 | .Xr fflush 3 |
| 124 | the standard output before going off and computing so that the output |
| 125 | will appear. |
| 126 | .Pp |
| 127 | The |
| 128 | .Nm stdio |
| 129 | library is a part of the library |
| 130 | .Xr libc |
| 131 | and routines are automatically loaded as needed by the compilers |
| 132 | .Xr cc 1 |
| 133 | and |
| 134 | .Xr pc 1 . |
| 135 | The |
| 136 | .Tn SYNOPSIS |
| 137 | sections of the following manual pages indicate which include files |
| 138 | are to be used, what the compiler declaration for the function |
| 139 | looks like and which external variables are of interest. |
| 140 | .Pp |
| 141 | The following are defined as macros; |
| 142 | these names may not be re-used |
| 143 | without first removing their current definitions with |
| 144 | .Dv #undef : |
| 145 | .Dv BUFSIZ , |
| 146 | .Dv EOF , |
| 147 | .Dv FILENAME_MAX , |
| 148 | .DV FOPEN_MAX , |
| 149 | .Dv L_cuserid , |
| 150 | .Dv L_ctermid , |
| 151 | .Dv L_tmpnam, |
| 152 | .Dv NULL , |
| 153 | .Dv SEEK_END , |
| 154 | .Dv SEEK_SET , |
| 155 | .Dv SEE_CUR , |
| 156 | .Dv TMP_MAX , |
| 157 | .Dv clearerr , |
| 158 | .Dv feof , |
| 159 | .Dv ferror , |
| 160 | .Dv fileno , |
| 161 | .Dv fropen , |
| 162 | .Dv fwopen , |
| 163 | .Dv getc , |
| 164 | .Dv getchar , |
| 165 | .Dv putc , |
| 166 | .Dv putchar , |
| 167 | .Dv stderr , |
| 168 | .Dv stdin , |
| 169 | .Dv stdout . |
| 170 | Function versions of the macro functions |
| 171 | .Xr feof , |
| 172 | .Xr ferror , |
| 173 | .Xr clearerr , |
| 174 | .Xr fileno , |
| 175 | .Xr getc , |
| 176 | .Xr getchar , |
| 177 | .Xr putc , |
| 178 | and |
| 179 | .Xr putchar |
| 180 | exist and will be used if the macros |
| 181 | definitions are explicitly removed. |
| 182 | .Sh SEE ALSO |
| 183 | .Xr open 2 , |
| 184 | .Xr close 2 , |
| 185 | .Xr read 2 , |
| 186 | .Xr write 2 |
| 187 | .Sh BUGS |
| 188 | The standard buffered functions do not interact well with certain other |
| 189 | library and system functions, especially |
| 190 | .Xr vfork |
| 191 | and |
| 192 | .Xr abort . |
| 193 | .Sh STANDARDS |
| 194 | The |
| 195 | .Nm stdio |
| 196 | library conforms to |
| 197 | .St -ansiC . |
| 198 | .Sh LIST OF FUNCTIONS |
| 199 | .Bl -column "Description" |
| 200 | .Sy Function Description |
| 201 | clearerr check and reset stream status |
| 202 | fclose close a stream |
| 203 | fdopen stream open functions |
| 204 | feof check and reset stream status |
| 205 | ferror check and reset stream status |
| 206 | fflush flush a stream |
| 207 | fgetc get next character or word from input stream |
| 208 | fgetline get a line from a stream |
| 209 | fgetpos reposition a stream |
| 210 | fgets get a line from a stream |
| 211 | fileno check and reset stream status |
| 212 | fopen stream open functions |
| 213 | fprintf formatted output conversion |
| 214 | fpurge flush a stream |
| 215 | fputc output a character or word to a stream |
| 216 | fputs output a line to a stream |
| 217 | fread binary stream input/output |
| 218 | freopen stream open functions |
| 219 | fropen open a stream |
| 220 | fscanf input format conversion |
| 221 | fseek reposition a stream |
| 222 | fsetpos reposition a stream |
| 223 | ftell reposition a stream |
| 224 | funopen open a stream |
| 225 | fwopen open a stream |
| 226 | fwrite binary stream input/output |
| 227 | getc get next character or word from input stream |
| 228 | getchar get next character or word from input stream |
| 229 | gets get a line from a stream |
| 230 | getw get next character or word from input stream |
| 231 | mktemp make temporary file name (unique) |
| 232 | perror system error messages |
| 233 | printf formatted output conversion |
| 234 | putc output a character or word to a stream |
| 235 | putchar output a character or word to a stream |
| 236 | puts output a line to a stream |
| 237 | putw output a character or word to a stream |
| 238 | remove remove directory entry |
| 239 | rewind reposition a stream |
| 240 | scanf input format conversion |
| 241 | setbuf stream buffering operations |
| 242 | setbuffer stream buffering operations |
| 243 | setlinebuf stream buffering operations |
| 244 | setvbuf stream buffering operations |
| 245 | snprintf formatted output conversion |
| 246 | sprintf formatted output conversion |
| 247 | sscanf input format conversion |
| 248 | strerror system error messages |
| 249 | sys_errlist system error messages |
| 250 | sys_nerr system error messages |
| 251 | tempnam temporary file routines |
| 252 | tmpfile temporary file routines |
| 253 | tmpnam temporary file routines |
| 254 | ungetc un-get character from input stream |
| 255 | vfprintf formatted output conversion |
| 256 | vfscanf input format conversion |
| 257 | vprintf formatted output conversion |
| 258 | vscanf input format conversion |
| 259 | vsnprintf formatted output conversion |
| 260 | vsprintf formatted output conversion |
| 261 | vsscanf input format conversion |
| 262 | .El |