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

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