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

## 概要

    #define             GCUT_PROCESS_ERROR
                        GCutProcess;
                        GCutProcessClass;
    enum                GCutProcessError;
    GQuark              gcut_process_error_quark            (void);
    GCutProcess *       gcut_process_new                    (const gchar *command,
                                                             ...);
    GCutProcess *       gcut_process_new_command_line       (const gchar *command_line);
    GCutProcess *       gcut_process_new_va_list            (const gchar *command,
                                                             va_list args);
    GCutProcess *       gcut_process_new_argv               (gint argc,
                                                             gchar **argv);
    GCutProcess *       gcut_process_new_strings            (const gchar **command);
    GCutProcess *       gcut_process_new_array              (GArray *command);
    void                gcut_process_set_flags              (GCutProcess *process,
                                                             GSpawnFlags flags);
    GSpawnFlags         gcut_process_get_flags              (GCutProcess *process);
    void                gcut_process_set_env                (GCutProcess *process,
                                                             const gchar *name,
                                                             ...);
    gchar **            gcut_process_get_env                (GCutProcess *process);
    gboolean            gcut_process_run                    (GCutProcess *process,
                                                             GError **error);
    GPid                gcut_process_get_pid                (GCutProcess *process);
    gint                gcut_process_wait                   (GCutProcess *process,
                                                             guint timeout,
                                                             GError **error);
    gboolean            gcut_process_kill                   (GCutProcess *process,
                                                             gint signal_number,
                                                             GError **error);
    gboolean            gcut_process_write                  (GCutProcess *process,
                                                             const gchar *chunk,
                                                             gsize size,
                                                             GError **error);
    GIOStatus           gcut_process_flush                  (GCutProcess *process,
                                                             GError **error);
    GString *           gcut_process_get_output_string      (GCutProcess *process);
    GString *           gcut_process_get_error_string       (GCutProcess *process);
    GIOChannel *        gcut_process_get_input_channel      (GCutProcess *process);
    GIOChannel *        gcut_process_get_output_channel     (GCutProcess *process);
    GIOChannel *        gcut_process_get_error_channel      (GCutProcess *process);
    GInputStream *      gcut_process_get_output_stream      (GCutProcess *process);
    GInputStream *      gcut_process_get_error_stream       (GCutProcess *process);
    guint               gcut_process_get_forced_termination_wait_time
                                                            (GCutProcess *process);
    void                gcut_process_set_forced_termination_wait_time
                                                            (GCutProcess *process,
                                                             guint timeout);
    GCutEventLoop *     gcut_process_get_event_loop         (GCutProcess *process);
    void                gcut_process_set_event_loop         (GCutProcess *process,
                                                             GCutEventLoop *loop);

## オブジェクト階層

      GObject
       +----GCutProcess

## プロパティ

      "command"                  gpointer              : Read / Write

## シグナル

      "error"                                          : Run Last
      "error-received"                                 : Run Last
      "output-received"                                : Run Last
      "reaped"                                         : Run Last

## 説明

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

## 詳細

### GCUT_PROCESS_ERROR

    #define GCUT_PROCESS_ERROR           (gcut_process_error_quark())

### GCutProcess

    typedef struct _GCutProcess GCutProcess;

### GCutProcessClass

    typedef struct {
        GObjectClass parent_class;

        void (*output_received) (GCutProcess *process,
                                 const gchar *chunk,
                                 gsize        size);
        void (*error_received)  (GCutProcess *process,
                                 const gchar *chunk,
                                 gsize        size);
        void (*reaped)          (GCutProcess *process,
                                 gint         status);
        void (*error)           (GCutProcess *process,
                                 GError      *error);
    } GCutProcessClass;

### enum GCutProcessError

    typedef enum
    {
        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,
        GCUT_PROCESS_ERROR_INVALID_SIGNAL,
        GCUT_PROCESS_ERROR_PERMISSION_DENIED,
        GCUT_PROCESS_ERROR_TIMEOUT
    } GCutProcessError;

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

`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` | タイムアウト。

1.1.5から

### gcut_process_error_quark ()

    GQuark              gcut_process_error_quark            (void);

戻り値 : |

### gcut_process_new ()

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

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

`command` : | 実行する外部コマンド名。
`...` : | `command`の引数
戻り値 : | GCutProcessオブジェクト。

1.1.5から

