/* gspawn.c - Process launching

 *

 *  Copyright 2000 Red Hat, Inc.

 *  g_execvpe implementation based on GNU libc execvp:

 *   Copyright 1991, 92, 95, 96, 97, 98, 99 Free Software Foundation, Inc.

 *

 * This library is free software; you can redistribute it and/or

 * modify it under the terms of the GNU Lesser General Public

 * License as published by the Free Software Foundation; either

 * version 2.1 of the License, or (at your option) any later version.

 *

 * This library is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

 * Lesser General Public License for more details.

 *

 * You should have received a copy of the GNU Lesser General Public License

 * along with this library; if not, see <http://www.gnu.org/licenses/>.

 */

#include "config.h"

#include <sys/time.h>

#include <sys/types.h>

#include <sys/wait.h>

#include <unistd.h>

#include <errno.h>

#include <fcntl.h>

#include <signal.h>

#include <string.h>

#include <stdlib.h>   /* for fdwalk */

#include <dirent.h>

#ifdef HAVE_SYS_SELECT_H

#include <sys/select.h>

#endif /* HAVE_SYS_SELECT_H */

#ifdef HAVE_SYS_RESOURCE_H

#include <sys/resource.h>

#endif /* HAVE_SYS_RESOURCE_H */

#include "gspawn.h"

#include "gthread.h"

#include "glib/gstdio.h"

#include "genviron.h"

#include "gmem.h"

#include "gshell.h"

#include "gstring.h"

#include "gstrfuncs.h"

#include "gtestutils.h"

#include "gutils.h"

#include "glibintl.h"

#include "glib-unix.h"

/**

 * SECTION:spawn

 * @Short_description: process launching

 * @Title: Spawning Processes

 *

 * GLib supports spawning of processes with an API that is more

 * convenient than the bare UNIX fork() and exec().

 *

 * The g_spawn family of functions has synchronous (g_spawn_sync())

 * and asynchronous variants (g_spawn_async(), g_spawn_async_with_pipes()),

 * as well as convenience variants that take a complete shell-like

 * commandline (g_spawn_command_line_sync(), g_spawn_command_line_async()).

 *

 * See #GSubprocess in GIO for a higher-level API that provides

 * stream interfaces for communication with child processes.

 *

 * An example of using g_spawn_async_with_pipes():

 * |[

 * const gchar * const argv[] = { "my-favourite-program", "--args", NULL };

 * gint child_stdout, child_stderr;

 * GPid child_pid;

 * g_autoptr(GError) error = NULL;

 *

 * // Spawn child process.

 * g_spawn_async_with_pipes (NULL, argv, NULL, G_SPAWN_DO_NOT_REAP_CHILD, NULL,

 *                           NULL, &child_pid, NULL, &child_stdout,

 *                           &child_stderr, &error);

 * if (error != NULL)

 *   {

 *     g_error ("Spawning child failed: %s", error->message);

 *     return;

 *   }

 *

 * // Add a child watch function which will be called when the child process

 * // exits.

 * g_child_watch_add (child_pid, child_watch_cb, NULL);

 *

 * // You could watch for output on @child_stdout and @child_stderr using

 * // #GUnixInputStream or #GIOChannel here.

 *

 * static void

 * child_watch_cb (GPid     pid,

 *                 gint     status,

 *                 gpointer user_data)

 * {

 *   g_message ("Child %" G_PID_FORMAT " exited %s", pid,

 *              g_spawn_check_exit_status (status, NULL) ? "normally" : "abnormally");

 *

 *   // Free any resources associated with the child here, such as I/O channels

 *   // on its stdout and stderr FDs. If you have no code to put in the

 *   // child_watch_cb() callback, you can remove it and the g_child_watch_add()

 *   // call, but you must also remove the G_SPAWN_DO_NOT_REAP_CHILD flag,

 *   // otherwise the child process will stay around as a zombie until this

 *   // process exits.

 *

 *   g_spawn_close_pid (pid);

 * }

 * ]|

 */

static gint g_execute (const gchar  *file,

                       gchar **argv,

                       gchar **envp,

                       gboolean search_path,

                       gboolean search_path_from_envp);

