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

External command

External command — Convenience API for using external command.

Properties

gpointer command Read / Write

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)

Flags: Run Last

Since: 1.1.5


The “error-received” signal

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

Flags: Run Last

Since: 1.1.5


The “output-received” signal

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

Flags: Run Last

Since: 1.1.5


The “reaped” signal

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

Flags: Run Last

Since: 1.1.5