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.

Returns

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

Generated by GTK-Doc V1.20