External command

External command — Convenience API for using external command.

Synopsis

#define             GCUT_EGG_ERROR
                    GCutEgg;
enum                GCutEggError;
GQuark              gcut_egg_error_quark                (void);
GCutEgg *           gcut_egg_new                        (const gchar *command,
                                                         ...);
GCutEgg *           gcut_egg_new_va_list                (const gchar *command,
                                                         va_list args);
GCutEgg *           gcut_egg_new_argv                   (gint argc,
                                                         gchar **argv);
GCutEgg *           gcut_egg_new_strings                (const gchar **command);
GCutEgg *           gcut_egg_new_array                  (GArray *command);
void                gcut_egg_set_flags                  (GCutEgg *egg,
                                                         GSpawnFlags flags);
GSpawnFlags         gcut_egg_get_flags                  (GCutEgg *egg);
void                gcut_egg_set_env                    (GCutEgg *egg,
                                                         const gchar *name,
                                                         ...);
gchar **            gcut_egg_get_env                    (GCutEgg *egg);
gboolean            gcut_egg_hatch                      (GCutEgg *egg,
                                                         GError **error);
void                gcut_egg_close                      (GCutEgg *egg);
gboolean            gcut_egg_write                      (GCutEgg *egg,
                                                         const gchar *chunk,
                                                         gsize size,
                                                         GError **error);
GPid                gcut_egg_get_pid                    (GCutEgg *egg);
gint                gcut_egg_wait                       (GCutEgg *egg,
                                                         guint timeout,
                                                         GError **error);
void                gcut_egg_kill                       (GCutEgg *egg,
                                                         gint signal_number);
GIOChannel *        gcut_egg_get_input                  (GCutEgg *egg);
GIOChannel *        gcut_egg_get_output                 (GCutEgg *egg);
GIOChannel *        gcut_egg_get_error                  (GCutEgg *egg);
guint               gcut_egg_get_forced_termination_wait_time
                                                        (GCutEgg *egg);
void                gcut_egg_set_forced_termination_wait_time
                                                        (GCutEgg *egg,
                                                         guint timeout);

Object Hierarchy

  GObject
   +----GCutEgg

Properties

  "command"                  gpointer              : Read / Write

Signals

  "error"                                          : Run Last
  "error-received"                                 : Run Last
  "output-received"                                : Run Last
  "reaped"                                         : Run Last

Description

GCutEgg encapsulates external command execution, communication and termination. GCutEgg reports an error as GError. It can be asserted easily by gcut_assert_error().

External command is specified to constructor like gcut_egg_new(), gcut_egg_new_strings() and so on. External command isn't run at the time. gcut_egg_hatch() runs specified external command.

Standard/Error outputs of external command are passed by "output-received"/"error-received" signals or GIOChannel returned by gcut_egg_get_output()/gcut_egg_get_error(). gcut_egg_write() writes a chunk to standard input of external command.

To wait external command finished, gcut_egg_wait() can be used. It accepts timeout to avoid infinite waiting.

e.g.:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
static GString *output_string;
static GCutEgg *egg;

void
cut_setup (void)
{
    output_string = g_string_new(NULL);
    egg = NULL;
}

void
cut_teardown (void)
{
    if (output_string)
        g_string_free(output_string, TRUE);
    if (egg)
        g_object_unref(egg);
}

static void
cb_output_received (GCutEgg *egg, const gchar *chunk, gsize size,
                    gpointer user_data)
{
    g_string_append_len(output_string, chunk, size);
}
void
test_echo (void)
{
    GError *error = NULL;

    egg = gcut_egg_new("echo", "XXX", NULL);
    g_signal_connect(egg, "receive-output",
                     G_CALLBACK(cb_output_received), NULL);

    gcut_egg_hatch(egg, &error);
    gcut_assert_error(error);

    gcut_egg_wait(egg, 1000, &error);
    gcut_assert_error(error);
    cut_assert_equal_string("XXX\n", output_string->str);
}

Details

GCUT_EGG_ERROR

#define GCUT_EGG_ERROR           (gcut_egg_error_quark())


GCutEgg

typedef struct _GCutEgg GCutEgg;


enum GCutEggError

typedef enum
{
    GCUT_EGG_ERROR_COMMAND_LINE,
    GCUT_EGG_ERROR_IO_ERROR,
    GCUT_EGG_ERROR_ALREADY_RUNNING,
    GCUT_EGG_ERROR_NOT_RUNNING,
    GCUT_EGG_ERROR_INVALID_OBJECT,
    GCUT_EGG_ERROR_TIMEOUT
} GCutEggError;

