External command (deprecated): Cutter Reference Manual

External command (deprecated)

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

Functions

#define	GCUT_EGG_ERROR
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

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

#define GCUT_EGG_ERROR           (gcut_egg_error_quark())

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

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

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)

Flags: Run Last

Since: 1.0.6

The `“error-received”` signal

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

Flags: Run Last

Since: 1.0.6

The `“output-received”` signal

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

Flags: Run Last

Since: 1.0.6

The `“reaped”` signal

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

Flags: Run Last

Since: 1.0.6