static gboolean fork_exec_with_pipes (gboolean              intermediate_child,

                                      const gchar          *working_directory,

                                      gchar               **argv,

                                      gchar               **envp,

                                      gboolean              close_descriptors,

                                      gboolean              search_path,

                                      gboolean              search_path_from_envp,

                                      gboolean              stdout_to_null,

                                      gboolean              stderr_to_null,

                                      gboolean              child_inherits_stdin,

                                      gboolean              file_and_argv_zero,

                                      gboolean              cloexec_pipes,

                                      GSpawnChildSetupFunc  child_setup,

                                      gpointer              user_data,

                                      GPid                 *child_pid,

                                      gint                 *standard_input,

                                      gint                 *standard_output,

                                      gint                 *standard_error,

                                      GError              **error);

G_DEFINE_QUARK (g-exec-error-quark, g_spawn_error)

G_DEFINE_QUARK (g-spawn-exit-error-quark, g_spawn_exit_error)

/**

 * g_spawn_async:

 * @working_directory: (type filename) (nullable): child's current working

 *     directory, or %NULL to inherit parent's

 * @argv: (array zero-terminated=1) (element-type filename):

 *     child's argument vector

 * @envp: (array zero-terminated=1) (element-type filename) (nullable):

 *     child's environment, or %NULL to inherit parent's

 * @flags: flags from #GSpawnFlags

 * @child_setup: (scope async) (nullable): function to run in the child just before exec()

 * @user_data: (closure): user data for @child_setup

 * @child_pid: (out) (optional): return location for child process reference, or %NULL

 * @error: return location for error

 * 

 * See g_spawn_async_with_pipes() for a full description; this function

 * simply calls the g_spawn_async_with_pipes() without any pipes.

 *

 * You should call g_spawn_close_pid() on the returned child process

 * reference when you don't need it any more.

 * 

 * If you are writing a GTK+ application, and the program you are spawning is a

 * graphical application too, then to ensure that the spawned program opens its

 * windows on the right screen, you may want to use #GdkAppLaunchContext,

 * #GAppLaunchContext, or set the %DISPLAY environment variable.

 *

 * Note that the returned @child_pid on Windows is a handle to the child

 * process and not its identifier. Process handles and process identifiers

 * are different concepts on Windows.

 *

 * Returns: %TRUE on success, %FALSE if error is set

 **/

gboolean

g_spawn_async (const gchar          *working_directory,

               gchar               **argv,

               gchar               **envp,

               GSpawnFlags           flags,

               GSpawnChildSetupFunc  child_setup,

               gpointer              user_data,

               GPid                 *child_pid,

               GError              **error)

{

  g_return_val_if_fail (argv != NULL, FALSE);

  return g_spawn_async_with_pipes (working_directory,

                                   argv, envp,

                                   flags,

                                   child_setup,

                                   user_data,

                                   child_pid,

                                   NULL, NULL, NULL,

                                   error);

}

/* Avoids a danger in threaded situations (calling close()

 * on a file descriptor twice, and another thread has

 * re-opened it since the first close)

 */

static void

close_and_invalidate (gint *fd)

{

  if (*fd < 0)

    return;

  else

    {

      (void) g_close (*fd, NULL);

      *fd = -1;

    }

}

/* Some versions of OS X define READ_OK in public headers */

#undef READ_OK

typedef enum

{

  READ_FAILED = 0, /* FALSE */

  READ_OK,

  READ_EOF

} ReadResult;

static ReadResult

read_data (GString *str,

           gint     fd,

           GError **error)

{

  gssize bytes;

  gchar buf[4096];

 again:

  bytes = read (fd, buf, 4096);

  if (bytes == 0)

    return READ_EOF;

  else if (bytes > 0)

    {

      g_string_append_len (str, buf, bytes);

      return READ_OK;

    }

  else if (errno == EINTR)

    goto again;

  else

    {

      int errsv = errno;

      g_set_error (error,

                   G_SPAWN_ERROR,

                   G_SPAWN_ERROR_READ,

                   _("Failed to read data from child process (%s)"),

                   g_strerror (errsv));

      return READ_FAILED;

    }

}

