Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
STDIO(3)		 BSD Library Functions Manual		      STDIO(3)

NAME
     stdio -- standard input/output library functions

LIBRARY
     Standard C	Library	(libc, -lc)

SYNOPSIS
     #include <stdio.h>

     FILE *stdin;
     FILE *stdout;
     FILE *stderr;

DESCRIPTION
     The standard I/O library provides a simple	and efficient buffered stream
     I/O interface.  Input and output is mapped	into logical data streams and
     the physical I/O characteristics are concealed.

     A stream is associated with an external file (which may be	a physical de-
     vice) by opening a	file, which may	involve	creating a new file.  Creating
     an	existing file causes its former	contents to be discarded.  If a	file
     can support positioning requests (such as a disk file, as opposed to a
     terminal) then a file position indicator associated with the stream is
     positioned	at the start of	the file (byte zero), unless the file is
     opened with append	mode.  If append mode is used, the position indicator
     will be placed the	end-of-file.  The position indicator is	maintained by
     subsequent	reads, writes and positioning requests.	 All input occurs as
     if	the characters were read by successive calls to	the fgetc(3) function;
     all output	takes place as if all characters were read by successive calls
     to	the fputc(3) function.

     A file is disassociated from a stream by closing the file.	 Output
     streams are flushed (any unwritten	buffer contents	are transferred	to the
     host environment) before the stream is disassociated from the file.  The
     value of a	pointer	to a FILE object is indeterminate after	a file is
     closed (garbage).

     A file may	be subsequently	reopened, by the same or another program exe-
     cution, and its contents reclaimed	or modified (if	it can be repositioned
     at	the start).  If	the main function returns to its original caller, or
     the exit(3) function is called, all open files are	closed (hence all out-
     put streams are flushed) before program termination.  Other methods of
     program termination, such as abort(3) do not bother about closing files
     properly.

     This implementation needs and makes no distinction	between	"text" and
     "binary" streams.	In effect, all streams are binary.  No translation is
     performed and no extra padding appears on any stream.

     At	program	startup, three streams are predefined and need not be opened
     explicitly:

	   1.	standard input for reading conventional	input,

	   2.	standard output	for writing conventional output, and

	   3.	standard error for writing diagnostic output.

     These streams are abbreviated stdin, stdout, and stderr.

     Initially,	the standard error stream is unbuffered; the standard input
     and output	streams	are fully buffered if and only if the streams do not
     refer to an interactive or	"terminal" device, as determined by the
     isatty(3) function.  In fact, all freshly-opened streams that refer to
     terminal devices default to line buffering, and pending output to such
     streams is	written	automatically whenever an such an input	stream is
     read.  Note that this applies only	to "true reads"; if the	read request
     can be satisfied by existing buffered data, no automatic flush will oc-
     cur.  In these cases, or when a large amount of computation is done after
     printing part of a	line on	an output terminal, it is necessary to
     fflush(3) the standard output before going	off and	computing so that the
     output will appear.  Alternatively, these defaults	may be modified	via
     the setvbuf(3) function.

IMPLEMENTATION NOTES
     In	multi-threaded applications, operations	on streams perform implicit
     locking, except for the getc_unlocked(), getchar_unlocked(),
     putc_unlocked(), and putchar_unlocked() functions.	 Explicit control of
     stream locking is available through the flockfile(), ftrylockfile(), and
     funlockfile() functions .

     The following are defined as macros; these	names may not be re-used with-
     out first removing	their current definitions with #undef: BUFSIZ, EOF,
     FILENAME_MAX, FOPEN_MAX, L_cuserid, L_ctermid, L_tmpnam, NULL, SEEK_END,
     SEEK_SET, SEE_CUR,	TMP_MAX, clearerr(), feof(), ferror(), fileno(),
     freopen(),	fwopen(), getc(), getc_unlocked(), getchar(),
     getchar_unlocked(), putc(), putc_unlocked(), putchar(),
     putchar_unlocked(), stderr, stdin,	stdout.

     Function versions of the macro functions feof(), ferror(),	clearerr(),
     fileno(), getc(), getc_unlocked(),	getchar(), getchar_unlocked(), putc(),
     putc_unlocked(), putchar(), and putchar_unlocked()	exist and will be used
     if	the macros definitions are explicitly removed.

