Correct punctuation in the ChangeLog summary line.
[gnupg.git] / common / exechelp.h
index c5ecc0d..b975166 100644 (file)
@@ -1,5 +1,5 @@
 /* exechelp.h - Definitions for the fork and exec helpers
- *     Copyright (C) 2004, 2009 Free Software Foundation, Inc.
+ * Copyright (C) 2004, 2009, 2010 Free Software Foundation, Inc.
  *
  * This file is part of GnuPG.
  *
@@ -52,19 +52,45 @@ gpg_error_t gnupg_create_inbound_pipe (int filedes[2]);
 gpg_error_t gnupg_create_outbound_pipe (int filedes[2]);
 
 
-/* Fork and exec the PGMNAME, connect the file descriptor of INFILE to
-   stdin, write the output to OUTFILE, return a new stream in
-   STATUSFILE for stderr and the pid of the process in PID. The
-   arguments for the process are expected in the NULL terminated array
-   ARGV.  The program name itself should not be included there.  If
-   PREEXEC is not NULL, that function will be called right before the
-   exec.  FLAGS is currently only useful for W32, see the source for
-   details.  Calling gnupg_wait_process is required.  Returns 0 on
-   success or an error code. */
-gpg_error_t gnupg_spawn_process (const char *pgmname, const char *argv[],
-                                 FILE *infile, estream_t outfile,
-                                 void (*preexec)(void), unsigned int flags,
-                                 FILE **statusfile, pid_t *pid);
+/* Fork and exec the PGMNAME.  If INFP is NULL connect /dev/null to
+   stdin of the new process; if it is not NULL connect the file
+   descriptor retrieved from INFP to stdin.  If R_OUTFP is NULL
+   connect stdout of the new process to /dev/null; if it is not NULL
+   store the address of a pointer to a new estream there.  If R_ERRFP
+   is NULL connect stderr of the new process to /dev/null; if it is
+   not NULL store the address of a pointer to a new estream there.  On
+   success the pid of the new process is stored at PID.  On error -1
+   is stored at PID and if R_OUTFP or R_ERRFP are not NULL, NULL is
+   stored there.
+
+   The arguments for the process are expected in the NULL terminated
+   array ARGV.  The program name itself should not be included there.
+   If PREEXEC is not NULL, the given function will be called right
+   before the exec.
+
+   Returns 0 on success or an error code.  Calling gnupg_wait_process
+   and gnupg_release_process is required if the function succeeded.
+
+   FLAGS is a bit vector:
+
+   Bit 7: If set the process will be started as a background process.
+          This flag is only useful under W32 (but not W32CE) systems,
+          so that no new console is created and pops up a console
+          window when starting the server.  Does not work on W32CE.
+
+   Bit 6: On W32 (but not on W32CE) run AllowSetForegroundWindow for
+          the child.  Note that due to unknown problems this actually
+          allows SetForegroundWindow for all childs of this process.
+
+ */
+gpg_error_t
+gnupg_spawn_process (const char *pgmname, const char *argv[],
+                     gpg_err_source_t errsource,
+                     void (*preexec)(void), unsigned int flags,
+                     estream_t infp,
+                     estream_t *r_outfp,
+                     estream_t *r_errfp,
+                     pid_t *pid);
 
 
 /* Simplified version of gnupg_spawn_process.  This function forks and
@@ -72,21 +98,41 @@ gpg_error_t gnupg_spawn_process (const char *pgmname, const char *argv[],
    and ERRFD to stderr (any of them may be -1 to connect them to
    /dev/null).  The arguments for the process are expected in the NULL
    terminated array ARGV.  The program name itself should not be
-   included there.  Calling gnupg_wait_process is required.  Returns 0
-   on success or an error code. */
-gpg_error_t gnupg_spawn_process_fd (const char *pgmname, 
+   included there.  Calling gnupg_wait_process and
+   gnupg_release_process is required.  Returns 0 on success or an
+   error code. */
+gpg_error_t gnupg_spawn_process_fd (const char *pgmname,
                                     const char *argv[],
                                     int infd, int outfd, int errfd,
                                     pid_t *pid);
 
 
-/* Wait for the process identified by PID to terminate. PGMNAME should
-   be the same as supplied to the spawn fucntion and is only used for
-   diagnostics.  Returns 0 if the process succeded, GPG_ERR_GENERAL
-   for any failures of the spawned program or other error codes.  If
-   EXITCODE is not NULL the exit code of the process is stored at this
-   address or -1 if it could not be retrieved.  */
-gpg_error_t gnupg_wait_process (const char *pgmname, pid_t pid, int *exitcode);
+/* If HANG is true, waits for the process identified by PID to exit;
+   if HANG is false, checks whether the process has terminated.
+   PGMNAME should be the same as supplied to the spawn function and is
+   only used for diagnostics.  Return values:
+
+   0
+       The process exited successful.  0 is stored at R_EXITCODE.
+
+   GPG_ERR_GENERAL
+       The process exited without success.  The exit code of process
+       is then stored at R_EXITCODE.  An exit code of -1 indicates
+       that the process terminated abnormally (e.g. due to a signal).
+
+   GPG_ERR_TIMEOUT
+       The process is still running (returned only if HANG is false).
+
+   GPG_ERR_INV_VALUE
+       An invalid PID has been specified.
+
+   Other error codes may be returned as well.  Unless otherwise noted,
+   -1 will be stored at R_EXITCODE.  R_EXITCODE may be passed as NULL
+   if the exit code is not required (in that case an error messge will
+   be printed).  Note that under Windows PID is not the process id but
+   the handle of the process.  */
+gpg_error_t gnupg_wait_process (const char *pgmname, pid_t pid, int hang,
+                                int *r_exitcode);
 
 
 /* Kill a process; that is send an appropriate signal to the process.
@@ -94,6 +140,11 @@ gpg_error_t gnupg_wait_process (const char *pgmname, pid_t pid, int *exitcode);
    from the system.  An invalid PID is ignored.  */
 void gnupg_kill_process (pid_t pid);
 
+/* Release the process identified by PID.  This function is actually
+   only required for Windows but it does not harm to always call it.
+   It is a nop if PID is invalid.  */
+void gnupg_release_process (pid_t pid);
+
 
 /* Spawn a new process and immediatley detach from it.  The name of
    the program to exec is PGMNAME and its arguments are in ARGV (the