/**

 * g_spawn_sync:

 * @working_directory: (type filename) (nullable): child's current working

 *     directory, or %NULL to inherit parent's

 * @argv: (array zero-terminated=1) (element-type filename):

 *     child's argument vector

 * @envp: (array zero-terminated=1) (element-type filename) (nullable):

 *     child's environment, or %NULL to inherit parent's

 * @flags: flags from #GSpawnFlags

 * @child_setup: (scope async) (nullable): function to run in the child just before exec()

 * @user_data: (closure): user data for @child_setup

 * @standard_output: (out) (array zero-terminated=1) (element-type guint8) (optional): return location for child output, or %NULL

 * @standard_error: (out) (array zero-terminated=1) (element-type guint8) (optional): return location for child error messages, or %NULL

 * @exit_status: (out) (optional): return location for child exit status, as returned by waitpid(), or %NULL

 * @error: return location for error, or %NULL

 *

 * Executes a child synchronously (waits for the child to exit before returning).

 * All output from the child is stored in @standard_output and @standard_error,

 * if those parameters are non-%NULL. Note that you must set the  

 * %G_SPAWN_STDOUT_TO_DEV_NULL and %G_SPAWN_STDERR_TO_DEV_NULL flags when

 * passing %NULL for @standard_output and @standard_error.

 *

 * If @exit_status is non-%NULL, the platform-specific exit status of

 * the child is stored there; see the documentation of

 * g_spawn_check_exit_status() for how to use and interpret this.

 * Note that it is invalid to pass %G_SPAWN_DO_NOT_REAP_CHILD in

 * @flags, and on POSIX platforms, the same restrictions as for

 * g_child_watch_source_new() apply.

 *

 * If an error occurs, no data is returned in @standard_output,

 * @standard_error, or @exit_status.

 *

 * This function calls g_spawn_async_with_pipes() internally; see that

 * function for full details on the other parameters and details on

 * how these functions work on Windows.

 * 

 * Returns: %TRUE on success, %FALSE if an error was set

 */

gboolean

g_spawn_sync (const gchar          *working_directory,

              gchar               **argv,

              gchar               **envp,

              GSpawnFlags           flags,

              GSpawnChildSetupFunc  child_setup,

              gpointer              user_data,

              gchar               **standard_output,

              gchar               **standard_error,

              gint                 *exit_status,

              GError              **error)     