### gcut_process_new_command_line ()

    GCutProcess *       gcut_process_new_command_line       (const gchar *command_line);

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

`command_line` : | コマンドライン
戻り値 : | GCutProcessオブジェクト。

1.1.5から

### gcut_process_new_va_list ()

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

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

`command` : | 実行する外部コマンド名。
`args` : | `command`の引数
戻り値 : | GCutProcessオブジェクト。

1.1.5から

### gcut_process_new_argv ()

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

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

`argc` : | `argv`の要素数
`argv` : | 実行する外部コマンド名とコマンド引数。
戻り値 : | GCutProcessオブジェクト。

1.1.5から

### gcut_process_new_strings ()

    GCutProcess *       gcut_process_new_strings            (const gchar **command);

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

`command` : | 実行する外部コマンド名とコマンド引数。`NULL`終端。
戻り値 : | GCutProcessオブジェクト。

1.1.5から

### gcut_process_new_array ()

    GCutProcess *       gcut_process_new_array              (GArray *command);

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

`command` : | 実行する外部コマンド名とコマンド引数。GArrayは0終端にして下さい。
戻り値 : | GCutProcessオブジェクト。

1.1.5から

### gcut_process_set_flags ()

    void                gcut_process_set_flags              (GCutProcess *process,
                                                             GSpawnFlags flags);

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

`process` : | GCutProcess
`flags` : | `g_spawn_async_with_pipes()`に渡すフラグ。

1.1.5から

### gcut_process_get_flags ()

    GSpawnFlags         gcut_process_get_flags              (GCutProcess *process);

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

`process` : | GCutProcess
戻り値 : | 外部コマンドを実行するときのフラグ。

1.1.5から

### gcut_process_set_env ()

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

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

`process` : | GCutProcess
`name` : | 最初の環境変数名。
`...` : | `name`に対応する値。その後に、名前と値のペアを任意の数だけ指定します。最後の引数は`NULL`にしてください。

1.1.5から

### gcut_process_get_env ()

    gchar **            gcut_process_get_env                (GCutProcess *process);

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

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

1.1.5から

### gcut_process_run ()

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

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

`process` : | GCutProcess
`error` : | エラーを返すアドレスまたは`NULL`。
戻り値 : | 成功したときは`TRUE`、そうでない場合は`FALSE`。

1.1.5から

### gcut_process_get_pid ()

    GPid                gcut_process_get_pid                (GCutProcess *process);

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

`process` : | GCutProcess
戻り値 : | 実行中の外部コマンドのプロセスID。実行していない場合は0。

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が返ります。

`process` : | GCutProcess
`timeout` : | タイムアウト時間（ミリ秒）
`error` : | エラーを返すアドレスまたは`NULL`。
戻り値 : | 外部プロセスが終了した場合は終了ステータス。そうでない場合は-1。

1.1.5から

### gcut_process_kill ()

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

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

`process` : | GCutProcess
`signal_number` : | 外部プロセスに送るシグナル番号。
`error` : | エラーを返すアドレスまたは`NULL`。
戻り値 : | 成功したときは`TRUE`、そうでない場合は`FALSE`。

1.1.5から

### gcut_process_write ()

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

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

`process` : | GCutProcess
`chunk` : | 書き込むデータ
`size` : | `chunk`のサイズ
`error` : | エラーを返すアドレスまたは`NULL`。
戻り値 : | 成功したときは`TRUE`、そうでない場合は`FALSE`。

1.1.5から

### gcut_process_flush ()

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

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

`process` : | GCutProcess
`error` : | エラーを返すアドレスまたは`NULL`。
戻り値 : | the status of the operation: One of `G_IO_STATUS_NORMAL`, `G_IO_STATUS_AGAIN`, or `G_IO_STATUS_ERROR`.

1.1.5から

### gcut_process_get_output_string ()

    GString *           gcut_process_get_output_string      (GCutProcess *process);

`process` : | GCutProcess
戻り値 : | 外部プロセスの標準出力の結果をすべて持ったGString。

1.1.5から

### gcut_process_get_error_string ()

    GString *           gcut_process_get_error_string       (GCutProcess *process);

`process` : | GCutProcess
戻り値 : | 外部プロセスの標準エラー出力の結果をすべて持ったGString。

1.1.5から

### gcut_process_get_input_channel ()

    GIOChannel *        gcut_process_get_input_channel      (GCutProcess *process);

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

