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

[Richard Stallman]

    --- process.texi    21 May 2001 16:19:34 -0000      1.32
    +++ process.texi    8 Aug 2002 07:18:46 -0000
    @@ -213,11 +213,13 @@ @node Creating a Process

     @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, neither process
    +should operate on the corresponding stream.  @xref{Error Recovery}.

This part still needs to be made stronger: it says "the corresponding
stream".  People reading this will think, "I am doing fprintf on
stderr; does the child process make stderr non-blocking?"  This needs
to tell them that it is just the same if the child process makes
stdout non-blocking--either way they must not use fprintf on stderr.

    +For example, if the command @samp{ssh foo bar} makes its @code{stdout}
    +and @code{stderr} non-blocking, any program that invokes @samp{ssh foo
    +bar} as a child process with a shared @code{stdout} or @code{stderr}
    +stream must avoid using @code{fprintf} on that stream.

This too is not really clear.  It seems to say, still, that the danger
applies only to those descriptor numbers that the child program makes
non-blocking.  It doesn't mention the fact that two "different" slots
can share one descriptor in some cases even if normally they do not.

The fact is that ssh only makes its stdout non-blocking.  It does not
do this to stderr.  However, it can happen (unknown to either CVS or
ssh) that their stderr and their stdout are the same descriptor.

Please state this explicitly.

In writing this text, are you trying to keep it short by relying on
the user to draw conclusions?  Please don't approach it that way.  A
good manual needs to state the rules of good practice explicitly; to
leave it to the reader to draw conclusions makes for an inferior
manual.  Please don't hesitate to use ten lines here, or 15, or 20, or
30, to state the practical rules explicitly.