161180Sbostic.\" Copyright (c) 1990, 1991, 1993 261180Sbostic.\" The Regents of the University of California. All rights reserved. 320455Smckusick.\" 449264Scael.\" %sccs.include.redist.man% 520455Smckusick.\" 6*66955Sbostic.\" @(#)stdio.3 8.7 (Berkeley) 04/19/94 749264Scael.\" 849264Scael.Dd 949264Scael.Dt STDIO 3 1049264Scael.Os BSD 4 1149264Scael.Sh NAME 1249264Scael.Nm stdio 1349264Scael.Nd standard input/output library functions 1449264Scael.Sh SYNOPSIS 1549264Scael.Fd #include <stdio.h> 1649264Scael.Fd FILE *stdin; 1749264Scael.Fd FILE *stdout; 1849264Scael.Fd FILE *stderr; 1949264Scael.Sh DESCRIPTION 2049264ScaelThe standard 2149264Scael.Tn I/O 2249264Scaellibrary provides a simple and efficient buffered stream 2349264Scael.Tn I/O 2449264Scaelinterface. 2549264ScaelInput and ouput is mapped into logical data streams 2649264Scaeland the physical 2749264Scael.Tn I/O 2849264Scaelcharacteristics are concealed. The functions and macros are listed 2949264Scaelbelow; more information is available from the individual man pages. 3049264Scael.Pp 3149264ScaelA stream is associated with an external file (which may be a physical 3249264Scaeldevice) by 3349264Scael.Em opening 3449264Scaela file, which may involve creating a new file. Creating an 3549264Scaelexisting file causes its former contents to be discarded. 3649264ScaelIf a file can support positioning requests (such as a disk file, as opposed 3749264Scaelto a terminal) then a 3849264Scael.Em file position indicator 3949264Scaelassociated with the stream is positioned at the start of the file (byte 4065099Smckusickzero), unless the file is opened with appended mode. If append mode 4149264Scaelis used, the position indicator will be placed the end-of-file. 4249264ScaelThe position indicator is maintained by subsequent reads, writes 4349264Scaeland positioning requests. All input occurs as if the characters 4449264Scaelwere read by successive calls to the 4549264Scael.Xr fgetc 3 4649264Scaelfunction; all ouput takes place as if all characters were 4749264Scaelread by successive calls to the 4849264Scael.Xr fputc 3 4949264Scaelfunction. 5049264Scael.Pp 5149264ScaelA file is disassociated from a stream by 5249264Scael.Em closing 5349264Scaelthe file. 54*66955SbosticOuput streams are flushed (any unwritten buffer contents are transferred 5549264Scaelto the host environment) before the stream is disassociated from the file. 5649264ScaelThe value of a pointer to a 5749264Scael.Dv FILE 5849264Scaelobject is indeterminate after a file is closed (garbage). 5949264Scael.Pp 6049264ScaelA file may be subsequently reopened, by the same or another program 6149264Scaelexecution, and its contents reclaimed or modified (if it can be repositioned 6249264Scaelat the start). If the main function returns to its original caller, or 6349264Scaelthe 6449264Scael.Xr exit 3 6549264Scaelfunction is called, all open files are closed (hence all output 6649264Scaelstreams are flushed) before program termination. Other methods 6749264Scaelof program termination, such as 6849264Scael.Xr abort 3 6949264Scaeldo not bother about closing files properly. 7049264Scael.Pp 7164901StorekThis implementation needs and makes 7264901Storekno distinction between 7364901Storek.Dq text 7464901Storekand 7564901Storek.Dq binary 7664901Storekstreams. 7764901StorekIn effect, all streams are binary. 7864901StorekNo translation is performed and no extra padding appears on any stream. 7964901Storek.Pp 8064901StorekAt program startup, three streams are predefined and need not be 8164901Storekopened explicitly: 8264901Storek.Bl -bullet -compact -offset indent 8364901Storek.It 8449264Scael.Em standard input 8564899Sbostic(for reading conventional input), 8664901Storek.It 8749264Scael.Em standard output 8864901Storek(for writing conventional input), and 8964901Storek.It 9049264Scael.Em standard error 9149264Scael(for writing diagnostic output). 9264901Storek.El 9349264ScaelThese streams are abbreviated 9449264Scael.Em stdin , stdout 9520455Smckusickand 9649264Scael.Em stderr . 9764901StorekInitially, the standard error stream 9864901Storekis unbuffered; the standard input and output streams are 9965099Smckusickfully buffered if and only if the streams do not refer to 10064901Storekan interactive or 10164901Storek.Dq terminal 10264901Storekdevice, as determined by the 10364901Storek.Xr isatty 3 10464901Storekfunction. 10564901StorekIn fact, 10664901Storek.Em all 10764901Storekfreshly-opened streams that refer to terminal devices 10864901Storekdefault to line buffering, and 10946106Sbosticpending output to such streams is written automatically 11064901Storekwhenever an such an input stream is read. 11164901StorekNote that this applies only to 11264901Storek.Dq "true reads" ; 11364901Storekif the read request can be satisfied by existing buffered data, 11464901Storekno automatic flush will occur. 11564901StorekIn these cases, 11664901Storekor when a large amount of computation is done after printing 11746106Sbosticpart of a line on an output terminal, it is necessary to 11849264Scael.Xr fflush 3 11946106Sbosticthe standard output before going off and computing so that the output 12046106Sbosticwill appear. 12164901StorekAlternatively, these defaults may be modified via the 12264901Storek.Xr setvbuf 3 12364901Storekfunction. 12449264Scael.Pp 12549264ScaelThe 12649264Scael.Nm stdio 12749264Scaellibrary is a part of the library 12849264Scael.Xr libc 12949264Scaeland routines are automatically loaded as needed by the compilers 13049264Scael.Xr cc 1 13149264Scaeland 13249264Scael.Xr pc 1 . 13349264ScaelThe 13449264Scael.Tn SYNOPSIS 13549264Scaelsections of the following manual pages indicate which include files 13649264Scaelare to be used, what the compiler declaration for the function 13749264Scaellooks like and which external variables are of interest. 13849264Scael.Pp 13949264ScaelThe following are defined as macros; 14049264Scaelthese names may not be re-used 14149264Scaelwithout first removing their current definitions with 14249264Scael.Dv #undef : 14349264Scael.Dv BUFSIZ , 14449264Scael.Dv EOF , 14549264Scael.Dv FILENAME_MAX , 14649264Scael.DV FOPEN_MAX , 14749264Scael.Dv L_cuserid , 14849264Scael.Dv L_ctermid , 14949264Scael.Dv L_tmpnam, 15049264Scael.Dv NULL , 15149264Scael.Dv SEEK_END , 15249264Scael.Dv SEEK_SET , 15349264Scael.Dv SEE_CUR , 15449264Scael.Dv TMP_MAX , 15549264Scael.Dv clearerr , 15649264Scael.Dv feof , 15749264Scael.Dv ferror , 15849264Scael.Dv fileno , 15964898Sbostic.Dv freopen , 16049264Scael.Dv fwopen , 16149264Scael.Dv getc , 16249264Scael.Dv getchar , 16349264Scael.Dv putc , 16449264Scael.Dv putchar , 16549264Scael.Dv stderr , 16649264Scael.Dv stdin , 16749264Scael.Dv stdout . 16849264ScaelFunction versions of the macro functions 16949264Scael.Xr feof , 17049264Scael.Xr ferror , 17149264Scael.Xr clearerr , 17249264Scael.Xr fileno , 17349264Scael.Xr getc , 17449264Scael.Xr getchar , 17549264Scael.Xr putc , 17649264Scaeland 17749264Scael.Xr putchar 17849264Scaelexist and will be used if the macros 17949264Scaeldefinitions are explicitly removed. 18049264Scael.Sh SEE ALSO 18149264Scael.Xr open 2 , 18249264Scael.Xr close 2 , 18349264Scael.Xr read 2 , 18449264Scael.Xr write 2 18549264Scael.Sh BUGS 18620456SmckusickThe standard buffered functions do not interact well with certain other 18749264Scaellibrary and system functions, especially 18849264Scael.Xr vfork 18949264Scaeland 19049264Scael.Xr abort . 19149264Scael.Sh STANDARDS 19249264ScaelThe 19349264Scael.Nm stdio 19449264Scaellibrary conforms to 19549264Scael.St -ansiC . 19649264Scael.Sh LIST OF FUNCTIONS 19749264Scael.Bl -column "Description" 19849264Scael.Sy Function Description 19949264Scaelclearerr check and reset stream status 20049264Scaelfclose close a stream 20149264Scaelfdopen stream open functions 20249264Scaelfeof check and reset stream status 20349264Scaelferror check and reset stream status 20449264Scaelfflush flush a stream 20549264Scaelfgetc get next character or word from input stream 20649264Scaelfgetline get a line from a stream 20749264Scaelfgetpos reposition a stream 20849264Scaelfgets get a line from a stream 20949264Scaelfileno check and reset stream status 21049264Scaelfopen stream open functions 21149264Scaelfprintf formatted output conversion 21249264Scaelfpurge flush a stream 21349264Scaelfputc output a character or word to a stream 21449264Scaelfputs output a line to a stream 21549264Scaelfread binary stream input/output 21649264Scaelfreopen stream open functions 21749264Scaelfropen open a stream 21849264Scaelfscanf input format conversion 21949264Scaelfseek reposition a stream 22049264Scaelfsetpos reposition a stream 22149264Scaelftell reposition a stream 22249264Scaelfunopen open a stream 22349264Scaelfwopen open a stream 22449264Scaelfwrite binary stream input/output 22549264Scaelgetc get next character or word from input stream 22649264Scaelgetchar get next character or word from input stream 22749264Scaelgets get a line from a stream 22849264Scaelgetw get next character or word from input stream 22964897Sbosticmkstemp create unique temporary file 23064897Sbosticmktemp create unique temporary file 23149264Scaelperror system error messages 23249264Scaelprintf formatted output conversion 23349264Scaelputc output a character or word to a stream 23449264Scaelputchar output a character or word to a stream 23549264Scaelputs output a line to a stream 23649264Scaelputw output a character or word to a stream 23749264Scaelremove remove directory entry 23849264Scaelrewind reposition a stream 23949264Scaelscanf input format conversion 24049264Scaelsetbuf stream buffering operations 24149264Scaelsetbuffer stream buffering operations 24249264Scaelsetlinebuf stream buffering operations 24349264Scaelsetvbuf stream buffering operations 24449264Scaelsnprintf formatted output conversion 24549264Scaelsprintf formatted output conversion 24649264Scaelsscanf input format conversion 24749264Scaelstrerror system error messages 24849264Scaelsys_errlist system error messages 24949264Scaelsys_nerr system error messages 25049264Scaeltempnam temporary file routines 25149264Scaeltmpfile temporary file routines 25249264Scaeltmpnam temporary file routines 25349264Scaelungetc un-get character from input stream 25449264Scaelvfprintf formatted output conversion 25549264Scaelvfscanf input format conversion 25649264Scaelvprintf formatted output conversion 25749264Scaelvscanf input format conversion 25849264Scaelvsnprintf formatted output conversion 25949264Scaelvsprintf formatted output conversion 26049264Scaelvsscanf input format conversion 26149264Scael.El 262