外部コマンド（非推奨） 3 Cutterライブラリ
外部コマンド（非推奨） 外部コマンドを使うための便利API（非推奨）

## 概要

    #define             GCUT_EGG_ERROR
                        GCutEgg;
                        GCutEggClass;
    enum                GCutEggError;
    GQuark              gcut_egg_error_quark                (void);
    GCutEgg *           gcut_egg_new                        (const gchar *command,
                                                             ...);
    GCutEgg *           gcut_egg_new_va_list                (const gchar *command,
                                                             va_list args);
    GCutEgg *           gcut_egg_new_argv                   (gint argc,
                                                             gchar **argv);
    GCutEgg *           gcut_egg_new_strings                (const gchar **command);
    GCutEgg *           gcut_egg_new_array                  (GArray *command);
    void                gcut_egg_set_flags                  (GCutEgg *egg,
                                                             GSpawnFlags flags);
    GSpawnFlags         gcut_egg_get_flags                  (GCutEgg *egg);
    void                gcut_egg_set_env                    (GCutEgg *egg,
                                                             const gchar *name,
                                                             ...);
    gchar **            gcut_egg_get_env                    (GCutEgg *egg);
    gboolean            gcut_egg_hatch                      (GCutEgg *egg,
                                                             GError **error);
    void                gcut_egg_close                      (GCutEgg *egg);
    gboolean            gcut_egg_write                      (GCutEgg *egg,
                                                             const gchar *chunk,
                                                             gsize size,
                                                             GError **error);
    GPid                gcut_egg_get_pid                    (GCutEgg *egg);
    gint                gcut_egg_wait                       (GCutEgg *egg,
                                                             guint timeout,
                                                             GError **error);
    void                gcut_egg_kill                       (GCutEgg *egg,
                                                             gint signal_number);
    GIOChannel *        gcut_egg_get_input                  (GCutEgg *egg);
    GIOChannel *        gcut_egg_get_output                 (GCutEgg *egg);
    GIOChannel *        gcut_egg_get_error                  (GCutEgg *egg);
    guint               gcut_egg_get_forced_termination_wait_time
                                                            (GCutEgg *egg);
    void                gcut_egg_set_forced_termination_wait_time
                                                            (GCutEgg *egg,
                                                             guint timeout);

## オブジェクト階層

      GObject
       +----GCutEgg

## プロパティ

      "command"                  gpointer              : Read / Write

## シグナル

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

## 説明

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

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

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

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

例:

    static GString *output_string;
    static GCutEgg *egg;

    void
    cut_setup (void)
    {
        output_string = g_string_new(NULL);
        egg = NULL;
    }

    void
    cut_teardown (void)
    {
        if (output_string)
            g_string_free(output_string, TRUE);
        if (egg)
            g_object_unref(egg);
    }

    static void
    cb_output_received (GCutEgg *egg, const gchar *chunk, gsize size,
                        gpointer user_data)
    {
        g_string_append_len(output_string, chunk, size);
    }

    void
    test_echo (void)
    {
        GError *error = NULL;

        egg = gcut_egg_new("echo", "XXX", NULL);
        g_signal_connect(egg, "receive-output",
                         G_CALLBACK(cb_output_received), NULL);

        gcut_egg_hatch(egg, &error);
        gcut_assert_error(error);

        gcut_egg_wait(egg, 1000, &error);
        gcut_assert_error(error);
        cut_assert_equal_string("XXX\n", output_string->str);
    }

## 詳細

### GCUT_EGG_ERROR

    #define GCUT_EGG_ERROR           (gcut_egg_error_quark())

`GCUT_EGG_ERROR`は非推奨です。新しいコードでは使わないでください。

GCUT_EGG_ERROR

### GCutEgg

    typedef struct _GCutEgg GCutEgg;

`GCutEgg`は非推奨です。新しいコードでは使わないでください。

GCutEgg

### GCutEggClass

    typedef struct {
        GObjectClass parent_class;

        void (*output_received) (GCutEgg     *egg,
                                 const gchar *chunk,
                                 gsize        size);
        void (*error_received)  (GCutEgg     *egg,
                                 const gchar *chunk,
                                 gsize        size);
        void (*reaped)          (GCutEgg     *egg,
                                 gint         status);
        void (*error)           (GCutEgg     *egg,
                                 GError      *error);
    } GCutEggClass;

