Re: stdio and non-blocking descriptors (patch for glibc manual)

[Paul Eggert]

> Date: Tue, 6 Aug 2002 08:57:47 -0600 (MDT)
> From: Richard Stallman <address@hidden>
> 
> I think it is necessary to document this danger in the manual section
> that documents `fork', and in a suitable stdio output section:

OK, here's a proposed patch to the glibc manual that builds on your
suggestion.

2002-08-07  Paul Eggert  <address@hidden>

        * manual/io.texi, manual/llio.texi, manual/process.texi,
        manual/stdio.texi: Mention the problem of stdio and non-blocking
        descriptors.  This builds on an earlier suggestion by Richard
        Stallman.

Index: io.texi
===================================================================
RCS file: /cvs/glibc/libc/manual/io.texi,v
retrieving revision 1.23
diff -u -r1.23 io.texi
--- io.texi     22 Jun 1999 12:16:22 -0000      1.23
+++ io.texi     7 Aug 2002 08:12:19 -0000
@@ -87,8 +87,9 @@
 you want to do control operations that are specific to a particular kind
 of device, you must use a file descriptor; there are no facilities to
 use streams in this way.  You must also use file descriptors if your
-program needs to do input or output in special modes, such as
-nonblocking (or polled) input (@pxref{File Status Flags}).
+program needs to do input or output in special modes.  For example,
+you must use a file descriptor instead of a stream if the descriptor
+might use nonblocking (or polled) I/O (@pxref{I/O Operating Modes}).
 
 Streams provide a higher-level interface, layered on top of the
 primitive file descriptor facilities.  The stream interface treats all
Index: llio.texi
===================================================================
RCS file: /cvs/glibc/libc/manual/llio.texi,v
retrieving revision 1.72
diff -u -r1.72 llio.texi
--- llio.texi   29 Jan 2002 03:20:06 -0000      1.72
+++ llio.texi   7 Aug 2002 08:12:28 -0000
@@ -3133,6 +3133,8 @@
 Likewise, @code{write} requests can also return immediately with a
 failure status if the output can't be written immediately.
 
+Non-blocking mode does not work well with streams.  @xref{Error Recovery}.
+
 Note that the @code{O_NONBLOCK} flag is overloaded as both an I/O
 operating mode and a file name translation flag; @pxref{Open-time Flags}.
 @end deftypevr
Index: process.texi
===================================================================
RCS file: /cvs/glibc/libc/manual/process.texi,v
retrieving revision 1.32
diff -u -r1.32 process.texi
--- process.texi        21 May 2001 16:19:34 -0000      1.32
+++ process.texi        7 Aug 2002 08:12:30 -0000
@@ -213,11 +213,14 @@
 
 @item
 The child process gets its own copies of the parent process's open file
-descriptors.  Subsequently changing attributes of the file descriptors
-in the parent process won't affect the file descriptors in the child,
-and vice versa.  @xref{Control Operations}.  However, the file position
-associated with each descriptor is shared by both processes;
address@hidden Position}.
+descriptors.  Subsequently changing flags of the file descriptors in the
+parent process won't affect the file descriptors in the child, and vice
+versa.  @xref{Descriptor Flags}.  However, the file position and status
+flags associated with each file descriptor are shared by both processes.
+See @ref{File Position} and @ref{File Status Flags}.  For example, if
+one process makes the file descriptor non-blocking, the other process
+should not use @code{fprintf} on the corresponding stream.  @xref{Error
+Recovery}.
 
 @item
 The elapsed processor times for the child process are set to zero;
Index: stdio.texi
===================================================================
RCS file: /cvs/glibc/libc/manual/stdio.texi,v
retrieving revision 1.133
diff -u -r1.133 stdio.texi
--- stdio.texi  30 Jun 2002 03:35:21 -0000      1.133
+++ stdio.texi  7 Aug 2002 08:12:45 -0000
@@ -4040,8 +4040,24 @@
 can be quite inconvenient.  You can avoid this hassle by installing all
 signals with the @code{SA_RESTART} flag.
 
-For similar reasons, setting nonblocking I/O on a stream's file
-descriptor is not usually advisable.
+Similarly, the @code{EAGAIN} error means that it is usually inadvisable
+to use stream operations on a file descriptor that is operating in
+non-blocking I/O mode (@pxref{Operating Modes}).  Hence if there is any
+possibility that a process might make one of its file descriptors
+non-blocking, all processes that share that file descriptor should avoid
+using the corresponding stream.  For example, if the command @samp{ssh
+foo bar} makes its @code{stdout} non-blocking, any program that invokes
address@hidden foo bar} as a child process with a shared @code{stdout} stream
+must avoid using @code{fprintf} on that stream.
+
+It is safe to use non-blocking streams if you limit yourself to
+single-byte invocations like @code{fputc}, provided you check every call
+to @code{fputc} for an error return; however, that use of streams
+provides little benefit.  Often the simplest workaround to this problem
+is to create an intermediate byte-copying process by invoking the
+equivalent of the shell command @samp{ssh foo bar | cat} instead of
address@hidden foo bar}, so that no parent program shares @code{stdout} with
address@hidden
 
 @node Binary Streams
 @section Text and Binary Streams