stdio man page on SmartOS

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

STDIO(3C)							     STDIO(3C)

       stdio, stdin, stdout, stderr - standard buffered input/output package

       #include <stdio.h>

       extern FILE *stdin;

       extern FILE *stdout;

       extern FILE *stderr;

       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) 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
       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
       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
       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

	       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 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

	       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  applica‐
		  tion	shall perform an lseek() or an fseek(3C) (as appropri‐
		  ate to the type of the handle) to an appropriate 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, 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, inde‐
		  pendent of what streams or file descriptors may be available
		  to the new process image.

	   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 han‐
		  dles	used.  If the rules above are not followed, the result
		  is unspecified. When these rules are followed, it is	imple‐
		  mentation  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

	 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),

				 May 18, 2005			     STDIO(3C)

List of man pages available for SmartOS

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]
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