a Unit Testing Framework for C and C++ - Cutter

External command

External command — Convenience API for using external command.

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

Object Hierarchy

    GObject
    ╰── GCutProcess

Description

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);
}

Functions

gcut_process_error_quark ()

GQuark
gcut_process_error_quark (void);

gcut_process_new ()

GCutProcess *
gcut_process_new (const gchar *command,
                  ...);

Creates a new GCutProcess object that runs command .

Parameters

command

the external command name to be ran

 

...

the arguments for command

 

Returns

a new GCutProcess.

Since: 1.1.5


gcut_process_new_command_line ()

GCutProcess *
gcut_process_new_command_line (const gchar *command_line);

Creates a new GCutProcess object that runs command_line .

Parameters

command_line

a command line

 

Returns

a new GCutProcess.

Since: 1.1.5


gcut_process_new_va_list ()

GCutProcess *
gcut_process_new_va_list (const gchar *command,
                          va_list args);

Creates a new GCutProcess object that runs command .

Parameters

command

the external command name to be ran

 

args

arguments for command

 

Returns

a new GCutProcess.

Since: 1.1.5


gcut_process_new_argv ()

GCutProcess *
gcut_process_new_argv (gint argc,
                       gchar **argv);

Creates a new GCutProcess 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 GCutProcess.

Since: 1.1.5


gcut_process_new_strings ()

GCutProcess *
gcut_process_new_strings (const gchar **command);

Creates a new GCutProcess object that runs command .

Parameters

command

the external command name to be ran and arguments of it. NULL-terminated.

 

Returns

a new GCutProcess.

Since: 1.1.5


gcut_process_new_array ()

GCutProcess *
gcut_process_new_array (GArray *command);

Creates a new GCutProcess 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 GCutProcess.

Since: 1.1.5


gcut_process_set_flags ()

void
gcut_process_set_flags (GCutProcess *process,
                        GSpawnFlags flags);

Sets flags for spawning.

Parameters

process

a GCutProcess

 

flags

the flags to be passed to g_spawn_async_with_pipes().

 

Since: 1.1.5


gcut_process_get_flags ()

GSpawnFlags
gcut_process_get_flags (GCutProcess *process);

Gets flags for spawning.

Parameters

process

a GCutProcess

 

Returns

the flags for spawning.

Since: 1.1.5


gcut_process_set_env ()

void
gcut_process_set_env (GCutProcess *process,
                      const gchar *name,
                      ...);

Sets environment variable for external command.

Parameters

process

a GCutProcess

 

name

the first environment name.

 

...

the value of name , followed by name and value pairs. NULL-terminated.

 

Since: 1.1.5


gcut_process_get_env ()

gchar **
gcut_process_get_env (GCutProcess *process);

Gets environment variable for external command.

Parameters

process

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


gcut_process_run ()

gboolean
gcut_process_run (GCutProcess *process,
                  GError **error);

Runs a new external process.

Parameters

process

a GCutProcess

 

error

return location for an error, or NULL

 

Returns

TRUE on success, otherwise FALSE

Since: 1.1.5


gcut_process_get_pid ()

GPid
gcut_process_get_pid (GCutProcess *process);

Gets the process ID of running external process. If external process isn't running, 0 is returned.

Parameters

process

a GCutProcess

 

Returns

the process ID of running external process if external process is running, otherwise 0.

Since: 1.1.5


gcut_process_wait ()

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.

Parameters

process

a GCutProcess

 

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.1.5


gcut_process_kill ()

gboolean
gcut_process_kill (GCutProcess *process,
                   gint signal_number,
                   GError **error);

Sends signal_number signal to external process.

Parameters

process

a GCutProcess

 

signal_number

the signal number to be sent to external process

 

error

return location for an error, or NULL

 

Returns

TRUE on success, otherwise FALSE

Since: 1.1.5


gcut_process_write ()

gboolean
gcut_process_write (GCutProcess *process,
                    const gchar *chunk,
                    gsize size,
                    GError **error);

Writes chunk to external process's standard input.

Parameters

process

a GCutProcess

 

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.1.5


gcut_process_flush ()

GIOStatus
gcut_process_flush (GCutProcess *process,
                    GError **error);

Flush buffered external process's standard input.

Parameters

process

a GCutProcess

 

error

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


gcut_process_get_output_string ()

GString *
gcut_process_get_output_string (GCutProcess *process);

Parameters

process

a GCutProcess

 

Returns

a GString that has all result of standard output of external process.

Since: 1.1.5


gcut_process_get_error_string ()

GString *
gcut_process_get_error_string (GCutProcess *process);

Parameters

process

a GCutProcess

 

Returns

a GString that has all result of standard error of external process.

Since: 1.1.5


gcut_process_get_input_channel ()

GIOChannel *
gcut_process_get_input_channel (GCutProcess *process);

Gets a GIOChannel connected with standard input of external process.

Parameters

