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 fucntion 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
  63 /* Fork and exec the PGMNAME.  If INFP is NULL connect /dev/null to
  64    stdin of the new process; if it is not NULL connect the file
  65    descriptor retrieved from INFP to stdin.  If R_OUTFP is NULL
  66    connect stdout of the new process to /dev/null; if it is not NULL
  67    store the address of a pointer to a new estream there.  If R_ERRFP
  68    is NULL connect stderr of the new process to /dev/null; if it is
  69    not NULL store the address of a pointer to a new estream there.  On
  70    success the pid of the new process is stored at PID.  On error -1
  71    is stored at PID and if R_OUTFP or R_ERRFP are not NULL, NULL is
  72    stored there.
  73
  74    The arguments for the process are expected in the NULL terminated
  75    array ARGV.  The program name itself should not be included there.
  76    If PREEXEC is not NULL, the given function will be called right
  77    before the exec.
  78
  79    Returns 0 on success or an error code.  Calling gnupg_wait_process
  80    and gnupg_release_process is required if the function succeeded.
  81
  82    FLAGS is a bit vector:
  83
  84    Bit 7: If set the process will be started as a background process.
  85           This flag is only useful under W32 (but not W32CE) systems,
  86           so that no new console is created and pops up a console
  87           window when starting the server.  Does not work on W32CE.
  88
  89    Bit 6: On W32 (but not on W32CE) run AllowSetForegroundWindow for
  90           the child.  Note that due to unknown problems this actually
  91           allows SetForegroundWindow for all childs of this process.
  92
  93  */
  94 gpg_error_t
  95 gnupg_spawn_process (const char *pgmname, const char *argv[],
  96                      gpg_err_source_t errsource,
  97                      void (*preexec)(void), unsigned int flags,
  98                      estream_t infp,
  99                      estream_t *r_outfp,
 100                      estream_t *r_errfp,
 101                      pid_t *pid);
 102
 103
 104 /* Simplified version of gnupg_spawn_process.  This function forks and
 105    then execs PGMNAME, while connecting INFD to stdin, OUTFD to stdout
 106    and ERRFD to stderr (any of them may be -1 to connect them to
 107    /dev/null).  The arguments for the process are expected in the NULL
 108    terminated array ARGV.  The program name itself should not be
 109    included there.  Calling gnupg_wait_process and
 110    gnupg_release_process is required.  Returns 0 on success or an
 111    error code. */
 112 gpg_error_t gnupg_spawn_process_fd (const char *pgmname,
 113                                     const char *argv[],
 114                                     int infd, int outfd, int errfd,
 115                                     pid_t *pid);
 116
 117
 118 /* If HANG is true, waits for the process identified by PID to exit;
 119    if HANG is false, checks whether the process has terminated.
 120    PGMNAME should be the same as supplied to the spawn function and is
 121    only used for diagnostics.  Return values:
 122
 123    0
 124        The process exited successful.  0 is stored at R_EXITCODE.
 125
 126    GPG_ERR_GENERAL
 127        The process exited without success.  The exit code of process
 128        is then stored at R_EXITCODE.  An exit code of -1 indicates
 129        that the process terminated abnormally (e.g. due to a signal).
 130
 131    GPG_ERR_TIMEOUT
 132        The process is still running (returned only if HANG is false).
 133
 134    GPG_ERR_INV_VALUE
 135        An invalid PID has been specified.
 136
 137    Other error codes may be returned as well.  Unless otherwise noted,
 138    -1 will be stored at R_EXITCODE.  R_EXITCODE may be passed as NULL
 139    if the exit code is not required (in that case an error messge will
 140    be printed).  Note that under Windows PID is not the process id but
 141    the handle of the process.  */
 142 gpg_error_t gnupg_wait_process (const char *pgmname, pid_t pid, int hang,
 143                                 int *r_exitcode);
 144
 145
 146 /* Kill a process; that is send an appropriate signal to the process.
 147    gnupg_wait_process must be called to actually remove the process
 148    from the system.  An invalid PID is ignored.  */
 149 void gnupg_kill_process (pid_t pid);
 150
 151 /* Release the process identified by PID.  This function is actually
 152    only required for Windows but it does not harm to always call it.
 153    It is a nop if PID is invalid.  */
 154 void gnupg_release_process (pid_t pid);
 155
 156
 157 /* Spawn a new process and immediatley detach from it.  The name of
 158    the program to exec is PGMNAME and its arguments are in ARGV (the
 159    programname is automatically passed as first argument).
 160    Environment strings in ENVP are set.  An error is returned if
 161    pgmname is not executable; to make this work it is necessary to
 162    provide an absolute file name.  */
 163 gpg_error_t gnupg_spawn_process_detached (const char *pgmname,
 164                                           const char *argv[],
 165                                           const char *envp[] );
 166
 167
 168
 169 #endif /*GNUPG_COMMON_EXECHELP_H*/