Merged Dirmngr with GnuPG.
[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  * GnuPG is free software; you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation; either version 3 of the License, or
9  * (at your option) any later version.
10  *
11  * GnuPG is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, see <http://www.gnu.org/licenses/>.
18  */
19
20 #ifndef GNUPG_COMMON_EXECHELP_H
21 #define GNUPG_COMMON_EXECHELP_H
22
23 #include "../common/estream.h"
24
25
26 /* Return the maximum number of currently allowed file descriptors.
27    Only useful on POSIX systems.  */
28 int get_max_fds (void);
29
30
31 /* Close all file descriptors starting with descriptor FIRST.  If
32    EXCEPT is not NULL, it is expected to be a list of file descriptors
33    which are not to close.  This list shall be sorted in ascending
34    order with its end marked by -1.  */
35 void close_all_fds (int first, int *except);
36
37
38 /* Returns an array with all currently open file descriptors.  The end
39    of the array is marked by -1.  The caller needs to release this
40    array using the *standard free* and not with xfree.  This allow the
41    use of this fucntion right at startup even before libgcrypt has
42    been initialized.  Returns NULL on error and sets ERRNO accordingly.  */
43 int *get_all_open_fds (void);
44
45
46 /* Portable function to create a pipe.  Under Windows the write end is
47    inheritable.  */
48 gpg_error_t gnupg_create_inbound_pipe (int filedes[2]);
49
50 /* Portable function to create a pipe.  Under Windows the read end is
51    inheritable.  */
52 gpg_error_t gnupg_create_outbound_pipe (int filedes[2]);
53
54
55 /* Fork and exec the PGMNAME, connect the file descriptor of INFILE to
56    stdin, write the output to OUTFILE.  INFILE or PUTFILE may be NULL
57    to connect thenm to /dev/null.  Returns a new stream in STATUSFILE
58    for stderr and the pid of the process in PID. The arguments for the
59    process are expected in the NULL terminated array ARGV.  The
60    program name itself should not be included there.  If PREEXEC is
61    not NULL, that function will be called right before the exec.
62    Calling gnupg_wait_process and gnupg_release_process is required.
63    Returns 0 on success or an error code.
64
65    FLAGS is a bit vector:
66
67    Bit 7: If set the process will be started as a background process.
68           This flag is only useful under W32 (but not W32CE) systems,
69           so that no new console is created and pops up a console
70           window when starting the server.  Does not work on W32CE.
71  
72    Bit 6: On W32 (but not on W32CE) run AllowSetForegroundWindow for
73           the child.  Note that due to unknown problems this actually
74           allows SetForegroundWindow for all childs of this process.
75
76  */
77 gpg_error_t gnupg_spawn_process (const char *pgmname, const char *argv[],
78                                  estream_t infile, estream_t outfile,
79                                  void (*preexec)(void), unsigned int flags,
80                                  estream_t *statusfile, pid_t *pid);
81
82
83 /* Simplified version of gnupg_spawn_process.  This function forks and
84    then execs PGMNAME, while connecting INFD to stdin, OUTFD to stdout
85    and ERRFD to stderr (any of them may be -1 to connect them to
86    /dev/null).  The arguments for the process are expected in the NULL
87    terminated array ARGV.  The program name itself should not be
88    included there.  Calling gnupg_wait_process and
89    gnupg_release_process is required.  Returns 0 on success or an
90    error code. */
91 gpg_error_t gnupg_spawn_process_fd (const char *pgmname, 
92                                     const char *argv[],
93                                     int infd, int outfd, int errfd,
94                                     pid_t *pid);
95
96
97 /* If HANG is true, waits for the process identified by PID to exit;
98    if HANG is false, checks whether the process has terminated.
99    PGMNAME should be the same as supplied to the spawn function and is
100    only used for diagnostics.  Return values:
101
102    0
103        The process exited successful.  0 is stored at R_EXITCODE.
104
105    GPG_ERR_GENERAL
106        The process exited without success.  The exit code of process
107        is then stored at R_EXITCODE.  An exit code of -1 indicates
108        that the process terminated abnormally (e.g. due to a signal).
109
110    GPG_ERR_TIMEOUT 
111        The process is still running (returned only if HANG is false).
112
113    GPG_ERR_INV_VALUE 
114        An invalid PID has been specified.  
115
116    Other error codes may be returned as well.  Unless otherwise noted,
117    -1 will be stored at R_EXITCODE.  R_EXITCODE may be passed as NULL
118    if the exit code is not required (in that case an error messge will
119    be printed).  Note that under Windows PID is not the process id but
120    the handle of the process.  */
121 gpg_error_t gnupg_wait_process (const char *pgmname, pid_t pid, int hang,
122                                 int *r_exitcode);
123
124
125 /* Kill a process; that is send an appropriate signal to the process.
126    gnupg_wait_process must be called to actually remove the process
127    from the system.  An invalid PID is ignored.  */
128 void gnupg_kill_process (pid_t pid);
129
130 /* Release the process identified by PID.  This function is actually
131    only required for Windows but it does not harm to always call it.
132    It is a nop if PID is invalid.  */
133 void gnupg_release_process (pid_t pid);
134
135
136 /* Spawn a new process and immediatley detach from it.  The name of
137    the program to exec is PGMNAME and its arguments are in ARGV (the
138    programname is automatically passed as first argument).
139    Environment strings in ENVP are set.  An error is returned if
140    pgmname is not executable; to make this work it is necessary to
141    provide an absolute file name.  */
142 gpg_error_t gnupg_spawn_process_detached (const char *pgmname,
143                                           const char *argv[],
144                                           const char *envp[] );
145
146
147
148 #endif /*GNUPG_COMMON_EXECHELP_H*/