`GCutEggClass`は非推奨です。新しいコードでは使わないでください。

GCutEggClass

### enum GCutEggError

    typedef enum
    {
        GCUT_EGG_ERROR_COMMAND_LINE,
        GCUT_EGG_ERROR_IO_ERROR,
        GCUT_EGG_ERROR_ALREADY_RUNNING,
        GCUT_EGG_ERROR_NOT_RUNNING,
        GCUT_EGG_ERROR_INVALID_OBJECT,
        GCUT_EGG_ERROR_TIMEOUT
    } GCutEggError;

`GCutEggError`はバージョン1.1.5から非推奨になりました。新しく書くコードでは使わないでください。代わりにGCutProcessErrorを使ってください。

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

`GCUT_EGG_ERROR_COMMAND_LINE`

  コマンドライン関連のエラー。

`GCUT_EGG_ERROR_IO_ERROR`

  入出力エラー。

`GCUT_EGG_ERROR_ALREADY_RUNNING`

  外部コマンドはすでに実行されています。

`GCUT_EGG_ERROR_NOT_RUNNING`

  外部こもアンドが実行されていません。

`GCUT_EGG_ERROR_INVALID_OBJECT`

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

`GCUT_EGG_ERROR_TIMEOUT`

  タイムアウト。

1.0.6から

GCutEggError
GCutEggError

### gcut_egg_error_quark ()

    GQuark              gcut_egg_error_quark                (void);

`gcut_egg_error_quark`は非推奨です。新しいコードでは使わないでください。

戻り値 :

gcut_egg_error_quark

### gcut_egg_new ()

    GCutEgg *           gcut_egg_new                        (const gchar *command,
                                                             ...);

`gcut_egg_new`はバージョン1.1.5から非推奨になりました。新しく書くコードでは使わないでください。代わりに`gcut_process_new()`を使ってください。

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

command :

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

... :

  commandの引数

戻り値 :

  新しいGCutEgg。

1.0.6から

gcut_egg_new
gcut_egg_new

### gcut_egg_new_va_list ()

    GCutEgg *           gcut_egg_new_va_list                (const gchar *command,
                                                             va_list args);

`gcut_egg_new_va_list`はバージョン1.1.5から非推奨になりました。新しく書くコードでは使わないで下さい。代わりに`gcut_process_new_va_list()`を使ってください。

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

command :

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

args :

  commandの引数

戻り値 :

  新しいGCutEgg。

1.0.6から

gcut_egg_new_va_list
gcut_egg_new_va_list

### gcut_egg_new_argv ()

    GCutEgg *           gcut_egg_new_argv                   (gint argc,
                                                             gchar **argv);

`gcut_egg_new_argv`はバージョン1.1.5から非推奨になりました。新しく書くコードでは使わないでください。代わりに`gcut_egg_new_argv()`を使ってください。

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

argc :

  argvの要素数

argv :

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

戻り値 :

  新しいGCutEgg。

1.0.6から

gcut_egg_new_argv
gcut_egg_new_argv

### gcut_egg_new_strings ()

    GCutEgg *           gcut_egg_new_strings                (const gchar **command);

`gcut_egg_new_strings`はバージョン1.1.5から非推奨になりました。新しく書くコードでは使わないでください。代わりに`gcut_process_new_strings()`を使ってください。

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

command :

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

戻り値 :

  新しいGCutEgg。

1.0.6から

gcut_egg_new_strings
gcut_egg_new_strings

### gcut_egg_new_array ()

    GCutEgg *           gcut_egg_new_array                  (GArray *command);

`gcut_egg_new_array`はバージョン1.1.5から非推奨になりました。新しく書くコードでは使わないでください。代わりに`gcut_egg_new_array()`を使ってください。

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

command :

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

戻り値 :

  新しいGCutEgg。

1.0.6から

gcut_egg_new_array
gcut_egg_new_array

### gcut_egg_set_flags ()

    void                gcut_egg_set_flags                  (GCutEgg *egg,
                                                             GSpawnFlags flags);

`gcut_egg_set_flags`はバージョン1.1.5から非推奨になりました。新しく書くコードでは使わないでください。代わりに`gcut_process_set_flags()`を使ってください。

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