{

  gint outpipe = -1;

  gint errpipe = -1;

  GPid pid;

  fd_set fds;

  gint ret;

  GString *outstr = NULL;

  GString *errstr = NULL;

  gboolean failed;

  gint status;

  g_return_val_if_fail (argv != NULL, FALSE);

  g_return_val_if_fail (!(flags & G_SPAWN_DO_NOT_REAP_CHILD), FALSE);

  g_return_val_if_fail (standard_output == NULL ||

                        !(flags & G_SPAWN_STDOUT_TO_DEV_NULL), FALSE);

  g_return_val_if_fail (standard_error == NULL ||

                        !(flags & G_SPAWN_STDERR_TO_DEV_NULL), FALSE);

  /* Just to ensure segfaults if callers try to use

   * these when an error is reported.

   */

  if (standard_output)

    *standard_output = NULL;

  if (standard_error)

    *standard_error = NULL;

  if (!fork_exec_with_pipes (FALSE,

                             working_directory,

                             argv,

                             envp,

                             !(flags & G_SPAWN_LEAVE_DESCRIPTORS_OPEN),

                             (flags & G_SPAWN_SEARCH_PATH) != 0,

                             (flags & G_SPAWN_SEARCH_PATH_FROM_ENVP) != 0,

                             (flags & G_SPAWN_STDOUT_TO_DEV_NULL) != 0,

                             (flags & G_SPAWN_STDERR_TO_DEV_NULL) != 0,

                             (flags & G_SPAWN_CHILD_INHERITS_STDIN) != 0,

                             (flags & G_SPAWN_FILE_AND_ARGV_ZERO) != 0,

                             (flags & G_SPAWN_CLOEXEC_PIPES) != 0,

                             child_setup,

                             user_data,

                             &pid,

                             NULL,

                             standard_output ? &outpipe : NULL,

                             standard_error ? &errpipe : NULL,

                             error))

    return FALSE;

  /* Read data from child. */

  failed = FALSE;

  if (outpipe >= 0)

    {

      outstr = g_string_new (NULL);

    }

  if (errpipe >= 0)

    {

      errstr = g_string_new (NULL);

    }

  /* Read data until we get EOF on both pipes. */

  while (!failed &&

         (outpipe >= 0 ||

          errpipe >= 0))

    {

      ret = 0;

      FD_ZERO (&fds);

      if (outpipe >= 0)

        FD_SET (outpipe, &fds);

      if (errpipe >= 0)

        FD_SET (errpipe, &fds);

      ret = select (MAX (outpipe, errpipe) + 1,

                    &fds,

                    NULL, NULL,

                    NULL /* no timeout */);

      if (ret < 0)

        {

          int errsv = errno;

	  if (errno == EINTR)

	    continue;

          failed = TRUE;

          g_set_error (error,

                       G_SPAWN_ERROR,

                       G_SPAWN_ERROR_READ,

                       _("Unexpected error in select() reading data from a child process (%s)"),

                       g_strerror (errsv));

          break;

        }

      if (outpipe >= 0 && FD_ISSET (outpipe, &fds))

        {

          switch (read_data (outstr, outpipe, error))

            {

            case READ_FAILED:

              failed = TRUE;

              break;

            case READ_EOF:

              close_and_invalidate (&outpipe);

              outpipe = -1;

              break;

            default:

              break;

            }

          if (failed)

            break;

        }

      if (errpipe >= 0 && FD_ISSET (errpipe, &fds))

        {

          switch (read_data (errstr, errpipe, error))

            {

            case READ_FAILED:

              failed = TRUE;

              break;

            case READ_EOF:

              close_and_invalidate (&errpipe);

              errpipe = -1;

              break;

            default:

              break;

            }

          if (failed)

            break;

        }

    }

  /* These should only be open still if we had an error.  */

  if (outpipe >= 0)

    close_and_invalidate (&outpipe);

  if (errpipe >= 0)

    close_and_invalidate (&errpipe);

  /* Wait for child to exit, even if we have

   * an error pending.

   */

 again:

  ret = waitpid (pid, &status, 0);

  if (ret < 0)

    {

      if (errno == EINTR)

        goto again;

      else if (errno == ECHILD)

        {

          if (exit_status)

            {

              g_warning ("In call to g_spawn_sync(), exit status of a child process was requested but ECHILD was received by waitpid(). See the documentation of g_child_watch_source_new() for possible causes.");

            }

          else

            {

              /* We don't need the exit status. */

            }

        }

      else

        {

          if (!failed) /* avoid error pileups */

            {

              int errsv = errno;

              failed = TRUE;

              g_set_error (error,

                           G_SPAWN_ERROR,

                           G_SPAWN_ERROR_READ,

                           _("Unexpected error in waitpid() (%s)"),

                           g_strerror (errsv));

            }

        }

    }

  if (failed)

    {

      if (outstr)

        g_string_free (outstr, TRUE);

      if (errstr)

        g_string_free (errstr, TRUE);

      return FALSE;

    }

  else

    {

      if (exit_status)

        *exit_status = status;

      if (standard_output)        

        *standard_output = g_string_free (outstr, FALSE);

      if (standard_error)

        *standard_error = g_string_free (errstr, FALSE);

      return TRUE;

    }

}

