1/* Creation of subprocesses, communicating via pipes. 2 Copyright (C) 2001-2003, 2006 Free Software Foundation, Inc. 3 Written by Bruno Haible <haible@clisp.cons.org>, 2001. 4 5 This program is free software: you can redistribute it and/or modify 6 it under the terms of the GNU General Public License as published by 7 the Free Software Foundation; either version 3 of the License, or 8 (at your option) any later version. 9 10 This program is distributed in the hope that it will be useful, 11 but WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 GNU General Public License for more details. 14 15 You should have received a copy of the GNU General Public License 16 along with this program. If not, see <http://www.gnu.org/licenses/>. */ 17 18#ifndef _PIPE_H 19#define _PIPE_H 20 21/* Get pid_t. */ 22#include <stdlib.h> 23#include <unistd.h> 24#include <sys/types.h> 25 26#include <stdbool.h> 27 28 29#ifdef __cplusplus 30extern "C" { 31#endif 32 33 34/* All these functions create a subprocess and don't wait for its termination. 35 They return the process id of the subprocess. They also return in fd[] 36 one or two file descriptors for communication with the subprocess. 37 If the subprocess creation fails: if exit_on_error is true, the main 38 process exits with an error message; otherwise, an error message is given 39 if null_stderr is false, then -1 is returned and fd[] remain uninitialized. 40 41 After finishing communication, the caller should call wait_subprocess() 42 to get rid of the subprocess in the process table. 43 44 If slave_process is true, the child process will be terminated when its 45 creator receives a catchable fatal signal or exits normally. If 46 slave_process is false, the child process will continue running in this 47 case, until it is lucky enough to attempt to communicate with its creator 48 and thus get a SIGPIPE signal. 49 50 If exit_on_error is false, a child process id of -1 should be treated the 51 same way as a subprocess which accepts no input, produces no output and 52 terminates with exit code 127. Why? Some errors during posix_spawnp() 53 cause the function posix_spawnp() to return an error code; some other 54 errors cause the subprocess to exit with return code 127. It is 55 implementation dependent which error is reported which way. The caller 56 must treat both cases as equivalent. 57 58 It is recommended that no signal is blocked or ignored (i.e. have a 59 signal handler with value SIG_IGN) while any of these functions is called. 60 The reason is that child processes inherit the mask of blocked signals 61 from their parent (both through posix_spawn() and fork()/exec()); 62 likewise, signals ignored in the parent are also ignored in the child 63 (except possibly for SIGCHLD). And POSIX:2001 says [in the description 64 of exec()]: 65 "it should be noted that many existing applications wrongly 66 assume that they start with certain signals set to the default 67 action and/or unblocked. In particular, applications written 68 with a simpler signal model that does not include blocking of 69 signals, such as the one in the ISO C standard, may not behave 70 properly if invoked with some signals blocked. Therefore, it is 71 best not to block or ignore signals across execs without explicit 72 reason to do so, and especially not to block signals across execs 73 of arbitrary (not closely co-operating) programs." */ 74 75/* Open a pipe for output to a child process. 76 * The child's stdout goes to a file. 77 * 78 * write system read 79 * parent -> fd[0] -> STDIN_FILENO -> child 80 * 81 */ 82extern pid_t create_pipe_out (const char *progname, 83 const char *prog_path, char **prog_argv, 84 const char *prog_stdout, bool null_stderr, 85 bool slave_process, bool exit_on_error, 86 int fd[1]); 87 88/* Open a pipe for input from a child process. 89 * The child's stdin comes from a file. 90 * 91 * read system write 92 * parent <- fd[0] <- STDOUT_FILENO <- child 93 * 94 */ 95extern pid_t create_pipe_in (const char *progname, 96 const char *prog_path, char **prog_argv, 97 const char *prog_stdin, bool null_stderr, 98 bool slave_process, bool exit_on_error, 99 int fd[1]); 100 101/* Open a bidirectional pipe. 102 * 103 * write system read 104 * parent -> fd[1] -> STDIN_FILENO -> child 105 * parent <- fd[0] <- STDOUT_FILENO <- child 106 * read system write 107 * 108 */ 109extern pid_t create_pipe_bidi (const char *progname, 110 const char *prog_path, char **prog_argv, 111 bool null_stderr, 112 bool slave_process, bool exit_on_error, 113 int fd[2]); 114 115/* The name of the "always silent" device. */ 116#if defined _MSC_VER || defined __MINGW32__ 117/* Native Woe32 API. */ 118# define DEV_NULL "NUL" 119#else 120/* Unix API. */ 121# define DEV_NULL "/dev/null" 122#endif 123 124 125#ifdef __cplusplus 126} 127#endif 128 129 130#endif /* _PIPE_H */ 131