X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=lib%2Fpipe.h;h=3c1b4b8f20d5c9161fae88cb747e4bcd9445caa3;hb=408e170e3ae81f73fb65686c5834693d89a96594;hp=082f6875f763117f674cb46eaff23c044005958f;hpb=deb58d481fc8dc345e463002c7087a08a4f1d5f0;p=gnulib.git diff --git a/lib/pipe.h b/lib/pipe.h index 082f6875f..3c1b4b8f2 100644 --- a/lib/pipe.h +++ b/lib/pipe.h @@ -1,146 +1,2 @@ -/* Creation of subprocesses, communicating via pipes. - Copyright (C) 2001-2003, 2006, 2008-2009 Free Software Foundation, Inc. - Written by Bruno Haible , 2001. - - 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 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 - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - 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, see . */ - -#ifndef _PIPE_H -#define _PIPE_H - -/* Get pid_t. */ -#include -#include -#include - -#include - - -#ifdef __cplusplus -extern "C" { -#endif - - -/* All these functions create a subprocess and don't wait for its termination. - They return the process id of the subprocess. They also return in fd[] - one or two file descriptors for communication with the subprocess. - If the subprocess creation fails: if exit_on_error is true, the main - process exits with an error message; otherwise, an error message is given - if null_stderr is false, then -1 is returned and fd[] remain uninitialized. - - After finishing communication, the caller should call wait_subprocess() - to get rid of the subprocess in the process table. - - If slave_process is true, the child process will be terminated when its - creator receives a catchable fatal signal or exits normally. If - slave_process is false, the child process will continue running in this - case, until it is lucky enough to attempt to communicate with its creator - and thus get a SIGPIPE signal. - - If exit_on_error is false, a child process id of -1 should be treated the - same way as a subprocess which accepts no input, produces no output and - terminates with exit code 127. Why? Some errors during posix_spawnp() - cause the function posix_spawnp() to return an error code; some other - errors cause the subprocess to exit with return code 127. It is - implementation dependent which error is reported which way. The caller - must treat both cases as equivalent. - - It is recommended that no signal is blocked or ignored (i.e. have a - signal handler with value SIG_IGN) while any of these functions is called. - The reason is that child processes inherit the mask of blocked signals - from their parent (both through posix_spawn() and fork()/exec()); - likewise, signals ignored in the parent are also ignored in the child - (except possibly for SIGCHLD). And POSIX:2001 says [in the description - of exec()]: - "it should be noted that many existing applications wrongly - assume that they start with certain signals set to the default - action and/or unblocked. In particular, applications written - with a simpler signal model that does not include blocking of - signals, such as the one in the ISO C standard, may not behave - properly if invoked with some signals blocked. Therefore, it is - best not to block or ignore signals across execs without explicit - reason to do so, and especially not to block signals across execs - of arbitrary (not closely co-operating) programs." */ - -/* Open a pipe for output to a child process. - * The child's stdout goes to a file. - * - * 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, - const char *prog_stdout, bool null_stderr, - bool slave_process, bool exit_on_error, - int fd[1]); - -/* Open a pipe for input from a child process. - * The child's stdin comes from a file. - * - * read system write - * parent <- fd[0] <- STDOUT_FILENO <- child - * - */ -extern pid_t create_pipe_in (const char *progname, - const char *prog_path, char **prog_argv, - const char *prog_stdin, bool null_stderr, - bool slave_process, bool exit_on_error, - int fd[1]); - -/* Open a bidirectional pipe. - * - * write system read - * parent -> fd[1] -> STDIN_FILENO -> child - * 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, - bool null_stderr, - bool slave_process, bool exit_on_error, - int fd[2]); - -/* The name of the "always silent" device. */ -#if (defined _WIN32 || defined __WIN32__) && ! defined __CYGWIN__ -/* Native Woe32 API. */ -# define DEV_NULL "NUL" -#else -/* Unix API. */ -# define DEV_NULL "/dev/null" -#endif - - -#ifdef __cplusplus -} -#endif - - -#endif /* _PIPE_H */ +/* Obsolete; consider using spawn-pipe.h instead. */ +#include "spawn-pipe.h"