/**

 * g_spawn_async_with_pipes:

 * @working_directory: (type filename) (nullable): child's current working

 *     directory, or %NULL to inherit parent's, in the GLib file name encoding

 * @argv: (array zero-terminated=1) (element-type filename): child's argument

 *     vector, in the GLib file name encoding

 * @envp: (array zero-terminated=1) (element-type filename) (nullable):

 *     child's environment, or %NULL to inherit parent's, in the GLib file

 *     name encoding

 * @flags: flags from #GSpawnFlags

 * @child_setup: (scope async) (nullable): function to run in the child just before exec()

 * @user_data: (closure): user data for @child_setup

 * @child_pid: (out) (optional): return location for child process ID, or %NULL

 * @standard_input: (out) (optional): return location for file descriptor to write to child's stdin, or %NULL

 * @standard_output: (out) (optional): return location for file descriptor to read child's stdout, or %NULL

 * @standard_error: (out) (optional): return location for file descriptor to read child's stderr, or %NULL

 * @error: return location for error

 *

 * Executes a child program asynchronously (your program will not

 * block waiting for the child to exit). The child program is

 * specified by the only argument that must be provided, @argv.

 * @argv should be a %NULL-terminated array of strings, to be passed

 * as the argument vector for the child. The first string in @argv

 * is of course the name of the program to execute. By default, the

 * name of the program must be a full path. If @flags contains the

 * %G_SPAWN_SEARCH_PATH flag, the `PATH` environment variable is

 * used to search for the executable. If @flags contains the

 * %G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the `PATH` variable from 

 * @envp is used to search for the executable. If both the

 * %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP flags

 * are set, the `PATH` variable from @envp takes precedence over

 * the environment variable.

 *

 * If the program name is not a full path and %G_SPAWN_SEARCH_PATH flag is not

 * used, then the program will be run from the current directory (or

 * @working_directory, if specified); this might be unexpected or even

 * dangerous in some cases when the current directory is world-writable.

 *

 * On Windows, note that all the string or string vector arguments to

 * this function and the other g_spawn*() functions are in UTF-8, the

 * GLib file name encoding. Unicode characters that are not part of

 * the system codepage passed in these arguments will be correctly

 * available in the spawned program only if it uses wide character API

 * to retrieve its command line. For C programs built with Microsoft's

 * tools it is enough to make the program have a wmain() instead of

 * main(). wmain() has a wide character argument vector as parameter.

 *

 * At least currently, mingw doesn't support wmain(), so if you use

 * mingw to develop the spawned program, it should call

 * g_win32_get_command_line() to get arguments in UTF-8.

 *

 * On Windows the low-level child process creation API CreateProcess()

 * doesn't use argument vectors, but a command line. The C runtime

 * library's spawn*() family of functions (which g_spawn_async_with_pipes()

 * eventually calls) paste the argument vector elements together into

 * a command line, and the C runtime startup code does a corresponding

 * reconstruction of an argument vector from the command line, to be

 * passed to main(). Complications arise when you have argument vector

 * elements that contain spaces of double quotes. The spawn*() functions

 * don't do any quoting or escaping, but on the other hand the startup

 * code does do unquoting and unescaping in order to enable receiving

 * arguments with embedded spaces or double quotes. To work around this

 * asymmetry, g_spawn_async_with_pipes() will do quoting and escaping on

 * argument vector elements that need it before calling the C runtime

 * spawn() function.

 *

 * The returned @child_pid on Windows is a handle to the child

 * process, not its identifier. Process handles and process

 * identifiers are different concepts on Windows.

 *

 * @envp is a %NULL-terminated array of strings, where each string

 * has the form `KEY=VALUE`. This will become the child's environment.

 * If @envp is %NULL, the child inherits its parent's environment.

 *

 * @flags should be the bitwise OR of any flags you want to affect the

 * function's behaviour. The %G_SPAWN_DO_NOT_REAP_CHILD means that the

 * child will not automatically be reaped; you must use a child watch

 * (g_child_watch_add()) to be notified about the death of the child process,

 * otherwise it will stay around as a zombie process until this process exits.

 * Eventually you must call g_spawn_close_pid() on the @child_pid, in order to

 * free resources which may be associated with the child process. (On Unix,

 * using a child watch is equivalent to calling waitpid() or handling

 * the %SIGCHLD signal manually. On Windows, calling g_spawn_close_pid()

 * is equivalent to calling CloseHandle() on the process handle returned

 * in @child_pid). See g_child_watch_add().

 *

 * %G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that the parent's open file

 * descriptors will be inherited by the child; otherwise all descriptors

 * except stdin/stdout/stderr will be closed before calling exec() in

 * the child. %G_SPAWN_SEARCH_PATH means that @argv[0] need not be an

 * absolute path, it will be looked for in the `PATH` environment

 * variable. %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an

 * absolute path, it will be looked for in the `PATH` variable from

 * @envp. If both %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP

 * are used, the value from @envp takes precedence over the environment.

 * %G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output

 * will be discarded, instead of going to the same location as the parent's 

 * standard output. If you use this flag, @standard_output must be %NULL.

 * %G_SPAWN_STDERR_TO_DEV_NULL means that the child's standard error

 * will be discarded, instead of going to the same location as the parent's

 * standard error. If you use this flag, @standard_error must be %NULL.

 * %G_SPAWN_CHILD_INHERITS_STDIN means that the child will inherit the parent's

 * standard input (by default, the child's standard input is attached to

 * `/dev/null`). If you use this flag, @standard_input must be %NULL.

 * %G_SPAWN_FILE_AND_ARGV_ZERO means that the first element of @argv is

 * the file to execute, while the remaining elements are the actual

 * argument vector to pass to the file. Normally g_spawn_async_with_pipes()

 * uses @argv[0] as the file to execute, and passes all of @argv to the child.

 *

 * @child_setup and @user_data are a function and user data. On POSIX

 * platforms, the function is called in the child after GLib has

 * performed all the setup it plans to perform (including creating

 * pipes, closing file descriptors, etc.) but before calling exec().

 * That is, @child_setup is called just before calling exec() in the

 * child. Obviously actions taken in this function will only affect

 * the child, not the parent.

 *

 * On Windows, there is no separate fork() and exec() functionality.

 * Child processes are created and run with a single API call,

 * CreateProcess(). There is no sensible thing @child_setup

 * could be used for on Windows so it is ignored and not called.

 *

 * If non-%NULL, @child_pid will on Unix be filled with the child's

 * process ID. You can use the process ID to send signals to the child,

 * or to use g_child_watch_add() (or waitpid()) if you specified the

 * %G_SPAWN_DO_NOT_REAP_CHILD flag. On Windows, @child_pid will be

 * filled with a handle to the child process only if you specified the

 * %G_SPAWN_DO_NOT_REAP_CHILD flag. You can then access the child

 * process using the Win32 API, for example wait for its termination

 * with the WaitFor*() functions, or examine its exit code with

 * GetExitCodeProcess(). You should close the handle with CloseHandle()

 * or g_spawn_close_pid() when you no longer need it.

 *

 * If non-%NULL, the @standard_input, @standard_output, @standard_error

 * locations will be filled with file descriptors for writing to the child's

 * standard input or reading from its standard output or standard error.

 * The caller of g_spawn_async_with_pipes() must close these file descriptors

 * when they are no longer in use. If these parameters are %NULL, the

 * corresponding pipe won't be created.

 *

 * If @standard_input is %NULL, the child's standard input is attached to

 * `/dev/null` unless %G_SPAWN_CHILD_INHERITS_STDIN is set.

 *

 * If @standard_error is NULL, the child's standard error goes to the same 

 * location as the parent's standard error unless %G_SPAWN_STDERR_TO_DEV_NULL 

 * is set.

 *

 * If @standard_output is NULL, the child's standard output goes to the same 

 * location as the parent's standard output unless %G_SPAWN_STDOUT_TO_DEV_NULL 

 * is set.

 *

 * @error can be %NULL to ignore errors, or non-%NULL to report errors.

 * If an error is set, the function returns %FALSE. Errors are reported

 * even if they occur in the child (for example if the executable in

 * @argv[0] is not found). Typically the `message` field of returned

 * errors should be displayed to users. Possible errors are those from

 * the #G_SPAWN_ERROR domain.

 *

 * If an error occurs, @child_pid, @standard_input, @standard_output,

 * and @standard_error will not be filled with valid values.

 *

 * If @child_pid is not %NULL and an error does not occur then the returned

 * process reference must be closed using g_spawn_close_pid().

 *

 * If you are writing a GTK+ application, and the program you are spawning is a

 * graphical application too, then to ensure that the spawned program opens its

 * windows on the right screen, you may want to use #GdkAppLaunchContext,

 * #GAppLaunchContext, or set the %DISPLAY environment variable.

 * 

 * Returns: %TRUE on success, %FALSE if an error was set

 */

