1: @node I/O on Streams, Low-Level I/O, I/O Overview, Top
    2: @c %MENU% High-level, portable I/O facilities
    3: @chapter Input/Output on Streams
    4: @c fix an overfull:
    5: @tex
    6: \hyphenation{which-ever}
    7: @end tex
    8: 
    9: This chapter describes the functions for creating streams and performing
   10: input and output operations on them.  As discussed in @ref{I/O
   11: Overview}, a stream is a fairly abstract, high-level concept
   12: representing a communications channel to a file, device, or process.
   13: 
   14: @menu
   15: * Streams::                     About the data type representing a stream.
   16: * Standard Streams::            Streams to the standard input and output
   17:                                  devices are created for you.
   18: * Opening Streams::             How to create a stream to talk to a file.
   19: * Closing Streams::             Close a stream when you are finished with it.
   20: * Streams and Threads::         Issues with streams in threaded programs.
   21: * Streams and I18N::            Streams in internationalized applications.
   22: * Simple Output::               Unformatted output by characters and lines.
   23: * Character Input::             Unformatted input by characters and words.
   24: * Line Input::                  Reading a line or a record from a stream.
   25: * Unreading::                   Peeking ahead/pushing back input just read.
   26: * Block Input/Output::          Input and output operations on blocks of data.
   27: * Formatted Output::            @code{printf} and related functions.
   28: * Customizing Printf::          You can define new conversion specifiers for
   29:                                  @code{printf} and friends.
   30: * Formatted Input::             @code{scanf} and related functions.
   31: * EOF and Errors::              How you can tell if an I/O error happens.
   32: * Error Recovery::              What you can do about errors.
   33: * Binary Streams::              Some systems distinguish between text files
   34:                                  and binary files.
   35: * File Positioning::            About random-access streams.
   36: * Portable Positioning::        Random access on peculiar ISO C systems.
   37: * Stream Buffering::            How to control buffering of streams.
   38: * Other Kinds of Streams::      Streams that do not necessarily correspond
   39:                                  to an open file.
   40: * Formatted Messages::          Print strictly formatted messages.
   41: @end menu
   42: 
   43: @node Streams
   44: @section Streams
   45: 
   46: For historical reasons, the type of the C data structure that represents
   47: a stream is called @code{FILE} rather than ``stream''.  Since most of
   48: the library functions deal with objects of type @code{FILE *}, sometimes
   49: the term @dfn{file pointer} is also used to mean ``stream''.  This leads
   50: to unfortunate confusion over terminology in many books on C.  This
   51: manual, however, is careful to use the terms ``file'' and ``stream''
   52: only in the technical sense.
   53: @cindex file pointer
   54: 
   55: @pindex stdio.h
   56: The @code{FILE} type is declared in the header file @file{stdio.h}.
   57: 
   58: @comment stdio.h
   59: @comment ISO
   60: @deftp {Data Type} FILE
   61: This is the data type used to represent stream objects.  A @code{FILE}
   62: object holds all of the internal state information about the connection
   63: to the associated file, including such things as the file position
   64: indicator and buffering information.  Each stream also has error and
   65: end-of-file status indicators that can be tested with the @code{ferror}
   66: and @code{feof} functions; see @ref{EOF and Errors}.
   67: @end deftp
   68: 
   69: @code{FILE} objects are allocated and managed internally by the
   70: input/output library functions.  Don't try to create your own objects of
   71: type @code{FILE}; let the library do it.  Your programs should
   72: deal only with pointers to these objects (that is, @code{FILE *} values)
   73: rather than the objects themselves.
   74: @c !!! should say that FILE's have "No user-serviceable parts inside."
   75: 
   76: @node Standard Streams
   77: @section Standard Streams
   78: @cindex standard streams
   79: @cindex streams, standard
   80: 
   81: When the @code{main} function of your program is invoked, it already has
   82: three predefined streams open and available for use.  These represent
   83: the ``standard'' input and output channels that have been established
   84: for the process.
   85: 
   86: These streams are declared in the header file @file{stdio.h}.
   87: @pindex stdio.h
   88: 
   89: @comment stdio.h
   90: @comment ISO
   91: @deftypevar {FILE *} stdin
   92: The @dfn{standard input} stream, which is the normal source of input for the
   93: program.
   94: @end deftypevar
   95: @cindex standard input stream
   96: 
   97: @comment stdio.h
   98: @comment ISO
   99: @deftypevar {FILE *} stdout
  100: The @dfn{standard output} stream, which is used for normal output from
  101: the program.
  102: @end deftypevar
  103: @cindex standard output stream
  104: 
  105: @comment stdio.h
  106: @comment ISO
  107: @deftypevar {FILE *} stderr
  108: The @dfn{standard error} stream, which is used for error messages and
  109: diagnostics issued by the program.
  110: @end deftypevar
  111: @cindex standard error stream
  112: 
  113: In the GNU system, you can specify what files or processes correspond to
  114: these streams using the pipe and redirection facilities provided by the
  115: shell.  (The primitives shells use to implement these facilities are
  116: described in @ref{File System Interface}.)  Most other operating systems
  117: provide similar mechanisms, but the details of how to use them can vary.
  118: 
  119: In the GNU C library, @code{stdin}, @code{stdout}, and @code{stderr} are
  120: normal variables which you can set just like any others.  For example,
  121: to redirect the standard output to a file, you could do:
  122: 
  123: @smallexample
  124: fclose (stdout);
  125: stdout = fopen ("standard-output-file", "w");
  126: @end smallexample
  127: 
  128: Note however, that in other systems @code{stdin}, @code{stdout}, and
  129: @code{stderr} are macros that you cannot assign to in the normal way.
  130: But you can use @code{freopen} to get the effect of closing one and
  131: reopening it.  @xref{Opening Streams}.
  132: 
  133: The three streams @code{stdin}, @code{stdout}, and @code{stderr} are not
  134: unoriented at program start (@pxref{Streams and I18N}).
  135: 
  136: @node Opening Streams
  137: @section Opening Streams
  138: 
  139: @cindex opening a stream
  140: Opening a file with the @code{fopen} function creates a new stream and
  141: establishes a connection between the stream and a file.  This may
  142: involve creating a new file.
  143: 
  144: @pindex stdio.h
  145: Everything described in this section is declared in the header file
  146: @file{stdio.h}.
  147: 
  148: @comment stdio.h
  149: @comment ISO
  150: @deftypefun {FILE *} fopen (const char *@var{filename}, const char *@var{opentype})
  151: The @code{fopen} function opens a stream for I/O to the file
  152: @var{filename}, and returns a pointer to the stream.
  153: 
  154: The @var{opentype} argument is a string that controls how the file is
  155: opened and specifies attributes of the resulting stream.  It must begin
  156: with one of the following sequences of characters:
  157: 
  158: @table @samp
  159: @item r
  160: Open an existing file for reading only.
  161: 
  162: @item w
  163: Open the file for writing only.  If the file already exists, it is
  164: truncated to zero length.  Otherwise a new file is created.
  165: 
  166: @item a
  167: Open a file for append access; that is, writing at the end of file only.
  168: If the file already exists, its initial contents are unchanged and
  169: output to the stream is appended to the end of the file.
  170: Otherwise, a new, empty file is created.
  171: 
  172: @item r+
  173: Open an existing file for both reading and writing.  The initial contents
  174: of the file are unchanged and the initial file position is at the
  175: beginning of the file.
  176: 
  177: @item w+
  178: Open a file for both reading and writing.  If the file already exists, it
  179: is truncated to zero length.  Otherwise, a new file is created.
  180: 
  181: @item a+
  182: Open or create file for both reading and appending.  If the file exists,
  183: its initial contents are unchanged.  Otherwise, a new file is created.
  184: The initial file position for reading is at the beginning of the file,
  185: but output is always appended to the end of the file.
  186: @end table
  187: 
  188: As you can see, @samp{+} requests a stream that can do both input and
  189: output.  The ISO standard says that when using such a stream, you must
  190: call @code{fflush} (@pxref{Stream Buffering}) or a file positioning
  191: function such as @code{fseek} (@pxref{File Positioning}) when switching
  192: from reading to writing or vice versa.  Otherwise, internal buffers
  193: might not be emptied properly.  The GNU C library does not have this
  194: limitation; you can do arbitrary reading and writing operations on a
  195: stream in whatever order.
  196: 
  197: Additional characters may appear after these to specify flags for the
  198: call.  Always put the mode (@samp{r}, @samp{w+}, etc.) first; that is
  199: the only part you are guaranteed will be understood by all systems.
  200: 
  201: The GNU C library defines one additional character for use in
  202: @var{opentype}: the character @samp{x} insists on creating a new
  203: file---if a file @var{filename} already exists, @code{fopen} fails
  204: rather than opening it.  If you use @samp{x} you are guaranteed that
  205: you will not clobber an existing file.  This is equivalent to the
  206: @code{O_EXCL} option to the @code{open} function (@pxref{Opening and
  207: Closing Files}).
  208: 
  209: The character @samp{b} in @var{opentype} has a standard meaning; it
  210: requests a binary stream rather than a text stream.  But this makes no
  211: difference in POSIX systems (including the GNU system).  If both
  212: @samp{+} and @samp{b} are specified, they can appear in either order.
  213: @xref{Binary Streams}.
  214: 
  215: @cindex stream orientation
  216: @cindex orientation, stream
  217: If the @var{opentype} string contains the sequence
  218: @code{,ccs=@var{STRING}} then @var{STRING} is taken as the name of a
  219: coded character set and @code{fopen} will mark the stream as
  220: wide-oriented which appropriate conversion functions in place to convert
  221: from and to the character set @var{STRING} is place.  Any other stream
  222: is opened initially unoriented and the orientation is decided with the
  223: first file operation.  If the first operation is a wide character
  224: operation, the stream is not only marked as wide-oriented, also the
  225: conversion functions to convert to the coded character set used for the
  226: current locale are loaded.  This will not change anymore from this point
  227: on even if the locale selected for the @code{LC_CTYPE} category is
  228: changed.
  229: 
  230: Any other characters in @var{opentype} are simply ignored.  They may be
  231: meaningful in other systems.
  232: 
  233: If the open fails, @code{fopen} returns a null pointer.
  234: 
  235: When the sources are compiling with @code{_FILE_OFFSET_BITS == 64} on a
  236: 32 bit machine this function is in fact @code{fopen64} since the LFS
  237: interface replaces transparently the old interface.
  238: @end deftypefun
  239: 
  240: You can have multiple streams (or file descriptors) pointing to the same
  241: file open at the same time.  If you do only input, this works
  242: straightforwardly, but you must be careful if any output streams are
  243: included.  @xref{Stream/Descriptor Precautions}.  This is equally true
  244: whether the streams are in one program (not usual) or in several
  245: programs (which can easily happen).  It may be advantageous to use the
  246: file locking facilities to avoid simultaneous access.  @xref{File
  247: Locks}.
  248: 
  249: @comment stdio.h
  250: @comment Unix98
  251: @deftypefun {FILE *} fopen64 (const char *@var{filename}, const char *@var{opentype})
  252: This function is similar to @code{fopen} but the stream it returns a
  253: pointer for is opened using @code{open64}.  Therefore this stream can be
  254: used even on files larger then @math{2^31} bytes on 32 bit machines.
  255: 
  256: Please note that the return type is still @code{FILE *}.  There is no
  257: special @code{FILE} type for the LFS interface.
  258: 
  259: If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
  260: bits machine this function is available under the name @code{fopen}
  261: and so transparently replaces the old interface.
  262: @end deftypefun
  263: 
  264: @comment stdio.h
  265: @comment ISO
  266: @deftypevr Macro int FOPEN_MAX
  267: The value of this macro is an integer constant expression that
  268: represents the minimum number of streams that the implementation
  269: guarantees can be open simultaneously.  You might be able to open more
  270: than this many streams, but that is not guaranteed.  The value of this
  271: constant is at least eight, which includes the three standard streams
  272: @code{stdin}, @code{stdout}, and @code{stderr}.  In POSIX.1 systems this
  273: value is determined by the @code{OPEN_MAX} parameter; @pxref{General
  274: Limits}.  In BSD and GNU, it is controlled by the @code{RLIMIT_NOFILE}
  275: resource limit; @pxref{Limits on Resources}.
  276: @end deftypevr
  277: 
  278: @comment stdio.h
  279: @comment ISO
  280: @deftypefun {FILE *} freopen (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream})
  281: This function is like a combination of @code{fclose} and @code{fopen}.
  282: It first closes the stream referred to by @var{stream}, ignoring any
  283: errors that are detected in the process.  (Because errors are ignored,
  284: you should not use @code{freopen} on an output stream if you have
  285: actually done any output using the stream.)  Then the file named by
  286: @var{filename} is opened with mode @var{opentype} as for @code{fopen},
  287: and associated with the same stream object @var{stream}.
  288: 
  289: If the operation fails, a null pointer is returned; otherwise,
  290: @code{freopen} returns @var{stream}.
  291: 
  292: @code{freopen} has traditionally been used to connect a standard stream
  293: such as @code{stdin} with a file of your own choice.  This is useful in
  294: programs in which use of a standard stream for certain purposes is
  295: hard-coded.  In the GNU C library, you can simply close the standard
  296: streams and open new ones with @code{fopen}.  But other systems lack
  297: this ability, so using @code{freopen} is more portable.
  298: 
  299: When the sources are compiling with @code{_FILE_OFFSET_BITS == 64} on a
  300: 32 bit machine this function is in fact @code{freopen64} since the LFS
  301: interface replaces transparently the old interface.
  302: @end deftypefun
  303: 
  304: @comment stdio.h
  305: @comment Unix98
  306: @deftypefun {FILE *} freopen64 (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream})
  307: This function is similar to @code{freopen}.  The only difference is that
  308: on 32 bit machine the stream returned is able to read beyond the
  309: @math{2^31} bytes limits imposed by the normal interface.  It should be
  310: noted that the stream pointed to by @var{stream} need not be opened
  311: using @code{fopen64} or @code{freopen64} since its mode is not important
  312: for this function.
  313: 
  314: If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
  315: bits machine this function is available under the name @code{freopen}
  316: and so transparently replaces the old interface.
  317: @end deftypefun
  318: 
  319: In some situations it is useful to know whether a given stream is
  320: available for reading or writing.  This information is normally not
  321: available and would have to be remembered separately.  Solaris
  322: introduced a few functions to get this information from the stream
  323: descriptor and these functions are also available in the GNU C library.
  324: 
  325: @comment stdio_ext.h
  326: @comment GNU
  327: @deftypefun int __freadable (FILE *@var{stream})
  328: The @code{__freadable} function determines whether the stream
  329: @var{stream} was opened to allow reading.  In this case the return value
  330: is nonzero.  For write-only streams the function returns zero.
  331: 
  332: This function is declared in @file{stdio_ext.h}.
  333: @end deftypefun
  334: 
  335: @comment stdio_ext.h
  336: @comment GNU
  337: @deftypefun int __fwritable (FILE *@var{stream})
  338: The @code{__fwritable} function determines whether the stream
  339: @var{stream} was opened to allow writing.  In this case the return value
  340: is nonzero.  For read-only streams the function returns zero.
  341: 
  342: This function is declared in @file{stdio_ext.h}.
  343: @end deftypefun
  344: 
  345: For slightly different kind of problems there are two more functions.
  346: They provide even finer-grained information.
  347: 
  348: @comment stdio_ext.h
  349: @comment GNU
  350: @deftypefun int __freading (FILE *@var{stream})
  351: The @code{__freading} function determines whether the stream
  352: @var{stream} was last read from or whether it is opened read-only.  In
  353: this case the return value is nonzero, otherwise it is zero.
  354: Determining whether a stream opened for reading and writing was last
  355: used for writing allows to draw conclusions about the content about the
  356: buffer, among other things.
  357: 
  358: This function is declared in @file{stdio_ext.h}.
  359: @end deftypefun
  360: 
  361: @comment stdio_ext.h
  362: @comment GNU
  363: @deftypefun int __fwriting (FILE *@var{stream})
  364: The @code{__fwriting} function determines whether the stream
  365: @var{stream} was last written to or whether it is opened write-only.  In
  366: this case the return value is nonzero, otherwise it is zero.
  367: 
  368: This function is declared in @file{stdio_ext.h}.
  369: @end deftypefun
  370: 
  371: 
  372: @node Closing Streams
  373: @section Closing Streams
  374: 
  375: @cindex closing a stream
  376: When a stream is closed with @code{fclose}, the connection between the
  377: stream and the file is canceled.  After you have closed a stream, you
  378: cannot perform any additional operations on it.
  379: 
  380: @comment stdio.h
  381: @comment ISO
  382: @deftypefun int fclose (FILE *@var{stream})
  383: This function causes @var{stream} to be closed and the connection to
  384: the corresponding file to be broken.  Any buffered output is written
  385: and any buffered input is discarded.  The @code{fclose} function returns
  386: a value of @code{0} if the file was closed successfully, and @code{EOF}
  387: if an error was detected.
  388: 
  389: It is important to check for errors when you call @code{fclose} to close
  390: an output stream, because real, everyday errors can be detected at this
  391: time.  For example, when @code{fclose} writes the remaining buffered
  392: output, it might get an error because the disk is full.  Even if you
  393: know the buffer is empty, errors can still occur when closing a file if
  394: you are using NFS.
  395: 
  396: The function @code{fclose} is declared in @file{stdio.h}.
  397: @end deftypefun
  398: 
  399: To close all streams currently available the GNU C Library provides
  400: another function.
  401: 
  402: @comment stdio.h
  403: @comment GNU
  404: @deftypefun int fcloseall (void)
  405: This function causes all open streams of the process to be closed and
  406: the connection to corresponding files to be broken.  All buffered data
  407: is written and any buffered input is discarded.  The @code{fcloseall}
  408: function returns a value of @code{0} if all the files were closed
  409: successfully, and @code{EOF} if an error was detected.
  410: 
  411: This function should be used only in special situations, e.g., when an
  412: error occurred and the program must be aborted.  Normally each single
  413: stream should be closed separately so that problems with individual
  414: streams can be identified.  It is also problematic since the standard
  415: streams (@pxref{Standard Streams}) will also be closed.
  416: 
  417: The function @code{fcloseall} is declared in @file{stdio.h}.
  418: @end deftypefun
  419: 
  420: If the @code{main} function to your program returns, or if you call the
  421: @code{exit} function (@pxref{Normal Termination}), all open streams are
  422: automatically closed properly.  If your program terminates in any other
  423: manner, such as by calling the @code{abort} function (@pxref{Aborting a
  424: Program}) or from a fatal signal (@pxref{Signal Handling}), open streams
  425: might not be closed properly.  Buffered output might not be flushed and
  426: files may be incomplete.  For more information on buffering of streams,
  427: see @ref{Stream Buffering}.
  428: 
  429: @node Streams and Threads
  430: @section Streams and Threads
  431: 
  432: @cindex threads
  433: @cindex multi-threaded application
  434: Streams can be used in multi-threaded applications in the same way they
  435: are used in single-threaded applications.  But the programmer must be
  436: aware of the possible complications.  It is important to know about
  437: these also if the program one writes never use threads since the design
  438: and implementation of many stream functions is heavily influenced by the
  439: requirements added by multi-threaded programming.
  440: 
  441: The POSIX standard requires that by default the stream operations are
  442: atomic.  I.e., issuing two stream operations for the same stream in two
  443: threads at the same time will cause the operations to be executed as if
  444: they were issued sequentially.  The buffer operations performed while
  445: reading or writing are protected from other uses of the same stream.  To
  446: do this each stream has an internal lock object which has to be
  447: (implicitly) acquired before any work can be done.
  448: 
  449: But there are situations where this is not enough and there are also
  450: situations where this is not wanted.  The implicit locking is not enough
  451: if the program requires more than one stream function call to happen
  452: atomically.  One example would be if an output line a program wants to
  453: generate is created by several function calls.  The functions by
  454: themselves would ensure only atomicity of their own operation, but not
  455: atomicity over all the function calls.  For this it is necessary to
  456: perform the stream locking in the application code.
  457: 
  458: @comment stdio.h
  459: @comment POSIX
  460: @deftypefun void flockfile (FILE *@var{stream})
  461: The @code{flockfile} function acquires the internal locking object
  462: associated with the stream @var{stream}.  This ensures that no other
  463: thread can explicitly through @code{flockfile}/@code{ftrylockfile} or
  464: implicit through a call of a stream function lock the stream.  The
  465: thread will block until the lock is acquired.  An explicit call to
  466: @code{funlockfile} has to be used to release the lock.
  467: @end deftypefun
  468: 
  469: @comment stdio.h
  470: @comment POSIX
  471: @deftypefun int ftrylockfile (FILE *@var{stream})
  472: The @code{ftrylockfile} function tries to acquire the internal locking
  473: object associated with the stream @var{stream} just like
  474: @code{flockfile}.  But unlike @code{flockfile} this function does not
  475: block if the lock is not available.  @code{ftrylockfile} returns zero if
  476: the lock was successfully acquired.  Otherwise the stream is locked by
  477: another thread.
  478: @end deftypefun
  479: 
  480: @comment stdio.h
  481: @comment POSIX
  482: @deftypefun void funlockfile (FILE *@var{stream})
  483: The @code{funlockfile} function releases the internal locking object of
  484: the stream @var{stream}. The stream must have been locked before by a
  485: call to @code{flockfile} or a successful call of @code{ftrylockfile}.
  486: The implicit locking performed by the stream operations do not count.
  487: The @code{funlockfile} function does not return an error status and the
  488: behavior of a call for a stream which is not locked by the current
  489: thread is undefined.
  490: @end deftypefun
  491: 
  492: The following example shows how the functions above can be used to
  493: generate an output line atomically even in multi-threaded applications
  494: (yes, the same job could be done with one @code{fprintf} call but it is
  495: sometimes not possible):
  496: 
  497: @smallexample
  498: FILE *fp;
  499: @{
  500:    @dots{}
  501:    flockfile (fp);
  502:    fputs ("This is test number ", fp);
  503:    fprintf (fp, "%d\n", test);
  504:    funlockfile (fp)
  505: @}
  506: @end smallexample
  507: 
  508: Without the explicit locking it would be possible for another thread to
  509: use the stream @var{fp} after the @code{fputs} call return and before
  510: @code{fprintf} was called with the result that the number does not
  511: follow the word @samp{number}.
  512: 
  513: From this description it might already be clear that the locking objects
  514: in streams are no simple mutexes.  Since locking the same stream twice
  515: in the same thread is allowed the locking objects must be equivalent to
  516: recursive mutexes.  These mutexes keep track of the owner and the number
  517: of times the lock is acquired.  The same number of @code{funlockfile}
  518: calls by the same threads is necessary to unlock the stream completely.
  519: For instance:
  520: 
  521: @smallexample
  522: void
  523: foo (FILE *fp)
  524: @{
  525:   ftrylockfile (fp);
  526:   fputs ("in foo\n", fp);
  527:   /* @r{This is very wrong!!!}  */
  528:   funlockfile (fp);
  529: @}
  530: @end smallexample
  531: 
  532: It is important here that the @code{funlockfile} function is only called
  533: if the @code{ftrylockfile} function succeeded in locking the stream.  It
  534: is therefore always wrong to ignore the result of @code{ftrylockfile}.
  535: And it makes no sense since otherwise one would use @code{flockfile}.
  536: The result of code like that above is that either @code{funlockfile}
  537: tries to free a stream that hasn't been locked by the current thread or it
  538: frees the stream prematurely.  The code should look like this:
  539: 
  540: @smallexample
  541: void
  542: foo (FILE *fp)
  543: @{
  544:   if (ftrylockfile (fp) == 0)
  545:     @{
  546:       fputs ("in foo\n", fp);
  547:       funlockfile (fp);
  548:     @}
  549: @}
  550: @end smallexample
  551: 
  552: Now that we covered why it is necessary to have these locking it is
  553: necessary to talk about situations when locking is unwanted and what can
  554: be done.  The locking operations (explicit or implicit) don't come for
  555: free.  Even if a lock is not taken the cost is not zero.  The operations
  556: which have to be performed require memory operations that are safe in
  557: multi-processor environments.  With the many local caches involved in
  558: such systems this is quite costly.  So it is best to avoid the locking
  559: completely if it is not needed -- because the code in question is never
  560: used in a context where two or more threads may use a stream at a time.
  561: This can be determined most of the time for application code; for
  562: library code which can be used in many contexts one should default to be
  563: conservative and use locking.
  564: 
  565: There are two basic mechanisms to avoid locking.  The first is to use
  566: the @code{_unlocked} variants of the stream operations.  The POSIX
  567: standard defines quite a few of those and the GNU library adds a few
  568: more.  These variants of the functions behave just like the functions
  569: with the name without the suffix except that they do not lock the
  570: stream.  Using these functions is very desirable since they are
  571: potentially much faster.  This is not only because the locking
  572: operation itself is avoided.  More importantly, functions like
  573: @code{putc} and @code{getc} are very simple and traditionally (before the
  574: introduction of threads) were implemented as macros which are very fast
  575: if the buffer is not empty.  With the addition of locking requirements
  576: these functions are no longer implemented as macros since they would
  577: would expand to too much code.
  578: But these macros are still available with the same functionality under the new
  579: names @code{putc_unlocked} and @code{getc_unlocked}.  This possibly huge
  580: difference of speed also suggests the use of the @code{_unlocked}
  581: functions even if locking is required.  The difference is that the
  582: locking then has to be performed in the program:
  583: 
  584: @smallexample
  585: void
  586: foo (FILE *fp, char *buf)
  587: @{
  588:   flockfile (fp);
  589:   while (*buf != '/')
  590:     putc_unlocked (*buf++, fp);
  591:   funlockfile (fp);
  592: @}
  593: @end smallexample
  594: 
  595: If in this example the @code{putc} function would be used and the
  596: explicit locking would be missing the @code{putc} function would have to
  597: acquire the lock in every call, potentially many times depending on when
  598: the loop terminates.  Writing it the way illustrated above allows the
  599: @code{putc_unlocked} macro to be used which means no locking and direct
  600: manipulation of the buffer of the stream.
  601: 
  602: A second way to avoid locking is by using a non-standard function which
  603: was introduced in Solaris and is available in the GNU C library as well.
  604: 
  605: @comment stdio_ext.h
  606: @comment GNU
  607: @deftypefun int __fsetlocking (FILE *@var{stream}, int @var{type})
  608: 
  609: The @code{__fsetlocking} function can be used to select whether the
  610: stream operations will implicitly acquire the locking object of the
  611: stream @var{stream}.  By default this is done but it can be disabled and
  612: reinstated using this function.  There are three values defined for the
  613: @var{type} parameter.
  614: 
  615: @vtable @code
  616: @item FSETLOCKING_INTERNAL
  617: The stream @code{stream} will from now on use the default internal
  618: locking.  Every stream operation with exception of the @code{_unlocked}
  619: variants will implicitly lock the stream.
  620: 
  621: @item FSETLOCKING_BYCALLER
  622: After the @code{__fsetlocking} function returns the user is responsible
  623: for locking the stream.  None of the stream operations will implicitly
  624: do this anymore until the state is set back to
  625: @code{FSETLOCKING_INTERNAL}.
  626: 
  627: @item FSETLOCKING_QUERY
  628: @code{__fsetlocking} only queries the current locking state of the
  629: stream.  The return value will be @code{FSETLOCKING_INTERNAL} or
  630: @code{FSETLOCKING_BYCALLER} depending on the state.
  631: @end vtable
  632: 
  633: The return value of @code{__fsetlocking} is either
  634: @code{FSETLOCKING_INTERNAL} or @code{FSETLOCKING_BYCALLER} depending on
  635: the state of the stream before the call.
  636: 
  637: This function and the values for the @var{type} parameter are declared
  638: in @file{stdio_ext.h}.
  639: @end deftypefun
  640: 
  641: This function is especially useful when program code has to be used
  642: which is written without knowledge about the @code{_unlocked} functions
  643: (or if the programmer was too lazy to use them).
  644: 
  645: @node Streams and I18N
  646: @section Streams in Internationalized Applications
  647: 
  648: @w{ISO C90} introduced the new type @code{wchar_t} to allow handling
  649: larger character sets.  What was missing was a possibility to output
  650: strings of @code{wchar_t} directly.  One had to convert them into
  651: multibyte strings using @code{mbstowcs} (there was no @code{mbsrtowcs}
  652: yet) and then use the normal stream functions.  While this is doable it
  653: is very cumbersome since performing the conversions is not trivial and
  654: greatly increases program complexity and size.
  655: 
  656: The Unix standard early on (I think in XPG4.2) introduced two additional
  657: format specifiers for the @code{printf} and @code{scanf} families of
  658: functions.  Printing and reading of single wide characters was made
  659: possible using the @code{%C} specifier and wide character strings can be
  660: handled with @code{%S}.  These modifiers behave just like @code{%c} and
  661: @code{%s} only that they expect the corresponding argument to have the
  662: wide character type and that the wide character and string are
  663: transformed into/from multibyte strings before being used.
  664: 
  665: This was a beginning but it is still not good enough.  Not always is it
  666: desirable to use @code{printf} and @code{scanf}.  The other, smaller and
  667: faster functions cannot handle wide characters.  Second, it is not
  668: possible to have a format string for @code{printf} and @code{scanf}
  669: consisting of wide characters.  The result is that format strings would
  670: have to be generated if they have to contain non-basic characters.
  671: 
  672: @cindex C++ streams
  673: @cindex streams, C++
  674: In the @w{Amendment 1} to @w{ISO C90} a whole new set of functions was
  675: added to solve the problem.  Most of the stream functions got a
  676: counterpart which take a wide character or wide character string instead
  677: of a character or string respectively.  The new functions operate on the
  678: same streams (like @code{stdout}).  This is different from the model of
  679: the C++ runtime library where separate streams for wide and normal I/O
  680: are used.
  681: 
  682: @cindex orientation, stream
  683: @cindex stream orientation
  684: Being able to use the same stream for wide and normal operations comes
  685: with a restriction: a stream can be used either for wide operations or
  686: for normal operations.  Once it is decided there is no way back.  Only a
  687: call to @code{freopen} or @code{freopen64} can reset the
  688: @dfn{orientation}.  The orientation can be decided in three ways:
  689: 
  690: @itemize @bullet
  691: @item
  692: If any of the normal character functions is used (this includes the
  693: @code{fread} and @code{fwrite} functions) the stream is marked as not
  694: wide oriented.
  695: 
  696: @item
  697: If any of the wide character functions is used the stream is marked as
  698: wide oriented.
  699: 
  700: @item
  701: The @code{fwide} function can be used to set the orientation either way.
  702: @end itemize
  703: 
  704: It is important to never mix the use of wide and not wide operations on
  705: a stream.  There are no diagnostics issued.  The application behavior
  706: will simply be strange or the application will simply crash.  The
  707: @code{fwide} function can help avoiding this.
  708: 
  709: @comment wchar.h
  710: @comment ISO
  711: @deftypefun int fwide (FILE *@var{stream}, int @var{mode})
  712: 
  713: The @code{fwide} function can be used to set and query the state of the
  714: orientation of the stream @var{stream}.  If the @var{mode} parameter has
  715: a positive value the streams get wide oriented, for negative values
  716: narrow oriented.  It is not possible to overwrite previous orientations
  717: with @code{fwide}.  I.e., if the stream @var{stream} was already
  718: oriented before the call nothing is done.
  719: 
  720: If @var{mode} is zero the current orientation state is queried and
  721: nothing is changed.
  722: 
  723: The @code{fwide} function returns a negative value, zero, or a positive
  724: value if the stream is narrow, not at all, or wide oriented
  725: respectively.
  726: 
  727: This function was introduced in @w{Amendment 1} to @w{ISO C90} and is
  728: declared in @file{wchar.h}.
  729: @end deftypefun
  730: 
  731: It is generally a good idea to orient a stream as early as possible.
  732: This can prevent surprise especially for the standard streams
  733: @code{stdin}, @code{stdout}, and @code{stderr}.  If some library
  734: function in some situations uses one of these streams and this use
  735: orients the stream in a different way the rest of the application
  736: expects it one might end up with hard to reproduce errors.  Remember
  737: that no errors are signal if the streams are used incorrectly.  Leaving
  738: a stream unoriented after creation is normally only necessary for
  739: library functions which create streams which can be used in different