process

a GCutProcess

 

Returns

a GIOChannel if external process is running, otherwise NULL.

Since: 1.1.5


gcut_process_get_output_channel ()

GIOChannel *
gcut_process_get_output_channel (GCutProcess *process);

Gets a GIOChannel connected with standard output of external process.

Parameters

process

a GCutProcess

 

Returns

a GIOChannel if external process is running, otherwise NULL.

Since: 1.1.5


gcut_process_get_error_channel ()

GIOChannel *
gcut_process_get_error_channel (GCutProcess *process);

Gets a GIOChannel connected with standard error output of external process.

Parameters

process

a GCutProcess

 

Returns

a GIOChannel if external process is running, otherwise NULL.

Since: 1.1.5


gcut_process_get_output_stream ()

GInputStream *
gcut_process_get_output_stream (GCutProcess *process);

Gets a GInputStream connected with standard output of external process.

Parameters

process

a GCutProcess

 

Returns

a GInputStream if external process is running, otherwise NULL.

Since: 1.1.5


gcut_process_get_error_stream ()

GInputStream *
gcut_process_get_error_stream (GCutProcess *process);

Gets a GInputStream connected with standard error output of external process.

Parameters

process

a GCutProcess

 

Returns

a GInputStream if external process is running, otherwise NULL.

Since: 1.1.5


gcut_process_get_forced_termination_wait_time ()

guint
gcut_process_get_forced_termination_wait_time
                               (GCutProcess *process);

Gets a wait time in milliseconds for forced termination on dispose.

Parameters

process

a GCutProcess

 

Returns

a timeout value for waiting forced terminated external command on dispose.

Since: 1.1.5


gcut_process_set_forced_termination_wait_time ()

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.

Parameters

process

a GCutProcess

 

timeout

the timeout value in milliseconds

 

Since: 1.1.5


gcut_process_get_event_loop ()

GCutEventLoop *
gcut_process_get_event_loop (GCutProcess *process);

Gets a event loop using by the process .

Parameters

process

a GCutProcess

 

Returns

a GCutEventLoop.

Since: 1.1.6


gcut_process_set_event_loop ()

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.

Parameters

process

a GCutProcess

 

loop

the event loop or NULL

 

Since: 1.1.6

Types and Values

GCUT_PROCESS_ERROR

#define GCUT_PROCESS_ERROR           (gcut_process_error_quark())

enum GCutProcessError

Error codes returned by GCutProcess related operations.

Members

GCUT_PROCESS_ERROR_COMMAND_LINE

Command line related error.

 

GCUT_PROCESS_ERROR_IO_ERROR

IO error.

 

GCUT_PROCESS_ERROR_ALREADY_RUNNING

External command is already running.

 

GCUT_PROCESS_ERROR_NOT_RUNNING

External command isn't running.

 

GCUT_PROCESS_ERROR_INVALID_OBJECT

Invalid GCutProcess object is passed.

 

GCUT_PROCESS_ERROR_INVALID_SIGNAL

Invalid signal is passed.

 

GCUT_PROCESS_ERROR_PERMISSION_DENIED

Permission denied.

 

GCUT_PROCESS_ERROR_TIMEOUT

Timeout.

 

Since: 1.1.5

Property Details

The “command” property

  “command”                  gpointer

The command to be ran by the process.

Flags: Read / Write

Signal Details

The “error” signal

void
user_function (GCutProcess *process,
               gpointer     error,
               gpointer     user_data)

It is emitted each time an external process causes an error. (e.g. IO error)

Parameters

process

the object which received the signal.

 

error

the error of an external process. (GError)

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 1.1.5


The “error-received” signal

void
user_function (GCutProcess *process,
               gchar       *chunk,
               guint64      size,
               gpointer     user_data)

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 GCutEventLoop by gcut_event_loop_run() or gcut_event_loop_iterate() for detecting an external process's output is readable.

Parameters

process

the object which received the signal.

 

chunk

the chunk read from an external process's standard error output.

 

size

the size of chunk . (gsize)

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 1.1.5


The “output-received” signal

void
user_function (GCutProcess *process,
               gchar       *chunk,
               guint64      size,
               gpointer     user_data)

It is emitted each time an external process outputs something to its standard output and it is read.

Note that you need to run GCutEventLoop by gcut_event_loop_run() or gcut_event_loop_iterate() for detecting an external process's output is readable.

Parameters

process

the object which received the signal.

 

chunk

the chunk read from an external process's standard output.

 

size

the size of chunk . (gsize)

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 1.1.5


The “reaped” signal

void
user_function (GCutProcess *process,
               gint         status,
               gpointer     user_data)

It is emitted when an external process is exited.

Note that you need to run GCutEventLoop by gcut_event_loop_run() or gcut_event_loop_iterate() for detecting an external process is exited.

Parameters

process

the object which received the signal.

 

status

the exit status of an external process.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 1.1.5