gboolean

g_spawn_async_with_pipes (const gchar          *working_directory,

                          gchar               **argv,

                          gchar               **envp,

                          GSpawnFlags           flags,

                          GSpawnChildSetupFunc  child_setup,

                          gpointer              user_data,

                          GPid                 *child_pid,

                          gint                 *standard_input,

                          gint                 *standard_output,

                          gint                 *standard_error,

                          GError              **error)

{

  g_return_val_if_fail (argv != NULL, FALSE);

  g_return_val_if_fail (standard_output == NULL ||

                        !(flags & G_SPAWN_STDOUT_TO_DEV_NULL), FALSE);

  g_return_val_if_fail (standard_error == NULL ||

                        !(flags & G_SPAWN_STDERR_TO_DEV_NULL), FALSE);

  /* can't inherit stdin if we have an input pipe. */

  g_return_val_if_fail (standard_input == NULL ||

                        !(flags & G_SPAWN_CHILD_INHERITS_STDIN), FALSE);

  return fork_exec_with_pipes (!(flags & G_SPAWN_DO_NOT_REAP_CHILD),

                               working_directory,

                               argv,

                               envp,

                               !(flags & G_SPAWN_LEAVE_DESCRIPTORS_OPEN),

                               (flags & G_SPAWN_SEARCH_PATH) != 0,

                               (flags & G_SPAWN_SEARCH_PATH_FROM_ENVP) != 0,

                               (flags & G_SPAWN_STDOUT_TO_DEV_NULL) != 0,

                               (flags & G_SPAWN_STDERR_TO_DEV_NULL) != 0,

                               (flags & G_SPAWN_CHILD_INHERITS_STDIN) != 0,

                               (flags & G_SPAWN_FILE_AND_ARGV_ZERO) != 0,

                               (flags & G_SPAWN_CLOEXEC_PIPES) != 0,

                               child_setup,

                               user_data,

                               child_pid,

                               standard_input,

                               standard_output,

                               standard_error,

                               error);

}

