外部コマンド

外部コマンド — 外部コマンドを使うための便利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()で指定された外部コマンドが実行されます。

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.

外部コマンドの終了を待つためには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

#define GCUT_PROCESS_ERROR           (gcut_process_error_quark())


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

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

 

...

commandの引数

 

Returns

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

コマンドライン

 

Returns

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

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

 

args

commandの引数

 

Returns

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

argvの要素数

 

argv

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

 

Returns

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

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

 

Returns

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

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

 

Returns

GCutProcessオブジェクト。

Since: 1.1.5


gcut_process_set_flags ()

void
gcut_process_set_flags (GCutProcess *process,
                        GSpawnFlags flags);

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

Parameters

process

GCutProcess

 

flags

g_spawn_async_with_pipes()に渡すフラグ。

 

Since: 1.1.5


gcut_process_get_flags ()

GSpawnFlags
gcut_process_get_flags (GCutProcess *process);

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

Parameters

process

GCutProcess

 

Returns

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

Since: 1.1.5


gcut_process_set_env ()

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

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

Parameters

process

GCutProcess

 

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

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

Parameters

process

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

process

GCutProcess

 

error

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

 

Returns

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

Since: 1.1.5


gcut_process_get_pid ()

GPid
gcut_process_get_pid (GCutProcess *process);

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

Parameters

process

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

process

GCutProcess

 

timeout

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

 

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

process

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

process

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

process

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

process

GCutProcess

 

Returns

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

Since: 1.1.5


gcut_process_get_error_string ()

GString *
gcut_process_get_error_string (GCutProcess *process);

Parameters

process

GCutProcess

 

Returns

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

Since: 1.1.5


gcut_process_get_input_channel ()

GIOChannel *
gcut_process_get_input_channel (GCutProcess *process);

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

Parameters

process

GCutProcess

 

Returns

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

Since: 1.1.5


gcut_process_get_output_channel ()

GIOChannel *
gcut_process_get_output_channel (GCutProcess *process);

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

Parameters

process

GCutProcess

 

Returns

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

Since: 1.1.5


gcut_process_get_error_channel ()

GIOChannel *
gcut_process_get_error_channel (GCutProcess *process);

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

Parameters

process

GCutProcess

 

Returns

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

Since: 1.1.5


gcut_process_get_output_stream ()

GInputStream *
gcut_process_get_output_stream (GCutProcess *process);

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

Parameters

process

GCutProcess

 

Returns

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

Since: 1.1.5


gcut_process_get_error_stream ()

GInputStream *
gcut_process_get_error_stream (GCutProcess *process);

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

Parameters

process

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

process

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

process

GCutProcess

 

timeout

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

 

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

GCutProcess

 

Returns

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

GCutProcess

 

loop

イベントループまたはNULL

 

Since: 1.1.6

Types and Values

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

プロパティ詳細

The “command” property

  “command”                  gpointer

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

Flags: Read / Write

シグナル詳細

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