## gnome-exec

gnome-exec — Execution of programs from within GNOME applications.

## Synopsis

    #include <libgnome/libgnome.h>

    int         gnome_execute_async             (const char *dir,
                                                 int argc,
                                                 char *const argv[]);
    int         gnome_execute_async_fds         (const char *dir,
                                                 int argc,
                                                 char *const argv[],
                                                 gboolean close_fds);
    int         gnome_execute_async_with_env    (const char *dir,
                                                 int argc,
                                                 char *const argv[],
                                                 int envc,
                                                 char *const envv[]);
    int         gnome_execute_async_with_env_fds
                                                (const char *dir,
                                                 int argc,
                                                 char *const argv[],
                                                 int envc,
                                                 char *const envv[],
                                                 gboolean close_fds);
    int         gnome_execute_shell             (const char *dir,
                                                 const char *commandline);
    int         gnome_execute_shell_fds         (const char *dir,
                                                 const char *commandline,
                                                 gboolean close_fds);
    void        gnome_prepend_terminal_to_vector
                                                (int *argc,
                                                 char ***argv);
    int         gnome_execute_terminal_shell    (const char *dir,
                                                 const char *commandline);
    int         gnome_execute_terminal_shell_fds
                                                (const char *dir,
                                                 const char *commandline,
                                                 gboolean close_fds);

## Description

The gnome-execute family of functions are provided to simplify execution of programs from withing GNOME applications. These routines are required to avoid passing opened file descriptors to a child process (like the X11 sockets and CORBA sockets). They will also make sure to terminate properly.

The range of possibilities goes from the most simple use to the most specialized ones.

## Details

### gnome_execute_async ()

    int         gnome_execute_async             (const char *dir,
                                                 int argc,
                                                 char *const argv[]);

Like `gnome_execute_async_with_env()`, but doesn't add anything to child's environment.

`dir` : | Directory in which child should be executesd, or `NULL` for current directory
`argc` : | Number of arguments
`argv` : | Argument vector to exec child
Returns : | process id of child, or `-1` on error.

### gnome_execute_async_fds ()

    int         gnome_execute_async_fds         (const char *dir,
                                                 int argc,
                                                 char *const argv[],
                                                 gboolean close_fds);

Like `gnome_execute_async_with_env_fds()`, but doesn't add anything to child's environment.

`dir` : | Directory in which child should be executed, or `NULL` for current directory
`argc` : | Number of arguments
`argv` : | Argument vector to exec child
`close_fds` : | If `TRUE`, will close all but file descriptors 0, 1 and 2.
Returns : | process id of child, or `-1` on error.

### gnome_execute_async_with_env ()

    int         gnome_execute_async_with_env    (const char *dir,
                                                 int argc,
                                                 char *const argv[],
                                                 int envc,
                                                 char *const envv[]);

This function forks and executes some program in the background. On error, returns `-1`; in this case, errno should hold a useful value. Searches the path to find the child. Environment settings in `envv` are added to the existing environment -- they do not completely replace it. This function closes all fds besides 0, 1, and 2 for the child

`dir` : | Directory in which child should be executed, or NULL for current directory
`argc` : | Number of arguments
`argv` : | Argument vector to exec child
`envc` : | Number of environment slots
`envv` : | Environment vector
Returns : | the process id, or `-1` on error.

### gnome_execute_async_with_env_fds ()

    int         gnome_execute_async_with_env_fds
                                                (const char *dir,
                                                 int argc,
                                                 char *const argv[],
                                                 int envc,
                                                 char *const envv[],
                                                 gboolean close_fds);

Like `gnome_execute_async_with_env()` but has a flag to decide whether or not to close fd's

`dir` : | Directory in which child should be executed, or `NULL` for current directory
`argc` : | Number of arguments
`argv` : | Argument vector to exec child
`envc` : | Number of environment slots
`envv` : | Environment vector
`close_fds` : | If `TRUE` will close all fds but 0,1, and 2
Returns : | the process id, or `-1` on error.

### gnome_execute_shell ()

    int         gnome_execute_shell             (const char *dir,
                                                 const char *commandline);

Like `gnome_execute_async_with_env()`, but uses the user's shell to run the desired program. Note that the pid of the shell is returned, not the pid of the user's program.

`dir` : | Directory in which child should be executed, or `NULL` for current directory
`commandline` : | Shell command to execute
Returns : | process id of shell, or `-1` on error.

### gnome_execute_shell_fds ()

    int         gnome_execute_shell_fds         (const char *dir,
                                                 const char *commandline,
                                                 gboolean close_fds);

Like `gnome_execute_async_with_env_fds()`, but uses the user's shell to run the desired program. Note that the pid of the shell is returned, not the pid of the user's program.

`dir` : | Directory in which child should be executed, or `NULL` for current directory
`commandline` : | Shell command to execute
`close_fds` : | Like close_fds in `gnome_execute_async_with_env_fds()`
Returns : | process id of shell, or `-1` on error.

### gnome_prepend_terminal_to_vector ()

    void        gnome_prepend_terminal_to_vector
                                                (int *argc,
                                                 char ***argv);

Prepends a terminal (either the one configured as default in the user's GNOME setup, or one of the common xterm emulators) to the passed in vector, modifying it in the process. The vector should be allocated with g_malloc, as this will g_free the original vector. Also all elements must have been allocated separately. That is the standard glib/GNOME way of doing vectors however. If the integer that `argc` points to is negative, the size will first be computed. Also note that passing in pointers to a vector that is empty, will just create a new vector for you.

`argc` : | a pointer to the vector size
`argv` : | a pointer to the vector

### gnome_execute_terminal_shell ()

    int         gnome_execute_terminal_shell    (const char *dir,
                                                 const char *commandline);

Like gnome_execute_async, except that it runs the terminal as well. Note that the pid of the terminal is returned, not the pid of the user's program. If commandline is `NULL`, just the shell is run.

`dir` : | Directory in which child should be executed, or NULL for current directory
`commandline` : | Shell command to execute
Returns : | process id of terminal, or `-1` on error.

### gnome_execute_terminal_shell_fds ()

    int         gnome_execute_terminal_shell_fds
                                                (const char *dir,
                                                 const char *commandline,
                                                 gboolean close_fds);

Like `gnome_execute_shell_fds()`, except that it runs the terminal as well. Note that the pid of the terminal is returned, not the pid of the user's program. If commandline is `NULL`, just the shell is run.

`dir` : | Directory in which child should be executed, or `NULL` for current directory
`commandline` : | Shell command to execute
`close_fds` : | Like close_fds in `gnome_execute_async_with_env_fds()`
Returns : | process id of terminal, or `-1` on error.