![]() |
![]() |
![]() |
Cutter Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Signals |
External command (deprecated)External command (deprecated) — Convenience API for using external command. (deprecated) |
#define GCUT_EGG_ERROR struct GCutEgg; struct GCutEggClass; enum GCutEggError; void gcut_egg_close (GCutEgg *egg
); GQuark gcut_egg_error_quark (void
); gchar ** gcut_egg_get_env (GCutEgg *egg
); GIOChannel * gcut_egg_get_error (GCutEgg *egg
); GSpawnFlags gcut_egg_get_flags (GCutEgg *egg
); guint gcut_egg_get_forced_termination_wait_time (GCutEgg *egg
); GIOChannel * gcut_egg_get_input (GCutEgg *egg
); GIOChannel * gcut_egg_get_output (GCutEgg *egg
); GPid gcut_egg_get_pid (GCutEgg *egg
); gboolean gcut_egg_hatch (GCutEgg *egg
,GError **error
); void gcut_egg_kill (GCutEgg *egg
,gint signal_number
); GCutEgg * gcut_egg_new (const gchar *command
,...
); GCutEgg * gcut_egg_new_argv (gint argc
,gchar **argv
); GCutEgg * gcut_egg_new_array (GArray *command
); GCutEgg * gcut_egg_new_strings (const gchar **command
); GCutEgg * gcut_egg_new_va_list (const gchar *command
,va_list args
); void gcut_egg_set_env (GCutEgg *egg
,const gchar *name
,...
); void gcut_egg_set_flags (GCutEgg *egg
,GSpawnFlags flags
); void gcut_egg_set_forced_termination_wait_time (GCutEgg *egg
,guint timeout
); gint gcut_egg_wait (GCutEgg *egg
,guint timeout
,GError **error
); gboolean gcut_egg_write (GCutEgg *egg
,const gchar *chunk
,gsize size
,GError **error
);
"error" :Run Last
"error-received" :Run Last
"output-received" :Run Last
"reaped" :Run Last
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, "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); }
#define GCUT_EGG_ERROR (gcut_egg_error_quark())
GCUT_EGG_ERROR
is deprecated and should not be used in newly-written code.
struct GCutEgg;
GCutEgg
is deprecated and should not be used in newly-written code.
struct GCutEggClass { 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
is deprecated and should not be used in newly-written code.
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;
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.
Command line related error. | |
IO error. | |
External command is already running. | |
External command isn't running. | |
Invalid GCutEgg object is passed. | |
Timeout. |
Since 1.0.6
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.
|
a GCutEgg |
Since 1.0.6
GQuark gcut_egg_error_quark (void
);
gcut_egg_error_quark
is deprecated and should not be used in newly-written code.
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.
|
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
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.
|
a GCutEgg |
Returns : |
a GIOChannel if external process is running,
otherwise NULL . |
Since 1.0.6
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.
|
a GCutEgg |
Returns : |
the flags for spawning. |
Since 1.0.6
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.
|
a GCutEgg |
Returns : |
a timeout value for waiting forced terminated external command on dispose. |
Since 1.0.6
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.
|
a GCutEgg |
Returns : |
a GIOChannel if external process is running,
otherwise NULL . |
Since 1.0.6
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.
|
a GCutEgg |
Returns : |
a GIOChannel if external process is running,
otherwise NULL . |
Since 1.0.6
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.
|
a GCutEgg |
Returns : |
the process ID of running external process if external process is running, otherwise 0. |
Since 1.0.6
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.
|
a GCutEgg |
|
return location for an error, or NULL
|
Returns : |
TRUE on success, otherwise FALSE
|
Since 1.0.6
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.
|
a GCutEgg |
|
the signal number to be sent to external process |
Since 1.0.6
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
.
|
the external command name to be ran |
|
the arguments for command
|
Returns : |
a new GCutEgg. |
Since 1.0.6
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
.
|
the number of elements of argv
|
|
the external command name to be ran and arguments of it. |
Returns : |
a new GCutEgg. |
Since 1.0.6
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
.
|
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
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
.
|
the external command name to be ran and
arguments of it. NULL -terminated. |
Returns : |
a new GCutEgg. |
Since 1.0.6
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
.
|
the external command name to be ran |
|
arguments for command
|
Returns : |
a new GCutEgg. |
Since 1.0.6
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.
|
a GCutEgg |
|
the first environment name. |
|
the value of name , followed by name and value
pairs. NULL -terminated. |
Since 1.0.6
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.
|
a GCutEgg |
|
the flags to be passed to g_spawn_async_with_pipes() . |
Since 1.0.6
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.
|
a GCutEgg |
|
the timeout value in milliseconds |
Since 1.0.6
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.
|
a GCutEgg |
|
the timeout period in milliseconds |
|
return location for an error, or NULL
|
Returns : |
an exit status of external process on success, otherwise -1. |
Since 1.0.6
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.
|
a GCutEgg |
|
the data to be wrote |
|
the size of chunk
|
|
return location for an error, or NULL
|
Returns : |
TRUE on success, otherwise FALSE
|
Since 1.0.6
"error"
signalvoid 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)
|
the object which received the signal. |
|
the error of an external process. (GError ) |
|
user data set when the signal handler was connected. |
Since 1.0.6
"error-received"
signalvoid 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.
|
the object which received the signal. |
|
the chunk read from an external process's standard error output. |
|
the size of chunk . (gsize ) |
|
user data set when the signal handler was connected. |
Since 1.0.6
"output-received"
signalvoid 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.
|
the object which received the signal. |
|
the chunk read from an external process's standard output. |
|
the size of chunk . (gsize ) |
|
user data set when the signal handler was connected. |
Since 1.0.6
"reaped"
signalvoid 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.
|
the object which received the signal. |
|
the exit status of an external process. |
|
user data set when the signal handler was connected. |
Since 1.0.6