[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: stdio and non-blocking descriptors (patch for glibc manual)
From: |
Paul Eggert |
Subject: |
Re: stdio and non-blocking descriptors (patch for glibc manual) |
Date: |
Wed, 7 Aug 2002 01:20:29 -0700 (PDT) |
> 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
- Re: stdio and non-blocking descriptors (patch for glibc manual),
Paul Eggert <=