External command (deprecated): Cutter Reference Manual

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

## Functions

GQuark | gcut_egg_error_quark ()
GCutEgg * | gcut_egg_new ()
GCutEgg * | gcut_egg_new_va_list ()
GCutEgg * | gcut_egg_new_argv ()
GCutEgg * | gcut_egg_new_strings ()
GCutEgg * | gcut_egg_new_array ()
void | gcut_egg_set_flags ()
GSpawnFlags | gcut_egg_get_flags ()
void | gcut_egg_set_env ()
gchar ** | gcut_egg_get_env ()
gboolean | gcut_egg_hatch ()
void | gcut_egg_close ()
gboolean | gcut_egg_write ()
GPid | gcut_egg_get_pid ()
gint | gcut_egg_wait ()
void | gcut_egg_kill ()
GIOChannel * | gcut_egg_get_input ()
GIOChannel * | gcut_egg_get_output ()
GIOChannel * | gcut_egg_get_error ()
guint | gcut_egg_get_forced_termination_wait_time ()
void | gcut_egg_set_forced_termination_wait_time ()

## Properties

gpointer | command | Read / Write

## Signals

void | error | Run Last
void | error-received | Run Last
void | output-received | Run Last
void | reaped | Run Last

## Types and Values

#define | GCUT_EGG_ERROR
enum | GCutEggError

## Object Hierarchy

        GObject
        ╰── GCutEgg

## 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, "output-received",
                         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);
    }

## Functions

### gcut_egg_error_quark ()

    GQuark
    gcut_egg_error_quark (void);

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

### gcut_egg_new ()

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

`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` .

#### Parameters

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

`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` .

#### Parameters

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

`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` .

#### Parameters

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

`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` .

#### Parameters

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

`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` .

#### Parameters

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

`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.

#### Parameters

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

`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.

#### Parameters

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

`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.

#### Parameters

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

`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.

#### Parameters

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

`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.

#### Parameters

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

`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.

#### Parameters

egg | a GCutEgg |

Since: 1.0.6

### gcut_egg_write ()

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

`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.

#### Parameters

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

`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.

#### Parameters

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

`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.

#### Parameters

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

`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.

#### Parameters

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

`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.

#### Parameters

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

`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.

#### Parameters

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

`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.

#### Parameters

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

`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.

#### Parameters

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

`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.

#### Parameters

egg | a GCutEgg |
timeout | the timeout value in milliseconds |

Since: 1.0.6

## Types and Values

### GCUT_EGG_ERROR

    #define GCUT_EGG_ERROR           (gcut_egg_error_quark())

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

### enum GCutEggError

`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.

#### Members

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

## Property Details

### The `“command”` property

      “command”                  gpointer

The command to be ran by the egg.

Flags: Read / Write

## Signal Details

### The `“error”` signal

    void
    user_function (GCutEgg *egg,
                   gpointer error,
                   gpointer user_data)

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

#### Parameters

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. |

Flags: Run Last

Since: 1.0.6

### The `“error-received”` signal

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

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.

#### Parameters

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. |

Flags: Run Last

Since: 1.0.6

### The `“output-received”` signal

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

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.

#### Parameters

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. |

Flags: Run Last

Since: 1.0.6

### The `“reaped”` signal

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

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.

#### Parameters

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. |

Flags: Run Last

Since: 1.0.6