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