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

FreeBSD Manual Pages


home | help
stdio(3C)		 Standard C Library Functions		     stdio(3C)

       stdio - standard	buffered input/output package

       #include	<stdio.h>

       extern FILE *stdin;

       extern FILE *stdout;

       extern FILE *stderr;

       The  functions  described  in  the entries of section 3S	of this	manual
       constitute an efficient,	user-level I/O buffering scheme.  The  in-line
       macros	getc()	and  putc()  handle  characters	 quickly.  The	macros
       getchar(3C) and putchar(3C), and	the higher-level  routines  fgetc(3C),
       fgets(3C),  fprintf(3C),	 fputc(3C),  fputs(3C),	fread(3C), fscanf(3C),
       fwrite(3C), gets	(3C), getw(3C),	printf(3C),  puts(3C),	putw(3C),  and
       scanf(3C)  all use or act as if they use	getc() and putc(); they	can be
       freely intermixed.

       A file with associated buffering	is called a stream (see	intro(3))  and
       is declared to be a pointer to a	defined	type FILE. The fopen(3C) func-
       tion creates certain descriptive	 data  for  a  stream  and  returns  a
       pointer	to designate the stream	in all further transactions. Normally,
       there are three open streams with constant  pointers  declared  in  the
       <stdio.h> header	and associated with the	standard open files:

	     standard input file

	     standard output file

	     standard error file

       The following symbolic values in	<unistd.h> define the file descriptors
       that will be associated with the	C-language stdin,  stdout  and	stderr
       when the	application is started:

       STDIN_FILENO	Standard input value	0     stdin
       STDOUT_FILENO	Standard output	value	1     stdout
       STDERR_FILENO	Standard error value	2     stderr

       The constant NULL designates a null pointer.

       The  integer-constant EOF is returned upon end-of-file or error by most
       integer functions that deal with	streams	(see the  individual  descrip-
       tions for details).

       The  integer  constant BUFSIZ specifies the size	of the buffers used by
       the particular implementation.

       The integer constant FILENAME_MAX specifies the number of bytes	needed
       to  hold	 the longest pathname of a file	allowed	by the implementation.
       If the system does not impose a maximum limit, this value is the	recom-
       mended size for a buffer	intended to hold a file's pathname.

       The  integer  constant  FOPEN_MAX specifies the minimum number of files
       that the	implementation guarantees can  be  open	 simultaneously.  Note
       that  no	more than 255 files may	be opened using	fopen(), and only file
       descriptors 0 through 255 can be	used in	a stream.

       The functions and constants mentioned in	the entries of section	3S  of
       this  manual  are  declared in that header and need no further declara-
       tion.  The constants and	the following "functions" are  implemented  as
       macros  (redeclaration  of these	names is perilous): getc(), getchar(),
       putc(), putchar(), ferror(3C), feof(3C),	clearerr(3C), and  fileno(3C).
       There   are  also  function  versions  of  getc(),  getchar(),  putc(),
       putchar(), ferror(), feof(), clearerr(),	and fileno().

       Output streams, with the	exception of the standard error	stream stderr,
       are  by	default	 buffered  if  the  output  refers to a	file and line-
       buffered	if the output refers to	a terminal. The	standard error	output
       stream  stderr  is  by  default	unbuffered,  but use of	freopen() (see
       fopen(3C)) will cause it	to become buffered or line-buffered.  When  an
       output  stream  is unbuffered, information is queued for	writing	on the
       destination file	or terminal as soon as written;	when it	 is  buffered,
       many  characters	 are saved up and written as a block. When it is line-
       buffered, each line of output is	queued for writing on the  destination
       terminal	 as  soon as the line is completed (that is, as	soon as	a new-
       line character is written or terminal input is  requested).   The  set-
       buf()  or  setvbuf() functions (both described on the setbuf(3C)	manual
       page) may be used to change the stream's	buffering strategy.

   Interactions	of Other FILE-Type C Functions
       A single	open file description can be accessed both through streams and
       through file descriptors.  Either a file	descriptor or a	stream will be
       called a	handle on the open file	description to	which  it  refers;  an
       open file description may have several handles.

       Handles	can  be	 created or destroyed by user action without affecting
       the underlying open file	description.  Some of the ways to create  them
       include fcntl(2), dup(2), fdopen(3C), fileno(3C)	and fork(2) (which du-
       plicates	existing ones into new processes). They	can be destroyed by at
       least  fclose(3C)  and  close(2),  and  by  the	 exec  functions  (see
       exec(2)), which close some file descriptors and destroy streams.

       A file descriptor that is never used in an operation and	 could	affect
       the file	offset (for example read(2), write(2), or
	lseek(2))  is  not  considered	a handle in this discussion, but could
       give rise to one	(as a consequence of  fdopen(),	dup(), or fork(),  for
       example).  This exception does include the file descriptor underlying a
       stream, whether created with  fopen() or	fdopen(), as long as it	is not
       used  directly  by  the	application  to	 affect	the file offset.  (The
       read()  and  write()  functions	implicitly  affect  the	 file  offset;
       lseek() explicitly affects it.)

       If two or more handles are used,	and any	one of them is a stream, their
       actions shall be	coordinated as described below.	 If this is not	 done,
       the result is undefined.

       A  handle  that	is  a stream is	considered to be closed	when either an
       fclose()	or freopen(3C) is executed on it (the result of	 freopen()  is
       a  new stream for this discussion, which	cannot be a handle on the same
       open file description as	its previous value) or when the	process	owning
       that  stream  terminates	the exit(2) or abort(3C). A file descriptor is
       closed by close(), _exit() (see exit(2)), or by one of the  exec	 func-
       tions when FD_CLOEXEC is	set on that file descriptor.

       For  a  handle  to  become the active handle, the actions below must be
       performed between the last other	user of	the first handle (the  current
       active  handle)	and the	first other user of the	second handle (the fu-
       ture active handle). The	second handle then becomes the active  handle.
       All  activity by	the application	affecting the file offset on the first
       handle shall be suspended until it again	becomes	the active handle. (If
       a  stream  function has as an underlying	function that affects the file
       offset, the stream function will	be considered to affect	the file  off-
       set.  The underlying functions are described below.)

       The  handles  need not be in the	same process for these rules to	apply.
       Note that after a fork(), two handles exist where one  existed  before.
       The  application	 shall	assure	that, if both handles will ever	be ac-
       cessed, that they will both be in a state where the other could	become
       the active handle first.	The application	shall prepare for a fork() ex-
       actly as	if it were a change of active handle.	(If  the  only	action
       performed  by  one  of  the  processes  is one of the exec functions or
       _exit(),	the handle is never accessed in	that process.)

       1. For the first	handle,	the first applicable condition below shall ap-
	  ply.	After  the actions required below are taken, the handle	may be
	  closed if it is still	open.

	  a. If	it is a	file descriptor, no action is required.

	  b. If	the only further action	to be performed	on any handle to  this
	     open file description is to close it, no action need be taken.

	  c. If	it is a	stream that is unbuffered, no action need be taken.

	  d. If	 it  is	 a stream that is line-buffered	and the	last character
	     written to	the stream was a newline (that is, as if a  putc('\n')
	     was  the most recent operation on that stream), no	action need be

	  e. If	it is a	stream that is open for	writing	 or  append  (but  not
	     also  open	 for reading), either an fflush(3C) shall occur	or the
	     stream shall be closed.

	  f. If	the stream is open for reading and it is at  the  end  of  the
	     file ( feof(3C) is	true), no action need be taken.

	  g. If	the stream is open with	a mode that allows reading and the un-
	     derlying open file	description refers to a	device that is capable
	     of	seeking, either	an fflush() shall occur	or the stream shall be

	  h. Otherwise,	the result is undefined.

       2. For the second handle: if any	previous active	handle	has  called  a
	  function that	explicitly changed the file offset, except as required
	  above	for the	first handle, the application shall perform an lseek()
	  or an	fseek(3C) (as appropriate to the type of the handle) to	an ap-
	  propriate location.

       3. If the active	handle ceases to be accessible before the requirements
	  on  the first	handle above have been met, the	state of the open file
	  description becomes undefined.  This might occur, for	example,  dur-
	  ing a	 fork()	or an _exit().

       4. The  exec  functions	shall  be  considered to make inaccessible all
	  streams that are open	at the time they are  called,  independent  of
	  what streams or file descriptors may be available to the new process

       5. Implementation shall assure that an application, even	one consisting
	  of  several  processes, shall	yield correct results (no data is lost
	  or duplicated	when writing, all data is written in order, except  as
	  requested by seeks) when the rules above are followed, regardless of
	  the sequence of handles used.	 If the	rules above are	not  followed,
	  the  result is unspecified. When these rules are followed, it	is im-
	  plementation defined whether,	and under what conditions,  all	 input
	  is seen exactly once.

   Use of stdio	in Multithreaded Applications
       All the stdio functions are safe	unless they have the _unlocked suffix.
       Each FILE pointer has its own lock to guarantee that  only  one	thread
       can  access  it.	 In the	case that output needs to be synchronized, the
       lock for	the FILE pointer can be	acquired before	performing a series of
       stdio operations.  For example:

       FILE iop;
       fprintf(iop, "hello ");
       fprintf(iop, "world);
       fputc(iop, 'a');

       will  print  everything out together, blocking other threads that might
       want to write to	the same file between calls to fprintf().

       An unlocked interface is	available in case performace is	an issue.
	For example:

       while (!feof(iop)) {
	       *c++ = getc_unlocked(iop);

       Invalid stream pointers usually cause grave disorder, possibly  includ-
       ing  program termination. Individual function descriptions describe the
       possible	error conditions.

       close(2), lseek(2), open(2), pipe(2), read(2),  write(2),  ctermid(3C),
       cuserid(3C),  fclose(3C),  ferror(3C), fopen(3C), fread(3C), fseek(3C),
       flockfile(3C), getc(3C),	 gets(3C),  popen(3C),	printf(3C),  putc(3C),
       puts(3C),  scanf(3C),  setbuf(3C), system(3C), tmpfile(3C), tmpnam(3C),

SunOS 5.9			  22 Jan 1993			     stdio(3C)


Want to link to this manual page? Use this URL:

home | help