add dependencies needed by gnulib-tool

[gnulib.git] / lib / pipe.h

diff --git a/lib/pipe.h b/lib/pipe.h
index 3856524..082f687 100644 (file)
--- a/lib/pipe.h
+++ b/lib/pipe.h
@@ -1,11 +1,11 @@
 /* Creation of subprocesses, communicating via pipes.
-   Copyright (C) 2001-2003, 2006 Free Software Foundation, Inc.
+   Copyright (C) 2001-2003, 2006, 2008-2009 Free Software Foundation, Inc.
    Written by Bruno Haible <haible@clisp.cons.org>, 2001.
 
-   This program is free software; you can redistribute it and/or modify
+   This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
-   the Free Software Foundation; either version 2, or (at your option)
-   any later version.
+   the Free Software Foundation; either version 3 of the License, or
+   (at your option) any later version.
 
    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
@@ -13,8 +13,7 @@
    GNU General Public License for more details.
 
    You should have received a copy of the GNU General Public License
-   along with this program; if not, write to the Free Software Foundation,
-   Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
+   along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
 
 #ifndef _PIPE_H
 #define _PIPE_H
@@ -79,6 +78,8 @@ extern "C" {
  *           write       system                read
  *    parent  ->   fd[0]   ->   STDIN_FILENO    ->   child
  *
+ * Note: When writing to a child process, it is useful to ignore the SIGPIPE
+ * signal and the EPIPE error code.
  */
 extern pid_t create_pipe_out (const char *progname,
                              const char *prog_path, char **prog_argv,
@@ -106,6 +107,20 @@ extern pid_t create_pipe_in (const char *progname,
  *    parent  <-   fd[0]   <-   STDOUT_FILENO   <-   child
  *           read        system                write
  *
+ * Note: When writing to a child process, it is useful to ignore the SIGPIPE
+ * signal and the EPIPE error code.
+ *
+ * Note: The parent process must be careful to avoid deadlock.
+ * 1) If you write more than PIPE_MAX bytes or, more generally, if you write
+ *    more bytes than the subprocess can handle at once, the subprocess
+ *    may write its data and wait on you to read it, but you are currently
+ *    busy writing.
+ * 2) When you don't know ahead of time how many bytes the subprocess
+ *    will produce, the usual technique of calling read (fd, buf, BUFSIZ)
+ *    with a fixed BUFSIZ will, on Linux 2.2.17 and on BSD systems, cause
+ *    the read() call to block until *all* of the buffer has been filled.
+ *    But the subprocess cannot produce more data until you gave it more
+ *    input.  But you are currently busy reading from it.
  */
 extern pid_t create_pipe_bidi (const char *progname,
                               const char *prog_path, char **prog_argv,
@@ -114,7 +129,7 @@ extern pid_t create_pipe_bidi (const char *progname,
                               int fd[2]);
 
 /* The name of the "always silent" device.  */
-#if defined _MSC_VER || defined __MINGW32__
+#if (defined _WIN32 || defined __WIN32__) && ! defined __CYGWIN__
 /* Native Woe32 API.  */
 # define DEV_NULL "NUL"
 #else