![]() |
![]() |
![]() |
Cutter Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Signals |
#define GCUT_PROCESS_ERROR GCutProcess; GCutProcessClass; enum GCutProcessError; GQuark gcut_process_error_quark (void
); GCutProcess * gcut_process_new (const gchar *command
,...
); GCutProcess * gcut_process_new_command_line (const gchar *command_line
); GCutProcess * gcut_process_new_va_list (const gchar *command
,va_list args
); GCutProcess * gcut_process_new_argv (gint argc
,gchar **argv
); GCutProcess * gcut_process_new_strings (const gchar **command
); GCutProcess * gcut_process_new_array (GArray *command
); void gcut_process_set_flags (GCutProcess *process
,GSpawnFlags flags
); GSpawnFlags gcut_process_get_flags (GCutProcess *process
); void gcut_process_set_env (GCutProcess *process
,const gchar *name
,...
); gchar ** gcut_process_get_env (GCutProcess *process
); gboolean gcut_process_run (GCutProcess *process
,GError **error
); GPid gcut_process_get_pid (GCutProcess *process
); gint gcut_process_wait (GCutProcess *process
,guint timeout
,GError **error
); gboolean gcut_process_kill (GCutProcess *process
,gint signal_number
,GError **error
); gboolean gcut_process_write (GCutProcess *process
,const gchar *chunk
,gsize size
,GError **error
); GIOStatus gcut_process_flush (GCutProcess *process
,GError **error
); GString * gcut_process_get_output_string (GCutProcess *process
); GString * gcut_process_get_error_string (GCutProcess *process
); GIOChannel * gcut_process_get_input_channel (GCutProcess *process
); GIOChannel * gcut_process_get_output_channel (GCutProcess *process
); GIOChannel * gcut_process_get_error_channel (GCutProcess *process
); GInputStream * gcut_process_get_output_stream (GCutProcess *process
); GInputStream * gcut_process_get_error_stream (GCutProcess *process
); guint gcut_process_get_forced_termination_wait_time (GCutProcess *process
); void gcut_process_set_forced_termination_wait_time (GCutProcess *process
,guint timeout
); GCutEventLoop * gcut_process_get_event_loop (GCutProcess *process
); void gcut_process_set_event_loop (GCutProcess *process
,GCutEventLoop *loop
);
"error" : Run Last "error-received" : Run Last "output-received" : Run Last "reaped" : Run Last
GCutProcess encapsulates external command execution,
communication and termination. GCutProcess reports an error
as GError. It can be asserted easily by
gcut_assert_error()
.
External command is specified to constructor like
gcut_process_new()
, gcut_process_new_strings()
and so
on. External command isn't run at the
time. gcut_process_run()
runs specified external command.
Standard/Error outputs of external command are passed by
"output-received"/"error-received" signals
or GIOChannel returned by
gcut_process_get_output()
/gcut_process_get_error()
.
gcut_process_write()
writes a chunk to standard input of
external command.
To wait external command finished, gcut_process_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 GCutProcess *process; void cut_setup (void) { output_string = g_string_new(NULL); process = NULL; } void cut_teardown (void) { if (output_string) g_string_free(output_string, TRUE); if (process) g_object_unref(process); } static void cb_output_received (GCutProcess *process, const gchar *chunk, gsize size, gpointer user_data) { g_string_append_len(output_string, chunk, size); } void test_echo (void) { GError *error = NULL; process = gcut_process_new("echo", "XXX", NULL); g_signal_connect(process, "receive-output", G_CALLBACK(cb_output_received), NULL); gcut_process_run(process, &error); gcut_assert_error(error); gcut_process_wait(process, 1000, &error); gcut_assert_error(error); cut_assert_equal_string("XXX\n", output_string->str); } |
typedef struct { GObjectClass parent_class; void (*output_received) (GCutProcess *process, const gchar *chunk, gsize size); void (*error_received) (GCutProcess *process, const gchar *chunk, gsize size); void (*reaped) (GCutProcess *process, gint status); void (*error) (GCutProcess *process, GError *error); } GCutProcessClass;
typedef enum { GCUT_PROCESS_ERROR_COMMAND_LINE, GCUT_PROCESS_ERROR_IO_ERROR, GCUT_PROCESS_ERROR_ALREADY_RUNNING, GCUT_PROCESS_ERROR_NOT_RUNNING, GCUT_PROCESS_ERROR_INVALID_OBJECT, GCUT_PROCESS_ERROR_INVALID_SIGNAL, GCUT_PROCESS_ERROR_PERMISSION_DENIED, GCUT_PROCESS_ERROR_TIMEOUT } GCutProcessError;
Error codes returned by GCutProcess related operations.
Command line related error. | |
IO error. | |
External command is already running. | |
External command isn't running. | |
Invalid GCutProcess object is passed. | |
Invalid signal is passed. | |
Permission denied. | |
Timeout. |
Since 1.1.5
GCutProcess * gcut_process_new (const gchar *command
,...
);
Creates a new GCutProcess object that runs command
.
|
the external command name to be ran |
|
the arguments for command
|
Returns : |
a new GCutProcess. |
Since 1.1.5
GCutProcess * gcut_process_new_command_line (const gchar *command_line
);
Creates a new GCutProcess object that runs command_line
.
|
a command line |
Returns : |
a new GCutProcess. |
Since 1.1.5
GCutProcess * gcut_process_new_va_list (const gchar *command
,va_list args
);
Creates a new GCutProcess object that runs command
.
|
the external command name to be ran |
|
arguments for command
|
Returns : |
a new GCutProcess. |
Since 1.1.5
GCutProcess * gcut_process_new_argv (gint argc
,gchar **argv
);
Creates a new GCutProcess object that runs command
.
|
the number of elements of argv
|
|
the external command name to be ran and arguments of it. |
Returns : |
a new GCutProcess. |
Since 1.1.5
GCutProcess * gcut_process_new_strings (const gchar **command
);
Creates a new GCutProcess object that runs command
.
|
the external command name to be ran and
arguments of it. NULL -terminated.
|
Returns : |
a new GCutProcess. |
Since 1.1.5
GCutProcess * gcut_process_new_array (GArray *command
);
Creates a new GCutProcess object that runs command
.
|
the external command name to be ran and arguments of it. The GArray should be zero-terminated. |
Returns : |
a new GCutProcess. |
Since 1.1.5
void gcut_process_set_flags (GCutProcess *process
,GSpawnFlags flags
);
Sets flags
for spawning.
|
a GCutProcess |
|
the flags to be passed to g_spawn_async_with_pipes() .
|
Since 1.1.5
GSpawnFlags gcut_process_get_flags (GCutProcess *process
);
Gets flags
for spawning.
|
a GCutProcess |
Returns : |
the flags for spawning. |
Since 1.1.5
void gcut_process_set_env (GCutProcess *process
,const gchar *name
,...
);
Sets environment variable for external command.
|
a GCutProcess |
|
the first environment name. |
|
the value of name , followed by name and value
pairs. NULL -terminated.
|
Since 1.1.5
gchar ** gcut_process_get_env (GCutProcess *process
);
Gets environment variable for external command.
|
a GCutProcess |
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.1.5
gboolean gcut_process_run (GCutProcess *process
,GError **error
);
Runs a new external process.
|
a GCutProcess |
|
return location for an error, or NULL
|
Returns : |
TRUE on success, otherwise FALSE
|
Since 1.1.5
GPid gcut_process_get_pid (GCutProcess *process
);
Gets the process ID of running external process. If external process isn't running, 0 is returned.
|
a GCutProcess |
Returns : |
the process ID of running external process if external process is running, otherwise 0. |
Since 1.1.5
gint gcut_process_wait (GCutProcess *process
,guint timeout
,GError **error
);
Waits running external process is finished while timeout
milliseconds. If external process isn't finished while
timeout
milliseconds, GCUT_PROCESS_ERROR_TIMEOUT
error is
set and -1 is returned. If external process isn't
running, GCUT_PROCESS_ERROR_NOT_RUNNING
error is set and -1
is returned.
|
a GCutProcess |
|
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.1.5
gboolean gcut_process_kill (GCutProcess *process
,gint signal_number
,GError **error
);
Sends signal_number
signal to external process.
|
a GCutProcess |
|
the signal number to be sent to external process |
|
return location for an error, or NULL
|
Returns : |
TRUE on success, otherwise FALSE
|
Since 1.1.5
gboolean gcut_process_write (GCutProcess *process
,const gchar *chunk
,gsize size
,GError **error
);
Writes chunk
to external process's standard input.
|
a GCutProcess |
|
the data to be wrote |
|
the size of chunk
|
|
return location for an error, or NULL
|
Returns : |
TRUE on success, otherwise FALSE
|
Since 1.1.5
GIOStatus gcut_process_flush (GCutProcess *process
,GError **error
);
Flush buffered external process's standard input.
|
a GCutProcess |
|
return location for an error, or NULL
|
Returns : |
the status of the operation: One of
G_IO_STATUS_NORMAL , G_IO_STATUS_AGAIN , or
G_IO_STATUS_ERROR .
|
Since 1.1.5
GString * gcut_process_get_output_string (GCutProcess *process
);
|
a GCutProcess |
Returns : |
a GString that has all result of standard output of external process. |
Since 1.1.5
GString * gcut_process_get_error_string (GCutProcess *process
);
|
a GCutProcess |
Returns : |
a GString that has all result of standard error of external process. |
Since 1.1.5
GIOChannel * gcut_process_get_input_channel (GCutProcess *process
);
Gets a GIOChannel connected with standard input of external process.
|
a GCutProcess |
Returns : |
a GIOChannel if external process is running,
otherwise NULL .
|
Since 1.1.5
GIOChannel * gcut_process_get_output_channel (GCutProcess *process
);
Gets a GIOChannel connected with standard output of external process.
|
a GCutProcess |
Returns : |
a GIOChannel if external process is running,
otherwise NULL .
|
Since 1.1.5
GIOChannel * gcut_process_get_error_channel (GCutProcess *process
);
Gets a GIOChannel connected with standard error output of external process.
|
a GCutProcess |
Returns : |
a GIOChannel if external process is running,
otherwise NULL .
|
Since 1.1.5
GInputStream * gcut_process_get_output_stream (GCutProcess *process
);
Gets a GInputStream connected with standard output of external process.
|
a GCutProcess |
Returns : |
a GInputStream if external process is running,
otherwise NULL .
|
Since 1.1.5
GInputStream * gcut_process_get_error_stream (GCutProcess *process
);
Gets a GInputStream connected with standard error output of external process.
|
a GCutProcess |
Returns : |
a GInputStream if external process is running,
otherwise NULL .
|
Since 1.1.5
guint gcut_process_get_forced_termination_wait_time
(GCutProcess *process
);
Gets a wait time in milliseconds for forced termination on dispose.
|
a GCutProcess |
Returns : |
a timeout value for waiting forced terminated external command on dispose. |
Since 1.1.5
void gcut_process_set_forced_termination_wait_time (GCutProcess *process
,guint timeout
);
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 GCutProcess |
|
the timeout value in milliseconds |
Since 1.1.5
GCutEventLoop * gcut_process_get_event_loop (GCutProcess *process
);
Gets a event loop using by the process
.
|
a GCutProcess |
Returns : |
a GCutEventLoop. |
Since 1.1.6
void gcut_process_set_event_loop (GCutProcess *process
,GCutEventLoop *loop
);
Sets a event loop for the process
. If loop
is NULL
,
the default GLib event loop will be used.
|
a GCutProcess |
|
the event loop or NULL
|
Since 1.1.6
"error"
signalvoid user_function (GCutProcess *process, 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.1.5
"error-received"
signalvoid user_function (GCutProcess *process, 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.1.5
"output-received"
signalvoid user_function (GCutProcess *process, 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.1.5
"reaped"
signalvoid user_function (GCutProcess *process, 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.1.5