/**

 * g_spawn_command_line_sync:

 * @command_line: (type filename): a command line

 * @standard_output: (out) (array zero-terminated=1) (element-type guint8) (optional): return location for child output

 * @standard_error: (out) (array zero-terminated=1) (element-type guint8) (optional): return location for child errors

 * @exit_status: (out) (optional): return location for child exit status, as returned by waitpid()

 * @error: return location for errors

 *

 * A simple version of g_spawn_sync() with little-used parameters

 * removed, taking a command line instead of an argument vector.  See

 * g_spawn_sync() for full details. @command_line will be parsed by

 * g_shell_parse_argv(). Unlike g_spawn_sync(), the %G_SPAWN_SEARCH_PATH flag

 * is enabled. Note that %G_SPAWN_SEARCH_PATH can have security

 * implications, so consider using g_spawn_sync() directly if

 * appropriate. Possible errors are those from g_spawn_sync() and those

 * from g_shell_parse_argv().

 *

 * If @exit_status is non-%NULL, the platform-specific exit status of

 * the child is stored there; see the documentation of

 * g_spawn_check_exit_status() for how to use and interpret this.

 * 

 * On Windows, please note the implications of g_shell_parse_argv()

 * parsing @command_line. Parsing is done according to Unix shell rules, not 

 * Windows command interpreter rules.

 * Space is a separator, and backslashes are

 * special. Thus you cannot simply pass a @command_line containing

 * canonical Windows paths, like "c:\\program files\\app\\app.exe", as

 * the backslashes will be eaten, and the space will act as a

 * separator. You need to enclose such paths with single quotes, like

 * "'c:\\program files\\app\\app.exe' 'e:\\folder\\argument.txt'".

 *

 * Returns: %TRUE on success, %FALSE if an error was set

 **/