`process` : | GCutProcess
戻り値 : | 外部プロセスが実行中の場合はGIOChannel。そうでない場合は`NULL`。

1.1.5から

### gcut_process_get_output_channel ()

    GIOChannel *        gcut_process_get_output_channel     (GCutProcess *process);

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

`process` : | GCutProcess
戻り値 : | 外部プロセスが実行中の場合はGIOChannel。そうでない場合は`NULL`。

1.1.5から

### gcut_process_get_error_channel ()

    GIOChannel *        gcut_process_get_error_channel      (GCutProcess *process);

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

`process` : | GCutProcess
戻り値 : | 外部プロセスが実行中の場合はGIOChannel。そうでない場合は`NULL`。

1.1.5から

### gcut_process_get_output_stream ()

    GInputStream *      gcut_process_get_output_stream      (GCutProcess *process);

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

`process` : | GCutProcess
戻り値 : | 外部プロセスが実行中の場合はGInputStream。そうでない場合は`NULL`。

1.1.5から

### gcut_process_get_error_stream ()

    GInputStream *      gcut_process_get_error_stream       (GCutProcess *process);

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

`process` : | GCutProcess
戻り値 : | 外部プロセスが実行中の場合はGInputStream。そうでない場合は`NULL`。

1.1.5から

### gcut_process_get_forced_termination_wait_time ()

    guint               gcut_process_get_forced_termination_wait_time
                                                            (GCutProcess *process);

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

`process` : | GCutProcess
戻り値 : | 破棄時の強制終了待ちの時間。

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です。

`process` : | GCutProcess
`timeout` : | タイムアウト時間（ミリ秒）

1.1.5から

### gcut_process_get_event_loop ()

    GCutEventLoop *     gcut_process_get_event_loop         (GCutProcess *process);

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

`process` : | GCutProcess
戻り値 : | GCutEventLoop。

1.1.6から

### gcut_process_set_event_loop ()

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

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

`process` : | GCutProcess
`loop` : | イベントループまたは`NULL`。

1.1.6から

## プロパティ詳細

### `"command"`プロパティ

      "command"                  gpointer              : Read / Write

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

## シグナル詳細

### `"error"`シグナル

    void                user_function                      (GCutProcess *process,
                                                            gpointer     error,
                                                            gpointer     user_data)      : Run Last

外部プロセス関連のエラーが発生した毎に発行されます。（例: 入出力エラー）

`process` : | シグナルを受け取るオブジェクト。
`error` : | 外部プロセスのエラー。（`GError`）
`user_data` : | シグナルハンドラが接続された時にユーザが指定したデータ。

1.1.5から

### `"error-received"`シグナル

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

外部プロセスが標準エラー出力に出力したデータが読み込まれる毎に発行されます。

外部コマンドの出力が読み取り可能になったかどうかを検出するために、`g_main_loop_run()`や`g_main_context_iteration()`などでGLibのメインループをまわす必要があることに注意してください。

`process` : | シグナルを受け取るオブジェクト。
`chunk` : | 外部プロセスの標準エラー出力から読み込んだデータ。
`size` : | `chunk`のサイズ。（`gsize`）
`user_data` : | シグナルハンドラが接続された時にユーザが指定したデータ。

1.1.5から

### `"output-received"`シグナル

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

外部プロセスが標準出力に出力したデータが読み込まれる毎に発行されます。

外部コマンドの出力が読み取り可能になったかどうかを検出するために、`g_main_loop_run()`や`g_main_context_iteration()`などでGLibのメインループをまわす必要があることに注意してください。

`process` : | シグナルを受け取るオブジェクト。
`chunk` : | 外部プロセスの標準出力から読み込んだデータ。
`size` : | `chunk`のサイズ。（`gsize`）
`user_data` : | シグナルハンドラが接続された時にユーザが指定したデータ。

1.1.5から

### `"reaped"`シグナル

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

外部プロセスが終了した時に発行されます。

外部コマンドが終了したこと検出するために、`g_main_loop_run()`や`g_main_context_iteration()`などでGLibのメインループをまわす必要があることに注意してください。

`process` : | シグナルを受け取るオブジェクト。
`status` : | 外部プロセスの終了ステータス。
`user_data` : | シグナルハンドラが接続された時にユーザが指定したデータ。

1.1.5から