egg :

  GCutEgg

flags :

  `g_spawn_async_with_pipes()`に渡すフラグ。

1.0.6から

gcut_egg_set_flags
gcut_egg_set_flags

### gcut_egg_get_flags ()

    GSpawnFlags         gcut_egg_get_flags                  (GCutEgg *egg);

`gcut_egg_get_flags`はバージョン1.1.5から非推奨になりました。新しく書くコードでは使わないでください。代わりに`gcut_process_get_flags()`を使ってください。

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

egg :

  GCutEgg

戻り値 :

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

1.0.6から

gcut_egg_get_flags
gcut_egg_get_flags

### gcut_egg_set_env ()

    void                gcut_egg_set_env                    (GCutEgg *egg,
                                                             const gchar *name,
                                                             ...);

`gcut_egg_set_env`はバージョン1.1.5から非推奨になりました。新しく書くコードでは使わないでください。代わりに`gcut_process_set_env()`を使ってください。

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

egg :

  GCutEgg

name :

  最初の環境変数名。

... :

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

1.0.6から

gcut_egg_set_env
gcut_egg_set_env

### gcut_egg_get_env ()

    gchar **            gcut_egg_get_env                    (GCutEgg *egg);

`gcut_egg_get_env`はバージョン1.1.5から非推奨になりました。新しく書くコードでは使わないでください。代わりに`gcut_process_get_env()`を使ってください。

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

egg :

  GCutEgg

戻り値 :

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

1.0.6から

gcut_egg_get_env
gcut_egg_get_env

### gcut_egg_hatch ()

    gboolean            gcut_egg_hatch                      (GCutEgg *egg,
                                                             GError **error);

`gcut_egg_hatch`はバージョン1.1.5から非推奨になりました。新しく書くコードでは使わないでください。代わりに`gcut_process_run()`を使ってください。

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

egg :

  GCutEgg

error :

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

戻り値 :

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

1.0.6から

gcut_egg_hatch
gcut_egg_hatch

### gcut_egg_close ()

    void                gcut_egg_close                      (GCutEgg *egg);

`gcut_egg_close`はバージョン1.1.5から非推奨になりました。新しく書くコードでは使わないでください。代わりにGCutProcessを使ってください。

実行した外部コマンドのリソースを回収します。破棄されるときに暗黙的に回収されます。

egg :

  GCutEgg

1.0.6から

gcut_egg_close
gcut_egg_close

### gcut_egg_write ()

    gboolean            gcut_egg_write                      (GCutEgg *egg,
                                                             const gchar *chunk,
                                                             gsize size,
                                                             GError **error);

`gcut_egg_write`はバージョン1.1.5から非推奨になりました。新しく書くコードでは使わないでください。代わりに`gcut_process_write()`を使ってください。

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

egg :

  GCutEgg

chunk :

  書き込むデータ

size :

  chunkのサイズ

error :

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

戻り値 :

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

1.0.6から

gcut_egg_write
gcut_egg_write

### gcut_egg_get_pid ()

    GPid                gcut_egg_get_pid                    (GCutEgg *egg);

`gcut_egg_get_pid`はバージョン1.1.5から非推奨になりました。新しく書くコードでは使わないでください。代わりに`gcut_process_get_pid()`を使ってください。

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

egg :

  GCutEgg

戻り値 :

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

1.0.6から

gcut_egg_get_pid
gcut_egg_get_pid

### gcut_egg_wait ()

    gint                gcut_egg_wait                       (GCutEgg *egg,
                                                             guint timeout,
                                                             GError **error);

`gcut_egg_wait`はバージョン1.1.5から非推奨になりました。新しく書くコードでは使わないでください。代わりに`gcut_process_wait()`を使ってください。

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

egg :

  GCutEgg

timeout :

  タイムアウト時間（ミリ秒）

error :

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

戻り値 :

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

1.0.6から

gcut_egg_wait
gcut_egg_wait

### gcut_egg_kill ()

    void                gcut_egg_kill                       (GCutEgg *egg,
                                                             gint signal_number);

`gcut_egg_kill`はバージョン1.1.5から非推奨になりました。新しく書くコードでは使わないで下さい。代わりに`gcut_process_kill()`を使ってください。

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

egg :

  GCutEgg

signal_number :

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

