| Top |
| void | error | Run Last |
| void | error-received | Run Last |
| void | output-received | Run Last |
| void | 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.:
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);
}
GCutProcess * gcut_process_new (const gchar *command,...);
Creates a new GCutProcess object that runs command
.
Since 1.1.5
GCutProcess *
gcut_process_new_command_line (const gchar *command_line);
Creates a new GCutProcess object that runs command_line
.
Since 1.1.5
GCutProcess * gcut_process_new_va_list (const gchar *command,va_list args);
Creates a new GCutProcess object that runs command
.
Since 1.1.5
GCutProcess * gcut_process_new_argv (gint argc,gchar **argv);
Creates a new GCutProcess object that runs command
.
argc |
the number of elements of |
|
argv |
the external command name to be ran and arguments of it. |
Since 1.1.5
GCutProcess *
gcut_process_new_strings (const gchar **command);
Creates a new GCutProcess object that runs command
.
Since 1.1.5
GCutProcess *
gcut_process_new_array (GArray *command);
Creates a new GCutProcess object that runs command
.
command |
the external command name to be ran and arguments of it. The GArray should be zero-terminated. |
Since 1.1.5
void gcut_process_set_flags (GCutProcess *process,GSpawnFlags flags);
Sets flags
for spawning.
Since 1.1.5
GSpawnFlags
gcut_process_get_flags (GCutProcess *process);
Gets flags
for spawning.
Since 1.1.5
void gcut_process_set_env (GCutProcess *process,const gchar *name,...);
Sets environment variable for external command.
process |
||
name |
the first environment name. |
|
... |
the value of |
Since 1.1.5
gchar **
gcut_process_get_env (GCutProcess *process);
Gets environment variable for external command.
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.
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.
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.
process |
||
timeout |
the timeout period in milliseconds |
|
error |
return location for an error, or |
Since 1.1.5
gboolean gcut_process_kill (GCutProcess *process,gint signal_number,GError **error);
Sends signal_number
signal to external process.
process |
||
signal_number |
the signal number to be sent to external process |
|
error |
return location for an error, or |
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.
process |
||
chunk |
the data to be wrote |
|
size |
the size of |
|
error |
return location for an error, or |
Since 1.1.5
GIOStatus gcut_process_flush (GCutProcess *process,GError **error);
Flush buffered external process's standard input.
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);
Since 1.1.5
GString *
gcut_process_get_error_string (GCutProcess *process);
Since 1.1.5
GIOChannel *
gcut_process_get_input_channel (GCutProcess *process);
Gets a GIOChannel connected with standard input of external process.
Since 1.1.5
GIOChannel *
gcut_process_get_output_channel (GCutProcess *process);
Gets a GIOChannel connected with standard output of external process.
Since 1.1.5
GIOChannel *
gcut_process_get_error_channel (GCutProcess *process);
Gets a GIOChannel connected with standard error output of external process.
Since 1.1.5
GInputStream *
gcut_process_get_output_stream (GCutProcess *process);
Gets a GInputStream connected with standard output of external process.
Since 1.1.5
GInputStream *
gcut_process_get_error_stream (GCutProcess *process);
Gets a GInputStream connected with standard error output of external process.
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.
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.
Since 1.1.5
GCutEventLoop *
gcut_process_get_event_loop (GCutProcess *process);
Gets a event loop using by the process
.
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.
Since 1.1.6
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
“error” signalvoid user_function (GCutProcess *process, gpointer error, gpointer user_data)
Flags: Run Last
Since 1.1.5
“error-received” signalvoid user_function (GCutProcess *process, gchar *chunk, guint64 size, gpointer user_data)
Flags: Run Last
Since 1.1.5
“output-received” signalvoid user_function (GCutProcess *process, gchar *chunk, guint64 size, gpointer user_data)
Flags: Run Last
Since 1.1.5
“reaped” signalvoid user_function (GCutProcess *process, gint status, gpointer user_data)
Flags: Run Last
Since 1.1.5