External command

External command — 外部コマンドを使うための便利API

Functions

プロパティ

gpointer command Read / Write

シグナル

Types and Values

オブジェクト階層

GObject
    ╰── GCutProcess

説明

GCutProcessは外部コマンドの実行・通信・終了をカプセル化します。GCutProcessはエラーをGErrorとして報告します。エラーはgcut_assert_error()を使うことにより簡単に検証できます。

外部コマンドはgcut_process_new()gcut_process_new_strings()などのようなコンストラクタで指定します。この時点では外部コマンドは実行されません。gcut_process_hatch()で指定された外部コマンドが実行されます。

外部コマンドの標準出力・エラー出力は"output-received"シグナル・"error-received"シグナル、あるいは、gcut_process_get_output()gcut_process_get_error()が返すGIOChannelで取得できます。gcut_process_write()は外部コマンドの標準入力にデータを書き込みます。

外部コマンドの終了を待つためにはgcut_process_wait()を使うことができます。無限待ちを避けるために、タイムアウトを指定することができます。

例:

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,
                  ...);

commandを実行する新しいGCutProcessオブジェクトを生成します。

Parameters

command

実行する外部コマンド名。

 

...

commandの引数

 

Returns

GCutProcessオブジェクト。

Since: 1.1.5


gcut_process_new_command_line ()

GCutProcess *
gcut_process_new_command_line (const gchar *command_line);

command_lineを実行する新しいGCutProcessオブジェクトを生成します。

Parameters

コマンドライン

コマンドライン

 

Returns

GCutProcessオブジェクト。

Since: 1.1.5


gcut_process_new_va_list ()

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

commandを実行する新しいGCutProcessオブジェクトを生成します。

Parameters

command

実行する外部コマンド名。

 

args

commandの引数

 

Returns

GCutProcessオブジェクト。

Since: 1.1.5


gcut_process_new_argv ()

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

commandを実行する新しいGCutProcessオブジェクトを生成します。

Parameters

argc

argvの要素数

 

argv

実行する外部コマンド名とコマンド引数。

 

Returns

GCutProcessオブジェクト。

Since: 1.1.5


gcut_process_new_strings ()

GCutProcess *
gcut_process_new_strings (const gchar **command);

commandを実行する新しいGCutProcessオブジェクトを生成します。

Parameters

command

実行する外部コマンド名とコマンド引数。NULL終端。

 

Returns

GCutProcessオブジェクト。

Since: 1.1.5


gcut_process_new_array ()

GCutProcess *
gcut_process_new_array (GArray *command);

commandを実行する新しいGCutProcessオブジェクトを生成します。

Parameters

command

実行する外部コマンド名とコマンド引数。GArrayは0終端にして下さい。

 

Returns

GCutProcessオブジェクト。

Since: 1.1.5


gcut_process_set_flags ()

void
gcut_process_set_flags (GCutProcess *process,
                        GSpawnFlags flags);

外部コマンドを実行するときのflagsを設定します。

Parameters

プロセスID。

GCutProcess

 

flags

g_spawn_async_with_pipes()に渡すフラグ。

 

Since: 1.1.5


gcut_process_get_flags ()

GSpawnFlags
gcut_process_get_flags (GCutProcess *process);

外部コマンドを実行する時のflagsを取得します。

Parameters

プロセスID。

GCutProcess

 

Returns

外部コマンドを実行するときのフラグ。

Since: 1.1.5


gcut_process_set_env ()

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

外部コマンドの環境変数を設定します。

Parameters

プロセスID。

GCutProcess

 

name

最初の環境変数名。

 

...

nameに対応する値。その後に、名前と値のペアを任意の数だけ指定します。最後の引数はNULLにしてください。

 

Since: 1.1.5


gcut_process_get_env ()

gchar **
gcut_process_get_env (GCutProcess *process);

外部コマンドの環境変数を取得します。

Parameters

プロセスID。

GCutProcess

 

Returns

新しく割り当てられたNULL終端の環境変数のリスト("名前1=値1", "名前2=値2", ..., NULL)を返します。必要がなくなったらg_strfreev()で開放してください。

Since: 1.1.5


gcut_process_run ()

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

新しい外部プロセスを実行します。

Parameters

プロセスID。

GCutProcess

 

error

エラーを返すアドレスまたはNULL

 

Returns

成功したときはTRUE、そうでない場合はFALSE

Since: 1.1.5


gcut_process_get_pid ()

詳細を示すguintGListです。

実行している外部プロセスのプロセスIDを取得します。外部コマンドが実行されていない場合は0が返ります。

Parameters

プロセスID。

GCutProcess

 

Returns

実行中の外部コマンドのプロセスID。実行していない場合は0。

Since: 1.1.5


gcut_process_wait ()

gint
gcut_process_wait (GCutProcess *process,
                   guint timeout,
                   GError **error);

実行中の外部プロセスが終了することをtimeoutミリ秒待ちます。外部コマンドがtimeoutミリ秒以内に終了しなかった場合は、GCUT_PROCESS_ERROR_TIMEOUTエラーが設定され、-1が返ります。外部プロセスが実行されていない場合は、GCUT_PROCESS_ERROR_NOT_RUNNINGエラーが設定され、-1が返ります。

Parameters

プロセスID。

GCutProcess

 

タイムアウト。

タイムアウト時間(ミリ秒)

 

error

エラーを返すアドレスまたはNULL

 

Returns

外部プロセスが終了した場合は終了ステータス。そうでない場合は-1。

Since: 1.1.5