1.0.6から

gcut_egg_kill
gcut_egg_kill

### gcut_egg_get_input ()

    GIOChannel *        gcut_egg_get_input                  (GCutEgg *egg);

`gcut_egg_get_input`はバージョン1.1.5から非推奨になりました。新しく書くコードでは使わないでください。代わりに`gcut_process_get_input_channel()`を使ってください。

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

egg :

  GCutEgg

戻り値 :

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

1.0.6から

gcut_egg_get_input
gcut_egg_get_input

### gcut_egg_get_output ()

    GIOChannel *        gcut_egg_get_output                 (GCutEgg *egg);

`gcut_egg_get_output`はバージョン1.1.5から非推奨になりました。新しく書くコードでは使わないでください。代わりに`gcut_process_get_output_channel()`を使ってください。

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

egg :

  GCutEgg

戻り値 :

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

1.0.6から

gcut_egg_get_output
gcut_egg_get_output

### gcut_egg_get_error ()

    GIOChannel *        gcut_egg_get_error                  (GCutEgg *egg);

`gcut_egg_get_error`はバージョン1.1.5から非推奨になりました。新しく書くコードでは使わないでください。代わりに`gcut_egg_get_error()`を使ってください。

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

egg :

  GCutEgg

戻り値 :

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

1.0.6から

gcut_egg_get_error
gcut_egg_get_error

### gcut_egg_get_forced_termination_wait_time ()

    guint               gcut_egg_get_forced_termination_wait_time
                                                            (GCutEgg *egg);

`gcut_egg_get_forced_termination_wait_time`はバージョン1.1.5から非推奨になりました。新しく書くコードでは使わないでください。代わりに`gcut_process_get_forced_termination_wait_time()`を使ってください。

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

egg :

  GCutEgg

戻り値 :

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

1.0.6から

gcut_egg_get_forced_termination_wait_time
gcut_egg_get_forced_termination_wait_time

### gcut_egg_set_forced_termination_wait_time ()

    void                gcut_egg_set_forced_termination_wait_time
                                                            (GCutEgg *egg,
                                                             guint timeout);

`gcut_egg_set_forced_termination_wait_time`はバージョン1.1.5から非推奨になりました。新しく書くコードでは使わないでください。代わりに`gcut_egg_set_forced_termination_wait_time()`を使ってください。

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

egg :

  GCutEgg

timeout :

  タイムアウト時間（ミリ秒）

1.0.6から

gcut_egg_set_forced_termination_wait_time
gcut_egg_set_forced_termination_wait_time

## プロパティ詳細

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

      "command"                  gpointer              : Read / Write

実行する外部コマンド。

GCutEgg:command

## シグナル詳細

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

    void                user_function                      (GCutEgg *egg,
                                                            gpointer error,
                                                            gpointer user_data)      : Run Last

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

egg :

  シグナルを受け取るオブジェクト。

error :

  外部プロセスのエラー。（`GError`）

user_data :

  シグナルハンドラが接続された時にユーザが指定したデータ。

1.0.6から

GCutEgg::error

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

    void                user_function                      (GCutEgg *egg,
                                                            gchar   *chunk,
                                                            guint64  size,
                                                            gpointer user_data)      : Run Last

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

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

egg :

  シグナルを受け取るオブジェクト。

chunk :

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

size :

  chunkのサイズ。（`gsize`）

user_data :

  シグナルハンドラが接続された時にユーザが指定したデータ。

1.0.6から

GCutEgg::error-received

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

    void                user_function                      (GCutEgg *egg,
                                                            gchar   *chunk,
                                                            guint64  size,
                                                            gpointer user_data)      : Run Last

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

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

egg :

  シグナルを受け取るオブジェクト。

chunk :

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

size :

  chunkのサイズ。（`gsize`）

user_data :

  シグナルハンドラが接続された時にユーザが指定したデータ。

1.0.6から

GCutEgg::output-received

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

    void                user_function                      (GCutEgg *egg,
                                                            gint     status,
                                                            gpointer user_data)      : Run Last

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

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

egg :

  シグナルを受け取るオブジェクト。

status :

  外部プロセスの終了ステータス。

user_data :

  シグナルハンドラが接続された時にユーザが指定したデータ。

1.0.6から

GCutEgg::reaped