stdio man page on Solaris

Man page or keyword search:  
man Server   20652 pages
apropos Keyword Search (all sections)
Output format
Solaris logo
[printable version]

stdio(3C)		 Standard C Library Functions		     stdio(3C)

NAME
       stdio - standard buffered input/output package

SYNOPSIS
       #include <stdio.h>

       extern FILE *stdin;

       extern FILE *stdout;

       extern FILE *stderr;

DESCRIPTION
       The  standard I/O functions described in section 3C of this manual con‐
       stitute 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)
       function 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:

       stdin	       standard input file

       stdout	       standard output file

       stderr	       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 setbuf() 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
       duplicates  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 excep‐
       tion does include the file descriptor underlying a stream, whether cre‐
       ated 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
       future active handle). The second handle then becomes the  active  han‐
       dle.  All  activity by the application affecting the file offset on the
       first handle shall be suspended until it again becomes the active  han‐
       dle.  (If  a stream function has as an underlying function that affects
       the file offset, the stream function will be considered to  affect  the
       file offset.  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
       accessed, that they will both be in  a  state  where  the  other	 could
       become  the  active  handle  first. The application shall prepare for a
       fork() exactly 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
	   apply.  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 char‐
		   acter 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 taken.

	       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 underlying open file description	 refers	 to  a	device
		   that	 is capable of seeking, either an fflush() shall occur
		   or the stream shall be closed.

	       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 han‐
	   dle) to an appropriate location.

       3.  If the active handle ceases to be accessible	 before	 the  require‐
	   ments  on  the  first  handle above have been met, the state of the
	   open file description becomes undefined.   This  might  occur,  for
	   example, during 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 image.

       5.  Implementation shall assure that an application, even one  consist‐
	   ing	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 fol‐
	   lowed, it is implementation defined whether, and under what	condi‐
	   tions, 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;
       flockfile(iop);
       fprintf(iop, "hello ");
       fprintf(iop, "world);
       fputc(iop, 'a');
       funlockfile(iop);

       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:

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

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

SEE ALSO
       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),
       ungetc(3C)

SunOS 5.10			  18 May 2005			     stdio(3C)
[top]

List of man pages available for Solaris

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net