Error codes returned by GCutEgg related operations.

GCUT_EGG_ERROR_COMMAND_LINE

Command line related error.

GCUT_EGG_ERROR_IO_ERROR

IO error.

GCUT_EGG_ERROR_ALREADY_RUNNING

External command is already running.

GCUT_EGG_ERROR_NOT_RUNNING

External command isn't running.

GCUT_EGG_ERROR_INVALID_OBJECT

Invalid GCutEgg object is passed.

GCUT_EGG_ERROR_TIMEOUT

Timeout.

Since 1.0.6


gcut_egg_error_quark ()

GQuark              gcut_egg_error_quark                (void);

Returns :


gcut_egg_new ()

GCutEgg *           gcut_egg_new                        (const gchar *command,
                                                         ...);

Creates a new GCutEgg object that runs command.

command :

the external command name to be ran

... :

the arguments for command

Returns :

a new GCutEgg.

Since 1.0.6


gcut_egg_new_va_list ()

GCutEgg *           gcut_egg_new_va_list                (const gchar *command,
                                                         va_list args);

Creates a new GCutEgg object that runs command.

command :

the external command name to be ran

args :

arguments for command

Returns :

a new GCutEgg.

Since 1.0.6


gcut_egg_new_argv ()

GCutEgg *           gcut_egg_new_argv                   (gint argc,
                                                         gchar **argv);

Creates a new GCutEgg object that runs command.

argc :

the number of elements of argv

argv :

the external command name to be ran and arguments of it.

Returns :

a new GCutEgg.

Since 1.0.6


gcut_egg_new_strings ()

GCutEgg *           gcut_egg_new_strings                (const gchar **command);

Creates a new GCutEgg object that runs command.

command :

the external command name to be ran and arguments of it. NULL-terminated.

Returns :

a new GCutEgg.

Since 1.0.6


gcut_egg_new_array ()

GCutEgg *           gcut_egg_new_array                  (GArray *command);

Creates a new GCutEgg object that runs command.

command :

the external command name to be ran and arguments of it. The GArray should be zero-terminated.

Returns :

a new GCutEgg.

Since 1.0.6


gcut_egg_set_flags ()

void                gcut_egg_set_flags                  (GCutEgg *egg,
                                                         GSpawnFlags flags);

Sets flags for spawning.

egg :

a GCutEgg

flags :

the flags to be passed to g_spawn_async_with_pipes().

Since 1.0.6


gcut_egg_get_flags ()

GSpawnFlags         gcut_egg_get_flags                  (GCutEgg *egg);

Gets flags for spawning.

egg :

a GCutEgg

Returns :

the flags for spawning.

Since 1.0.6


gcut_egg_set_env ()

void                gcut_egg_set_env                    (GCutEgg *egg,
                                                         const gchar *name,
                                                         ...);

Sets environment variable for external command.

egg :

a GCutEgg

name :

the first environment name.

... :

the value of name, followed by name and value pairs. NULL-terminated.

Since 1.0.6


gcut_egg_get_env ()

gchar **            gcut_egg_get_env                    (GCutEgg *egg);

Gets environment variable for external command.

egg :

a GCutEgg

Returns :

a newly-allocated NULL-terminated environment variables. ("NAME1=VALUE1", "NAME2=VALUE2", ..., NULL) It should be freed by g_strfreev() when no longer needed.

Since 1.0.6


gcut_egg_hatch ()

gboolean            gcut_egg_hatch                      (GCutEgg *egg,
                                                         GError **error);

Hatches a new external process.

egg :

a GCutEgg

error :

return location for an error, or NULL

Returns :

TRUE on success, otherwise FALSE

Since 1.0.6


gcut_egg_close ()

void                gcut_egg_close                      (GCutEgg *egg);

Closes a hatched external process. It is closed implicitly on destroy.

egg :

a GCutEgg

Since 1.0.6


gcut_egg_write ()

gboolean            gcut_egg_write                      (GCutEgg *egg,
                                                         const gchar *chunk,
                                                         gsize size,
                                                         GError **error);

Writes chunk to external process's standard input.

egg :

a GCutEgg

chunk :

the data to be wrote

size :

the size of chunk

error :

return location for an error, or NULL

Returns :

TRUE on success, otherwise FALSE

Since 1.0.6


gcut_egg_get_pid ()

GPid                gcut_egg_get_pid                    (GCutEgg *egg);

Gets the process ID of running external process. If external process isn't running, 0 is returned.

egg :

a GCutEgg

Returns :

the process ID of running external process if external process is running, otherwise 0.

