外部コマンド

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

概要

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

オブジェクト階層

  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()を使うことができます。無限待ちを避けるために、タイムアウトを指定することができます。

例:

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


struct GCutProcess

struct GCutProcess;


struct GCutProcessClass

struct GCutProcessClass {
    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);
};


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_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_env ()

gchar **            gcut_process_get_env                (GCutProcess *process);

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

process :

GCutProcess

戻り値 :

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

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_error_stream ()

GInputStream *      gcut_process_get_error_stream       (GCutProcess *process);

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

process :

GCutProcess

戻り値 :

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

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_event_loop ()

GCutEventLoop *     gcut_process_get_event_loop         (GCutProcess *process);

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

process :

GCutProcess

戻り値 :

GCutEventLoop

1.1.6から


gcut_process_get_flags ()

GSpawnFlags         gcut_process_get_flags              (GCutProcess *process);

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

process :

GCutProcess

戻り値 :

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

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_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_output_stream ()

GInputStream *      gcut_process_get_output_stream      (GCutProcess *process);

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

process :

GCutProcess

戻り値 :

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

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_pid ()

GPid                gcut_process_get_pid                (GCutProcess *process);

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

process :

GCutProcess

戻り値 :

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

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_new ()

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

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

command :

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

... :

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_array ()

GCutProcess *       gcut_process_new_array              (GArray *command);

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

command :

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

戻り値 :

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_strings ()

GCutProcess *       gcut_process_new_strings            (const gchar **command);

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

command :

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

戻り値 :

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_run ()

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

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

process :

GCutProcess

error :

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

戻り値 :

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

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_set_event_loop ()

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

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

process :

GCutProcess

loop :

イベントループまたはNULL

1.1.6から


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_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_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_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から

プロパティ詳細

"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

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

外部コマンドの出力が読み取り可能になったかどうかを検出するために、gcut_event_loop_run()gcut_event_loop_iterate()<literl>GCutEventLoop</literl>

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

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

外部コマンドの出力が読み取り可能になったかどうかを検出するために、gcut_event_loop_run()gcut_event_loop_iterate()<literl>GCutEventLoop</literl>

process :

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

chunk :

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

size :

chunkのサイズ。(gsize

user_data :

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

1.1.5から


"reaped"シグナル

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

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

外部コマンドが終了したことを検出するために、gcut_event_loop_run()gcut_event_loop_iterate()GCutEventLoopをまわす必要があることに注意してください。

process :

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

status :

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

user_data :

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

1.1.5から