gcut_process_kill ()

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

外部プロセスにsignal_numberシグナルを送ります。

Parameters

プロセスID。

GCutProcess

 

signal_number

外部プロセスに送るシグナル番号。

 

error

エラーを返すアドレスまたはNULL

 

Returns

成功したときはTRUE、そうでない場合はFALSE

Since: 1.1.5


gcut_process_write ()

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

外部プロセスの標準入力にchunkを書き込みます。

Parameters

プロセスID。

GCutProcess

 

chunk

書き込むデータ

 

size

chunkのサイズ

 

error

エラーを返すアドレスまたはNULL

 

Returns

成功したときはTRUE、そうでない場合はFALSE

Since: 1.1.5


gcut_process_flush ()

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

外部プロセスの標準出力から読み込んだデータ。

Parameters

プロセスID。

GCutProcess

 

error

エラーを返すアドレスまたは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

プロセスID。

GCutProcess

 

Returns

外部プロセスの標準出力の結果をすべて持ったGString

Since: 1.1.5


gcut_process_get_error_string ()

GString *
gcut_process_get_error_string (GCutProcess *process);

Parameters

プロセスID。

GCutProcess

 

Returns

外部プロセスの標準エラー出力の結果をすべて持ったGString

Since: 1.1.5


gcut_process_get_input_channel ()

GIOChannel *
gcut_process_get_input_channel (GCutProcess *process);

外部プロセスの標準入力と結びついたGIOChannelを取得します。

Parameters

プロセスID。

GCutProcess

 

Returns

外部プロセスが実行中の場合はGIOChannel。そうでない場合はNULL

Since: 1.1.5


gcut_process_get_output_channel ()

GIOChannel *
gcut_process_get_output_channel (GCutProcess *process);

外部プロセスの標準出力と結びついたGIOChannelを取得します。

Parameters

プロセスID。

GCutProcess

 

Returns

外部プロセスが実行中の場合はGIOChannel。そうでない場合はNULL

Since: 1.1.5


gcut_process_get_error_channel ()

GIOChannel *
gcut_process_get_error_channel (GCutProcess *process);

外部プロセスのエラー出力に結びついたGIOChannelを返します。

Parameters

プロセスID。

GCutProcess

 

Returns

外部プロセスが実行中の場合はGIOChannel。そうでない場合はNULL

Since: 1.1.5


gcut_process_get_output_stream ()

GInputStream *
gcut_process_get_output_stream (GCutProcess *process);

外部プロセスの標準出力と結びついたGInputStreamを取得します。

Parameters

プロセスID。

GCutProcess

 

Returns

外部プロセスが実行中の場合はGInputStream。そうでない場合はNULL

Since: 1.1.5


gcut_process_get_error_stream ()

GInputStream *
gcut_process_get_error_stream (GCutProcess *process);

外部プロセスの標準エラー出力に結びついたGInputStreamを返します。

Parameters

プロセスID。

GCutProcess

 

Returns

外部プロセスが実行中の場合はGInputStream。そうでない場合はNULL

Since: 1.1.5


gcut_process_get_forced_termination_wait_time ()

guint
gcut_process_get_forced_termination_wait_time
                               (GCutProcess *process);

オブジェクトが破棄されるときに行われる外部コマンド強制終了後に待つ時間(ミリ秒)を取得します。

Parameters

プロセスID。

GCutProcess

 

Returns

破棄時の強制終了待ちの時間。

Since: 1.1.5


gcut_process_set_forced_termination_wait_time ()

void
gcut_process_set_forced_termination_wait_time
                               (GCutProcess *process,
                                guint timeout);

オブジェクトが破棄されるときに行われる外部コマンド強制終了時に待つ時間(ミリ秒)を設定します。timeoutが0なら外部コマンドの終了を待ちません。デフォルト値は10です。

Parameters

プロセスID。

GCutProcess

 

タイムアウト。

タイムアウト時間(ミリ秒)

 

Since: 1.1.5


gcut_process_get_event_loop ()

GCutEventLoop *
gcut_process_get_event_loop (GCutProcess *process);

processが使っているイベントループを取得します。

Parameters

プロセスID。

GCutProcess

 

Returns

GCutEventLoop

Since: 1.1.6


gcut_process_set_event_loop ()

void
gcut_process_set_event_loop (GCutProcess *process,
                             GCutEventLoop *loop);

processのイベントループを設定します。loopNULLなら、デフォルトのGLibイベントループが使われます。

Parameters

プロセスID。

GCutProcess

 

loop

イベントループまたはNULL

 

Since: 1.1.6

Types and Values

GCUT_PROCESS_ERROR

#define GCUT_PROCESS_ERROR           (gcut_process_error_quark())

enum GCutProcessError

GCutProcess関連の操作で返されるエラーコード。

Members

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

不正なGCutProcessオブジェクトが渡されました。

 

GCUT_PROCESS_ERROR_INVALID_SIGNAL

不正なシグナルが渡されました。

 

GCUT_PROCESS_ERROR_PERMISSION_DENIED

許可がありません。

 

GCUT_PROCESS_ERROR_TIMEOUT

タイムアウト。

 

Since: 1.1.5

プロパティ詳細

"command"プロパティ

“command”                  gpointer

このプロセスが実行する外部コマンド。

Owner: GCutProcess

Flags: Read / Write

シグナル詳細

"error"シグナル

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

プロセスID。

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


"error-received"シグナル

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

プロセスID。

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


"output-received"シグナル

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

プロセスID。

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


"reaped"シグナル

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

プロセスID。

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