SEE ALSO
     close(2), open(2),	read(2), write(2)

STANDARDS
     The stdio library conforms	to ANSI	X3.159-1989 ("ANSI C89").

LIST OF	FUNCTIONS
     Function		 Description
     clearerr		 check and reset stream	status
     fclose		 close a stream
     fdopen		 stream	open functions
     feof		 check and reset stream	status
     ferror		 check and reset stream	status
     fflush		 flush a stream
     fgetc		 get next character or word from input stream
     fgetln		 get a line from a stream
     fgetpos		 reposition a stream
     fgets		 get a line from a stream
     fgetwc		 get next wide character from input stream
     fileno		 check and reset stream	status
     flockfile		 lock a	stream
     fopen		 stream	open functions
     fprintf		 formatted output conversion
     fpurge		 flush a stream
     fputc		 output	a character or word to a stream
     fputs		 output	a line to a stream
     fputwc		 output	a wide character to a stream
     fread		 binary	stream input/output
     freopen		 stream	open functions
     fropen		 open a	stream
     fscanf		 input format conversion
     fseek		 reposition a stream
     fsetpos		 reposition a stream
     ftell		 reposition a stream
     ftrylockfile	 lock a	stream (non-blocking)
     funlockfile	 unlock	a stream
     funopen		 open a	stream
     fwide		 set/get orientation of	a stream
     fwopen		 open a	stream
     fwrite		 binary	stream input/output
     getc		 get next character or word from input stream
     getc_unlocked	 get next character or word from input stream
			 (no implicit locking)
     getchar		 get next character or word from input stream
     getchar_unlocked	 get next character or word from input stream
			 (no implicit locking)
     getdelim		 get a delimited record	from a stream
     getline		 get a line from a stream
     gets		 get a line from a stream
     getw		 get next character or word from input stream
     getwc		 get next wide character from input stream
     getwchar		 get next wide character from input stream
     mkstemp		 create	unique temporary file
     mktemp		 create	unique temporary file
     perror		 system	error messages
     printf		 formatted output conversion
     putc		 output	a character or word to a stream
     putc_unlocked	 output	a character or word to a stream
			 (no implicit locking)
     putchar		 output	a character or word to a stream
     putchar_unlocked	 output	a character or word to a stream
			 (no implicit locking)
     puts		 output	a line to a stream
     putw		 output	a character or word to a stream
     putwc		 output	a wide character to a stream
     putwchar		 output	a wide character to a stream
     remove		 remove	directory entry
     rewind		 reposition a stream
     scanf		 input format conversion
     setbuf		 stream	buffering operations
     setbuffer		 stream	buffering operations
     setlinebuf		 stream	buffering operations
     setvbuf		 stream	buffering operations
     snprintf		 formatted output conversion
     sprintf		 formatted output conversion
     sscanf		 input format conversion
     strerror		 system	error messages
     sys_errlist	 system	error messages
     sys_nerr		 system	error messages
     tempnam		 temporary file	routines
     tmpfile		 temporary file	routines
     tmpnam		 temporary file	routines
     ungetc		 un-get	character from input stream
     ungetwc		 un-get	wide character from input stream
     vfprintf		 formatted output conversion
     vfscanf		 input format conversion
     vprintf		 formatted output conversion
     vscanf		 input format conversion
     vsnprintf		 formatted output conversion
     vsprintf		 formatted output conversion
     vsscanf		 input format conversion

BUGS
     The standard buffered functions do	not interact well with certain other
     library and system	functions, especially vfork(2) and abort(3).

BSD				  May 5, 2010				   BSD

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | IMPLEMENTATION NOTES | SEE ALSO | STANDARDS | LIST OF FUNCTIONS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=stdio&sektion=3&manpath=NetBSD+6.0>

home | help