PrevUpHomeGExecutor Reference Manual

GExecutor

Name

GExecutor -- A class for executing processes.

Synopsis



struct      GExecutor;

GExecutor*  g_executor_new                  (void);
void        g_executor_setup                (GExecutor *executor,
                                             const gchar *working_directory,
                                             const gchar *const argv[],
                                             const gchar *const envp[]);
enum        GExecutorChannel;
gboolean    g_executor_run                  (GExecutor *executor,
                                             GExecutorChannel channels,
                                             GError **error);
gboolean    g_executor_run_sync             (GExecutor *executor,
                                             gchar **standard_output,
                                             gchar **standard_error,
                                             GError **error);
gboolean    g_executor_wait                 (GExecutor *executor);
gboolean    g_executor_kill                 (GExecutor *executor,
                                             int sig);

gboolean    g_executor_is_running           (GExecutor *executor);
GIOChannel* g_executor_get_output_channel   (GExecutor *executor);
GIOChannel* g_executor_get_error_channel    (GExecutor *executor);
GIOChannel* g_executor_get_input_channel    (GExecutor *executor);
gint        g_executor_get_status           (GExecutor *executor);

const gchar* g_executor_get_working_dir     (GExecutor *executor);
gboolean    g_executor_get_joined_output    (GExecutor *executor);
const gchar** g_executor_get_argv           (GExecutor *executor);
const gchar** g_executor_get_envp           (GExecutor *executor);

void        g_executor_set_working_dir      (GExecutor *executor,
                                             const gchar *working_directory);
void        g_executor_set_joined_output    (GExecutor *executor,
                                             gboolean joined_output);
void        g_executor_set_argv             (GExecutor *executor,
                                             const gchar *const argv[]);
void        g_executor_set_envp             (GExecutor *executor,
                                             const gchar *const envp[]);

Object Hierarchy


  GObject
   +----GExecutor

Signal Prototypes


"child-exited"
            void        user_function      (GExecutor *gexecutor,
                                            gpointer user_data);

Description

A GExecutor object simplifies the creation and control of external processes using fork() and exec(). It emits the "child_exited" signal when the child process terminates.

After creating a GExecutor object you specify the current working directory (cwd) for the child process, the argument vector (argv) and its environment (envp). They can be set individually by appropriate functions or toghether by a single call to the convenient function g_executor_setup().

To start executing the process you call g_executor_run() specifying in which standard channels (streams) you are interested in (input, output, error). The GExecutor will automatically create these channels for you.

If the execution started successful you can obtain the channels (as GIOChannel) you required using g_executor_get_output_channel(), g_executor_get_error_channel() and g_executor_get_input_channel(). Reading process' output and writing to its input stream will then be simple.

There are also functions for send signals the child process (g_executor_kill()), and for waiting its termination (g_executor_wait()).

Details

struct GExecutor

struct GExecutor;

All fields are private and should be only accessed by available functions.

g_executor_new ()

GExecutor*  g_executor_new                  (void);

Creates a new GExecutor object.

Returns :

a new GExecutor object.

g_executor_setup ()

void        g_executor_setup                (GExecutor *executor,
                                             const gchar *working_directory,
                                             const gchar *const argv[],
                                             const gchar *const envp[]);

Sets the working_directory, argv and envp. For more details see also: g_executor_set_working_dir(), g_executor_set_argv(), g_executor_set_envp().

The GExecutor must not be running.

executor :

a GExecutor.

working_directory :

the current working directory for the child process.

argv :

the argument vector.

envp :

the environment for the child process.

enum GExecutorChannel

typedef enum {
	G_EXECUTOR_CHANNEL_INPUT = 1 << 0,
	G_EXECUTOR_CHANNEL_OUTPUT = 1 << 1,
	G_EXECUTOR_CHANNEL_ERROR = 1 << 2
} GExecutorChannel;

These are the standard I/O channels (streams) available for the child process.

G_EXECUTOR_CHANNEL_INPUT

standard input.

G_EXECUTOR_CHANNEL_OUTPUT

standard output.

G_EXECUTOR_CHANNEL_ERROR

standard error.

g_executor_run ()

gboolean    g_executor_run                  (GExecutor *executor,
                                             GExecutorChannel channels,
                                             GError **error);

Starts the execution of the child process.

channels is a bit-wise OR of GExecutorChannel that specifies the standard channels that will be created. If the joined_output flag is set you must pass G_EXECUTOR_CHANNEL_OUTPUT and you cannot pass G_EXECUTOR_CHANNEL_ERROR. error is the return location for a GError; you can pass NULL to ignore errors.

The GExecutor must not be running.

executor :

a GExecutor.

channels :

a bit-wise OR of GExecutorChannel.

error :

return location for error.

Returns :

TRUE if child process started successful, FALSE otherwise.

g_executor_run_sync ()

gboolean    g_executor_run_sync             (GExecutor *executor,
                                             gchar **standard_output,
                                             gchar **standard_error,
                                             GError **error);

Executes the child process syncronously. standard_output and standard_error will be filled with the output from the child, if they are non-NULL. You will have to free them. error is the return location for a GError; you can pass NULL to ignore errors.

If child process executed successful, that is the exec() function did not fail, the function returns TRUE.

The GExecutor must not be running.

NOTE: the "child-exited" signal will not be emitted.

executor :

a GExecutor.

standard_output :