Since 1.0.6


gcut_egg_wait ()

gint                gcut_egg_wait                       (GCutEgg *egg,
                                                         guint timeout,
                                                         GError **error);

Waits running external process is finished while timeout milliseconds. If external process isn't finished while timeout milliseconds, GCUT_EGG_ERROR_TIMEOUT error is set and -1 is returned. If external process isn't running, GCUT_EGG_ERROR_NOT_RUNNING error is set and -1 is returned.

egg :

a GCutEgg

timeout :

the timeout period in milliseconds

error :

return location for an error, or NULL

Returns :

an exit status of external process on success, otherwise -1.

Since 1.0.6


gcut_egg_kill ()

void                gcut_egg_kill                       (GCutEgg *egg,
                                                         gint signal_number);

Sends signal_number signal to external process.

egg :

a GCutEgg

signal_number :

the signal number to be sent to external process

Since 1.0.6


gcut_egg_get_input ()

GIOChannel *        gcut_egg_get_input                  (GCutEgg *egg);

Gets a GIOChannel connected with standard input of external process.

egg :

a GCutEgg

Returns :

a GIOChannel if external process is running, otherwise NULL.

Since 1.0.6


gcut_egg_get_output ()

GIOChannel *        gcut_egg_get_output                 (GCutEgg *egg);

Gets a GIOChannel connected with standard output of external process.

egg :

a GCutEgg

Returns :

a GIOChannel if external process is running, otherwise NULL.

Since 1.0.6


gcut_egg_get_error ()

GIOChannel *        gcut_egg_get_error                  (GCutEgg *egg);

Gets a GIOChannel connected with standard error output of external process.

egg :

a GCutEgg

Returns :

a GIOChannel if external process is running, otherwise NULL.

Since 1.0.6


gcut_egg_get_forced_termination_wait_time ()

guint               gcut_egg_get_forced_termination_wait_time
                                                        (GCutEgg *egg);

Gets a wait time in milliseconds for forced termination on dispose.

egg :

a GCutEgg

Returns :

a timeout value for waiting forced terminated external command on dispose.

Since 1.0.6


gcut_egg_set_forced_termination_wait_time ()

void                gcut_egg_set_forced_termination_wait_time
                                                        (GCutEgg *egg,
                                                         guint timeout);

Sets a wait time in milliseconds for forced termination on dispose. If timeout is 0, it doesn't wait termination of external process. The default value is 10.

egg :

a GCutEgg

timeout :

the timeout value in milliseconds

Since 1.0.6

Property Details

The "command" property

  "command"                  gpointer              : Read / Write

The command to be ran by the egg.

Signal Details

The "error" signal

void                user_function                      (GCutEgg *egg,
                                                        gpointer error,
                                                        gpointer user_data)      : Run Last

It is emitted each time an external process causes an error. (e.g. IO error)

egg :

the object which received the signal.

error :

the error of an external process. (GError)

user_data :

user data set when the signal handler was connected.

Since 1.0.6


The "error-received" signal

void                user_function                      (GCutEgg *egg,
                                                        gchar   *chunk,
                                                        guint64  size,
                                                        gpointer user_data)      : Run Last

It is emitted each time an external process outputs something to its standard error output and it is read.

Note that you need to run GLib's main loop by g_main_loop_run(), g_main_context_iteration() and so on for detecting an external process's output is readable.

egg :

the object which received the signal.

chunk :

the chunk read from an external process's standard error output.

size :

the size of chunk. (gsize)

user_data :

user data set when the signal handler was connected.

Since 1.0.6


The "output-received" signal

void                user_function                      (GCutEgg *egg,
                                                        gchar   *chunk,
                                                        guint64  size,
                                                        gpointer user_data)      : Run Last

It is emitted each time an external process outputs something to its standard output and it is read.

Note that you need to run GLib's main loop by g_main_loop_run(), g_main_context_iteration() and so on for detecting an external process's output is readable.

egg :

the object which received the signal.

chunk :

the chunk read from an external process's standard output.

size :

the size of chunk. (gsize)

user_data :

user data set when the signal handler was connected.

Since 1.0.6


The "reaped" signal

void                user_function                      (GCutEgg *egg,
                                                        gint     status,
                                                        gpointer user_data)      : Run Last

It is emitted when an external process is exited.

Note that you need to run GLib's main loop by g_main_loop_run(), g_main_context_iteration() and so on for detecting an external process is exited.

egg :

the object which received the signal.

status :

the exit status of an external process.

user_data :

user data set when the signal handler was connected.

Since 1.0.6