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

## Functions

#define | GCUT_PROCESS_ERROR
GQuark | gcut_process_error_quark ()
GCutProcess * | gcut_process_new ()
GCutProcess * | gcut_process_new_command_line ()
GCutProcess * | gcut_process_new_va_list ()
GCutProcess * | gcut_process_new_argv ()
GCutProcess * | gcut_process_new_strings ()
GCutProcess * | gcut_process_new_array ()
void | gcut_process_set_flags ()
GSpawnFlags | gcut_process_get_flags ()
void | gcut_process_set_env ()
gchar ** | gcut_process_get_env ()
gboolean | gcut_process_run ()
GPid | gcut_process_get_pid ()
gint | gcut_process_wait ()
gboolean | gcut_process_kill ()
gboolean | gcut_process_write ()
GIOStatus | gcut_process_flush ()
GString * | gcut_process_get_output_string ()
GString * | gcut_process_get_error_string ()
GIOChannel * | gcut_process_get_input_channel ()
GIOChannel * | gcut_process_get_output_channel ()
GIOChannel * | gcut_process_get_error_channel ()
GInputStream * | gcut_process_get_output_stream ()
GInputStream * | gcut_process_get_error_stream ()
guint | gcut_process_get_forced_termination_wait_time ()
void | gcut_process_set_forced_termination_wait_time ()
GCutEventLoop * | gcut_process_get_event_loop ()
void | gcut_process_set_event_loop ()

## プロパティ

gpointer | command | Read / Write

## シグナル

void | error | Run Last
void | error-received | Run Last
void | output-received | Run Last
void | reaped | Run Last

## Types and Values

enum | GCutProcessError

## オブジェクト階層

        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