1 /* exechelp.h - Definitions for the fork and exec helpers 2 * Copyright (C) 2004, 2009, 2010 Free Software Foundation, Inc. 3 * Copyright (C) 2004, 2006-2012, 2014-2017 g10 Code GmbH 4 * 5 * This file is part of GnuPG. 6 * 7 * This file is free software; you can redistribute it and/or modify 8 * it under the terms of either 9 * 10 * - the GNU Lesser General Public License as published by the Free 11 * Software Foundation; either version 3 of the License, or (at 12 * your option) any later version. 13 * 14 * or 15 * 16 * - the GNU General Public License as published by the Free 17 * Software Foundation; either version 2 of the License, or (at 18 * your option) any later version. 19 * 20 * or both in parallel, as here. 21 * 22 * This file is distributed in the hope that it will be useful, 23 * but WITHOUT ANY WARRANTY; without even the implied warranty of 24 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 25 * GNU General Public License for more details. 26 * 27 * You should have received a copy of the GNU General Public License 28 * along with this program; if not, see <https://www.gnu.org/licenses/>. 29 * SPDX-License-Identifier: (LGPL-3.0+ OR GPL-2.0+) 30 */ 31 32 #ifndef GNUPG_COMMON_EXECHELP_H 33 #define GNUPG_COMMON_EXECHELP_H 34 35 36 /* Return the maximum number of currently allowed file descriptors. 37 Only useful on POSIX systems. */ 38 int get_max_fds (void); 39 40 41 /* Close all file descriptors starting with descriptor FIRST. If 42 EXCEPT is not NULL, it is expected to be a list of file descriptors 43 which are not to close. This list shall be sorted in ascending 44 order with its end marked by -1. */ 45 void close_all_fds (int first, int *except); 46 47 48 /* Returns an array with all currently open file descriptors. The end 49 of the array is marked by -1. The caller needs to release this 50 array using the *standard free* and not with xfree. This allow the 51 use of this function right at startup even before libgcrypt has 52 been initialized. Returns NULL on error and sets ERRNO accordingly. */ 53 int *get_all_open_fds (void); 54 55 56 /* Portable function to create a pipe. Under Windows the write end is 57 inheritable. If R_FP is not NULL, an estream is created for the 58 write end and stored at R_FP. */ 59 gpg_error_t gnupg_create_inbound_pipe (int filedes[2], 60 estream_t *r_fp, int nonblock); 61 62 /* Portable function to create a pipe. Under Windows the read end is 63 inheritable. If R_FP is not NULL, an estream is created for the 64 write end and stored at R_FP. */ 65 gpg_error_t gnupg_create_outbound_pipe (int filedes[2], 66 estream_t *r_fp, int nonblock); 67 68 /* Portable function to create a pipe. Under Windows both ends are 69 inheritable. */ 70 gpg_error_t gnupg_create_pipe (int filedes[2]); 71 72 /* Close the end of a pipe. */ 73 void gnupg_close_pipe (int fd); 74 75 76 #define GNUPG_SPAWN_NONBLOCK 16 77 #define GNUPG_SPAWN_RUN_ASFW 64 78 #define GNUPG_SPAWN_DETACHED 128 79 80 81 /* Fork and exec the program PGMNAME. 82 83 If R_INFP is NULL connect stdin of the new process to /dev/null; if 84 it is not NULL store the address of a pointer to a new estream 85 there. If R_OUTFP is NULL connect stdout of the new process to 86 /dev/null; if it is not NULL store the address of a pointer to a 87 new estream there. If R_ERRFP is NULL connect stderr of the new 88 process to /dev/null; if it is not NULL store the address of a 89 pointer to a new estream there. On success the pid of the new 90 process is stored at PID. On error -1 is stored at PID and if 91 R_OUTFP or R_ERRFP are not NULL, NULL is stored there. 92 93 The arguments for the process are expected in the NULL terminated 94 array ARGV. The program name itself should not be included there. 95 If PREEXEC is not NULL, the given function will be called right 96 before the exec. 97 98 IF EXCEPT is not NULL, it is expected to be an ordered list of file 99 descriptors, terminated by an entry with the value (-1). These 100 file descriptors won't be closed before spawning a new program. 101 102 Returns 0 on success or an error code. Calling gnupg_wait_process 103 and gnupg_release_process is required if the function succeeded. 104 105 FLAGS is a bit vector: 106 107 GNUPG_SPAWN_NONBLOCK 108 If set the two output streams are created in non-blocking 109 mode and the input stream is switched to non-blocking mode. 110 This is merely a convenience feature because the caller 111 could do the same with gpgrt_set_nonblock. Does not yet 112 work for Windows. 113 114 GNUPG_SPAWN_DETACHED 115 If set the process will be started as a background process. 116 This flag is only useful under W32 (but not W32CE) systems, 117 so that no new console is created and pops up a console 118 window when starting the server. Does not work on W32CE. 119 120 GNUPG_SPAWN_RUN_ASFW 121 On W32 (but not on W32CE) run AllowSetForegroundWindow for 122 the child. Note that due to unknown problems this actually 123 allows SetForegroundWindow for all children of this process. 124 125 */ 126 gpg_error_t 127 gnupg_spawn_process (const char *pgmname, const char *argv[], 128 int *execpt, void (*preexec)(void), unsigned int flags, 129 estream_t *r_infp, 130 estream_t *r_outfp, 131 estream_t *r_errfp, 132 pid_t *pid); 133 134 135 /* Simplified version of gnupg_spawn_process. This function forks and 136 then execs PGMNAME, while connecting INFD to stdin, OUTFD to stdout 137 and ERRFD to stderr (any of them may be -1 to connect them to 138 /dev/null). The arguments for the process are expected in the NULL 139 terminated array ARGV. The program name itself should not be 140 included there. Calling gnupg_wait_process and 141 gnupg_release_process is required. Returns 0 on success or an 142 error code. */ 143 gpg_error_t gnupg_spawn_process_fd (const char *pgmname, 144 const char *argv[], 145 int infd, int outfd, int errfd, 146 pid_t *pid); 147 148 149 /* If HANG is true, waits for the process identified by PID to exit; 150 if HANG is false, checks whether the process has terminated. 151 PGMNAME should be the same as supplied to the spawn function and is 152 only used for diagnostics. Return values: 153 154 0 155 The process exited successful. 0 is stored at R_EXITCODE. 156 157 GPG_ERR_GENERAL 158 The process exited without success. The exit code of process 159 is then stored at R_EXITCODE. An exit code of -1 indicates 160 that the process terminated abnormally (e.g. due to a signal). 161 162 GPG_ERR_TIMEOUT 163 The process is still running (returned only if HANG is false). 164 165 GPG_ERR_INV_VALUE 166 An invalid PID has been specified. 167 168 Other error codes may be returned as well. Unless otherwise noted, 169 -1 will be stored at R_EXITCODE. R_EXITCODE may be passed as NULL 170 if the exit code is not required (in that case an error message will 171 be printed). Note that under Windows PID is not the process id but 172 the handle of the process. */ 173 gpg_error_t gnupg_wait_process (const char *pgmname, pid_t pid, int hang, 174 int *r_exitcode); 175 176 /* Like gnupg_wait_process, but for COUNT processes. */ 177 gpg_error_t gnupg_wait_processes (const char **pgmnames, pid_t *pids, 178 size_t count, int hang, int *r_exitcodes); 179 180 181 /* Kill a process; that is send an appropriate signal to the process. 182 gnupg_wait_process must be called to actually remove the process 183 from the system. An invalid PID is ignored. */ 184 void gnupg_kill_process (pid_t pid); 185 186 /* Release the process identified by PID. This function is actually 187 only required for Windows but it does not harm to always call it. 188 It is a nop if PID is invalid. */ 189 void gnupg_release_process (pid_t pid); 190 191 192 /* Spawn a new process and immediately detach from it. The name of 193 the program to exec is PGMNAME and its arguments are in ARGV (the 194 programname is automatically passed as first argument). 195 Environment strings in ENVP are set. An error is returned if 196 pgmname is not executable; to make this work it is necessary to 197 provide an absolute file name. */ 198 gpg_error_t gnupg_spawn_process_detached (const char *pgmname, 199 const char *argv[], 200 const char *envp[] ); 201 202 203 204 #endif /*GNUPG_COMMON_EXECHELP_H*/ 205