External command (deprecated)

## External command (deprecated) External command (deprecated) — Convenience API for using external command. (deprecated) |

## Synopsis

    #define             GCUT_EGG_ERROR
                        GCutEgg;
                        GCutEggClass;
    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
    42
    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())

### Warning

`GCUT_EGG_ERROR` is deprecated and should not be used in newly-written code.

### GCutEgg

    typedef struct _GCutEgg GCutEgg;

### Warning

`GCutEgg` is deprecated and should not be used in newly-written code.

### GCutEggClass

    typedef struct {
        GObjectClass parent_class;

        void (*output_received) (GCutEgg     *egg,
                                 const gchar *chunk,
                                 gsize        size);
        void (*error_received)  (GCutEgg     *egg,
                                 const gchar *chunk,
                                 gsize        size);
        void (*reaped)          (GCutEgg     *egg,
                                 gint         status);
        void (*error)           (GCutEgg     *egg,
                                 GError      *error);
    } GCutEggClass;

### Warning

`GCutEggClass` is deprecated and should not be used in newly-written code.

### 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;

### Warning

`GCutEggError` has been deprecated since version 1.1.5 and should not be used in newly-written code. Use GCutProcessError instead.

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);

### Warning

`gcut_egg_error_quark` is deprecated and should not be used in newly-written code.

Returns : |

### gcut_egg_new ()

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

### Warning

`gcut_egg_new` has been deprecated since version 1.1.5 and should not be used in newly-written code. Use `gcut_process_new()` instead.

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);

### Warning

`gcut_egg_new_va_list` has been deprecated since version 1.1.5 and should not be used in newly-written code. Use `gcut_process_new_va_list()` instead.

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);

### Warning

`gcut_egg_new_argv` has been deprecated since version 1.1.5 and should not be used in newly-written code. Use `gcut_process_new_argv()` instead.

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);

### Warning

`gcut_egg_new_strings` has been deprecated since version 1.1.5 and should not be used in newly-written code. Use `gcut_process_new_strings()` instead.

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);

### Warning

`gcut_egg_new_array` has been deprecated since version 1.1.5 and should not be used in newly-written code. Use `gcut_process_new_array()` instead.

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);

### Warning

`gcut_egg_set_flags` has been deprecated since version 1.1.5 and should not be used in newly-written code. Use `gcut_process_set_flags()` instead.

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);

### Warning

`gcut_egg_get_flags` has been deprecated since version 1.1.5 and should not be used in newly-written code. Use `gcut_process_get_flags()` instead.

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,
                                                             ...);

### Warning

`gcut_egg_set_env` has been deprecated since version 1.1.5 and should not be used in newly-written code. Use `gcut_process_set_env()` instead.

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);

### Warning

`gcut_egg_get_env` has been deprecated since version 1.1.5 and should not be used in newly-written code. Use `gcut_process_get_env()` instead.

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);

### Warning

`gcut_egg_hatch` has been deprecated since version 1.1.5 and should not be used in newly-written code. Use `gcut_process_run()` instead.

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);

### Warning

`gcut_egg_close` has been deprecated since version 1.1.5 and should not be used in newly-written code. no need to close explicitly on GCutProcess.

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);

### Warning

`gcut_egg_write` has been deprecated since version 1.1.5 and should not be used in newly-written code. Use `gcut_process_write()` instead.

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);

### Warning

`gcut_egg_get_pid` has been deprecated since version 1.1.5 and should not be used in newly-written code. Use `gcut_process_get_pid()` instead.

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);

### Warning

`gcut_egg_wait` has been deprecated since version 1.1.5 and should not be used in newly-written code. Use `gcut_process_wait()` instead.

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);

### Warning

`gcut_egg_kill` has been deprecated since version 1.1.5 and should not be used in newly-written code. Use `gcut_process_kill()` instead.

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);

### Warning

`gcut_egg_get_input` has been deprecated since version 1.1.5 and should not be used in newly-written code. Use `gcut_process_get_input_channel()` instead.

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);

### Warning

`gcut_egg_get_output` has been deprecated since version 1.1.5 and should not be used in newly-written code. Use `gcut_process_get_output_channel()` instead.

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);

### Warning

`gcut_egg_get_error` has been deprecated since version 1.1.5 and should not be used in newly-written code. Use `gcut_process_get_error_channel()` instead.

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);

### Warning

`gcut_egg_get_forced_termination_wait_time` has been deprecated since version 1.1.5 and should not be used in newly-written code. Use `gcut_process_get_forced_termination_wait_time()` instead.

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);

### Warning

`gcut_egg_set_forced_termination_wait_time` has been deprecated since version 1.1.5 and should not be used in newly-written code. Use `gcut_process_set_forced_termination_wait_time()` instead.

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