return location for child's standard output

standard_error :

return location for child's standard error

error :

return location for error.

Returns :

TRUE if child process executed successful, FALSE otherwise.

g_executor_wait ()

gboolean    g_executor_wait                 (GExecutor *executor);

Blocks until the process terminates.

The GExecutor must be running.

executor :

a GExecutor.

Returns :

TRUE, FALSE only if the child is already terminated by the time of the call.

g_executor_kill ()

gboolean    g_executor_kill                 (GExecutor *executor,
                                             int sig);

Sends a signal to the child process.

The GExecutor must be running.

executor :

a GExecutor.

sig :

the signal number.

Returns :

TRUE if the signal has been sent successful, FALSE only if the child is already terminated by the time of the call.

g_executor_is_running ()

gboolean    g_executor_is_running           (GExecutor *executor);

Checks if the GExecutor is currently running a child process.

executor :

a GExecutor.

Returns :

TRUE if the GExecutor is currently running a child process, FALSE otherwise.

g_executor_get_output_channel ()

GIOChannel* g_executor_get_output_channel   (GExecutor *executor);

Returns a GIOChannel that represent the standard output of the child process. The GIOChannel does not have a reference added, it is up to you to increase its reference count if you store the pointer.

If it does not exists (that is you did not pass the G_EXECUTOR_CHANNEL_OUTPUT flag to g_executor_run() or the execution already terminated) this function returns NULL.

executor :

a GExecutor.

Returns :

a GIOChannel or NULL.

g_executor_get_error_channel ()

GIOChannel* g_executor_get_error_channel    (GExecutor *executor);

Returns a GIOChannel that represent the standard error of the child process. The GIOChannel does not have a reference added, it is up to you to increase its reference count if you store the pointer.

If it does not exists (that is you did not pass the G_EXECUTOR_CHANNEL_ERROR flag to g_executor_run() or the execution already terminated) this function returns NULL.

executor :

a GExecutor.

Returns :

a GIOChannel or NULL.

g_executor_get_input_channel ()

GIOChannel* g_executor_get_input_channel    (GExecutor *executor);

Returns a GIOChannel that represent the standard input of the child process. The GIOChannel does not have a reference added, it is up to you to increase its reference count if you store the pointer.

If it does not exists (that is you did not pass the G_EXECUTOR_CHANNEL_INPUT flag to g_executor_run() or the execution already terminated) this function returns NULL.

executor :

a GExecutor.

Returns :

a GIOChannel or NULL.

g_executor_get_status ()

gint        g_executor_get_status           (GExecutor *executor);

Returns the child exit status as returned by waitpid() syscall.

The GExecutor must not be running.

executor :

a GExecutor.

Returns :

the child exit status.

g_executor_get_working_dir ()

const gchar* g_executor_get_working_dir     (GExecutor *executor);

Gets the working directory for child process. The returned value is owned by the GExecutor, you must not change or free it.

executor :

a GExecutor.

Returns :

the working directory or NULL if none is set.

g_executor_get_joined_output ()

gboolean    g_executor_get_joined_output    (GExecutor *executor);

Gets the joined_output flag.

executor :

a GExecutor.

Returns :

TRUE if the joined_output flag is set, FALSE otherwise.

g_executor_get_argv ()

const gchar** g_executor_get_argv           (GExecutor *executor);

Gets the argument vector for child process. The returned value is owned by the GExecutor, you must not change or free it.

executor :

a GExecutor.

Returns :

the argument vector for child process or NULL if none is set.

g_executor_get_envp ()

const gchar** g_executor_get_envp           (GExecutor *executor);

Gets the environment for child process. The returned value is owned by the GExecutor, you must not change or free it.

executor :

a GExecutor.

Returns :

the environment for child process or NULL if none is set.

g_executor_set_working_dir ()

void        g_executor_set_working_dir      (GExecutor *executor,
                                             const gchar *working_directory);

Sets the working directory for child process: working_directory may be NULL to inherit working directory from parent process.

The GExecutor must not be running.

executor :

a GExecutor.

working_directory :

the working directory for child process.

g_executor_set_joined_output ()

void        g_executor_set_joined_output    (GExecutor *executor,
                                             gboolean joined_output);

Sets the joined_output flag for the GExecutor, that is standard error from child process will be redirected to standard output.

The GExecutor must not be running.

executor :

a GExecutor.

joined_output :

the value.

g_executor_set_argv ()

void        g_executor_set_argv             (GExecutor *executor,
                                             const gchar *const argv[]);

Sets the argument vector for child process. argv is a NULL-terminated array of strings that specifies the program to execute and its arguments. argv[0] must be the path to the program to execute.

The GExecutor must not be running.

executor :

a GExecutor.

argv :

the argument vector for child process.

g_executor_set_envp ()

void        g_executor_set_envp             (GExecutor *executor,
                                             const gchar *const envp[]);

Sets the environment for child process. envp is a NULL-terminated array of strings that specifies the environment for the child process. Each string is in the form "key=value".

The GExecutor must not be running.

executor :

a GExecutor.

envp :

the environment for child process.

Signals

The "child-exited" signal

void        user_function                  (GExecutor *gexecutor,
                                            gpointer user_data);

The child-exited signal is emitted when the child process terminates.

NOTE: if the child process is executed with g_executor_run_sync() this signal is not emitted.

gexecutor :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

<<< GExecutor