gboolean

g_spawn_command_line_sync (const gchar  *command_line,

                           gchar       **standard_output,

                           gchar       **standard_error,

                           gint         *exit_status,

                           GError      **error)

{

  gboolean retval;

  gchar **argv = NULL;

  g_return_val_if_fail (command_line != NULL, FALSE);

  if (!g_shell_parse_argv (command_line,

                           NULL, &argv,

                           error))

    return FALSE;

  retval = g_spawn_sync (NULL,

                         argv,

                         NULL,

                         G_SPAWN_SEARCH_PATH,

                         NULL,

                         NULL,

                         standard_output,

                         standard_error,

                         exit_status,

                         error);

  g_strfreev (argv);

  return retval;

}

/**

 * g_spawn_command_line_async:

 * @command_line: (type filename): a command line

 * @error: return location for errors

 * 

 * A simple version of g_spawn_async() that parses a command line with

 * g_shell_parse_argv() and passes it to g_spawn_async(). Runs a

 * command line in the background. Unlike g_spawn_async(), the

 * %G_SPAWN_SEARCH_PATH flag is enabled, other flags are not. Note

 * that %G_SPAWN_SEARCH_PATH can have security implications, so

 * consider using g_spawn_async() directly if appropriate. Possible

 * errors are those from g_shell_parse_argv() and g_spawn_async().

 * 

 * The same concerns on Windows apply as for g_spawn_command_line_sync().

 *

 * Returns: %TRUE on success, %FALSE if error is set

 **/

gboolean

g_spawn_command_line_async (const gchar *command_line,

                            GError     **error)

{

  gboolean retval;

  gchar **argv = NULL;

  g_return_val_if_fail (command_line != NULL, FALSE);

  if (!g_shell_parse_argv (command_line,

                           NULL, &argv,

                           error))

    return FALSE;

  retval = g_spawn_async (NULL,

                          argv,

                          NULL,

                          G_SPAWN_SEARCH_PATH,

                          NULL,

                          NULL,

                          NULL,

                          error);

  g_strfreev (argv);

  return retval;

}

/**

 * g_spawn_check_exit_status:

 * @exit_status: An exit code as returned from g_spawn_sync()

 * @error: a #GError

 *

 * Set @error if @exit_status indicates the child exited abnormally

 * (e.g. with a nonzero exit code, or via a fatal signal).

 *

 * The g_spawn_sync() and g_child_watch_add() family of APIs return an

 * exit status for subprocesses encoded in a platform-specific way.

 * On Unix, this is guaranteed to be in the same format waitpid() returns,

 * and on Windows it is guaranteed to be the result of GetExitCodeProcess().

 *

 * Prior to the introduction of this function in GLib 2.34, interpreting

 * @exit_status required use of platform-specific APIs, which is problematic

 * for software using GLib as a cross-platform layer.

 *

 * Additionally, many programs simply want to determine whether or not

 * the child exited successfully, and either propagate a #GError or

 * print a message to standard error. In that common case, this function

 * can be used. Note that the error message in @error will contain

 * human-readable information about the exit status.

 *

 * The @domain and @code of @error have special semantics in the case

 * where the process has an "exit code", as opposed to being killed by

 * a signal. On Unix, this happens if WIFEXITED() would be true of

 * @exit_status. On Windows, it is always the case.

 *

 * The special semantics are that the actual exit code will be the

 * code set in @error, and the domain will be %G_SPAWN_EXIT_ERROR.

 * This allows you to differentiate between different exit codes.

 *

 * If the process was terminated by some means other than an exit

 * status, the domain will be %G_SPAWN_ERROR, and the code will be

 * %G_SPAWN_ERROR_FAILED.

 *

 * This function just offers convenience; you can of course also check

 * the available platform via a macro such as %G_OS_UNIX, and use

 * WIFEXITED() and WEXITSTATUS() on @exit_status directly. Do not attempt

 * to scan or parse the error message string; it may be translated and/or

 * change in future versions of GLib.

 *