Merged jnlib into common.
[gnupg.git] / common / exechelp.h
1 /* exechelp.h - Definitions for the fork and exec helpers
2  *      Copyright (C) 2004, 2009 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, return a new stream in
57    STATUSFILE for stderr and the pid of the process in PID. The
58    arguments for the process are expected in the NULL terminated array
59    ARGV.  The program name itself should not be included there.  If
60    PREEXEC is not NULL, that function will be called right before the
61    exec.  FLAGS is currently only useful for W32, see the source for
62    details.  Calling gnupg_wait_process is required.  Returns 0 on
63    success or an error code. */
64 gpg_error_t gnupg_spawn_process (const char *pgmname, const char *argv[],
65                                  FILE *infile, estream_t outfile,
66                                  void (*preexec)(void), unsigned int flags,
67                                  FILE **statusfile, pid_t *pid);
68
69
70 /* Simplified version of gnupg_spawn_process.  This function forks and
71    then execs PGMNAME, while connecting INFD to stdin, OUTFD to stdout
72    and ERRFD to stderr (any of them may be -1 to connect them to
73    /dev/null).  The arguments for the process are expected in the NULL
74    terminated array ARGV.  The program name itself should not be
75    included there.  Calling gnupg_wait_process is required.  Returns 0
76    on success or an error code. */
77 gpg_error_t gnupg_spawn_process_fd (const char *pgmname, 
78                                     const char *argv[],
79                                     int infd, int outfd, int errfd,
80                                     pid_t *pid);
81
82
83 /* Wait for the process identified by PID to terminate. PGMNAME should
84    be the same as supplied to the spawn fucntion and is only used for
85    diagnostics.  Returns 0 if the process succeded, GPG_ERR_GENERAL
86    for any failures of the spawned program or other error codes.  If
87    EXITCODE is not NULL the exit code of the process is stored at this
88    address or -1 if it could not be retrieved.  */
89 gpg_error_t gnupg_wait_process (const char *pgmname, pid_t pid, int *exitcode);
90
91
92 /* Kill a process; that is send an appropriate signal to the process.
93    gnupg_wait_process must be called to actually remove the process
94    from the system.  An invalid PID is ignored.  */
95 void gnupg_kill_process (pid_t pid);
96
97
98 /* Spawn a new process and immediatley detach from it.  The name of
99    the program to exec is PGMNAME and its arguments are in ARGV (the
100    programname is automatically passed as first argument).
101    Environment strings in ENVP are set.  An error is returned if
102    pgmname is not executable; to make this work it is necessary to
103    provide an absolute file name.  */
104 gpg_error_t gnupg_spawn_process_detached (const char *pgmname,
105                                           const char *argv[],
106                                           const char *envp[] );
107
108
109
110 #endif /*GNUPG_COMMON_EXECHELP_H*/