## Name

gfarm — Gfarm ファイルシステム API ライブラリ

## Synopsis

    #include <gfarm/gfarm.h>

## DESCRIPTION

Gfarm ライブラリは，Gfarm ファイルシステムや，スケジューリング 機能に対するインターフェースを提供します．このマニュアルはライブラリ の概要を記述します．各関数の詳細は，関数単位のマニュアルを参照して ください．

### 初期化／終了処理

gfarm_initialize 関数は Gfarm ライブラリの初期化に， gfarm_terminate 関数は Gfarm ライブラリの終了処理に用います．

### ファイル入出力処理

既存のファイルをストリームとしてオープンするには gfs_pio_open 関数を， 新規ファイルを作成してストリームとしてオープンするには gfs_pio_create 関数を用います． ファイルのクローズは gfs_pio_close 関数を使います．

gfs_pio_error 関数はオープンしているストリームに関してエラーが生じているか を判別し， gfs_pio_eof 関数は読み込みオープンしているストリームがファイル 末尾に達しているかを判別します． gfs_pio_seek 関数は，ストリーム中の現在位置を変更します．

gfs_pio_getc 関数はストリームから一文字読み込み， gfs_pio_ungetc 関数は逆に読み込んだ一文字をストリームに戻します． gfs_pio_getline 関数や gfs_pio_gets 関数， gfs_pio_readline 関数は，ストリームから一行を読み込み， gfs_pio_readdelim 関数は，ストリームから指定したデリミタまでを読み込みます． gfs_pio_read 関数は，ストリームから指定したバイト数だけ読み込みます．

gfs_pio_putc 関数はストリームへ一文字書きだし， gfs_pio_putline 関数や gfs_pio_puts 関数はストリームへ一行書きだします． gfs_pio_write 関数は，ストリームへ指定したバイト数だけ書き込みます． gfs_pio_flush 関数や， gfs_pio_sync 関数， gfs_pio_datasync 関数は，バッファリングしているデータを記憶装置に書き出します． gfs_pio_truncate 関数は，ファイルのサイズを変更します．

### ディレクトリアクセス

gfs_opendir 関数でディレクトリをオープンすると， gfs_readdir 関数で，そのディレクトリを構成するエントリを得ることが できます．オープンしたディレクトリへのアクセスは， gfs_closedir 関数で終了します．

gfs_glob_init 関数で初期化した gfs_glob_t を gfs_glob 関数に渡すことで，ワイルドカードの展開を行うことが できます． 利用が終わったら，この領域は gfs_glob_free 関数で開放します． gfs_glob_add 関数は，gfs_glob_t にエントリを追加するのに用います．

### ファイル／ディレクトリ操作

gfs_chmod 関数でファイルのモードを変更し， gfs_chown 関数でファイルの所有者を変更し， gfs_utimes 関数でファイルの更新時刻とアクセス時刻を変更します．

gfs_mkdir 関数はディレクトリを作成し， gfs_rmdir 関数はディレクトリを削除します． gfs_unlink 関数はファイルを削除し， gfs_rename 関数はディレクトリやファイルを改名します．

gfs_stat 関数は指定したファイルあるいはディレクトリのサイズや 更新時刻などの情報を返します． この関数が返した gfs_stat 構造体は gfs_stat_free 関数を用いて解放する必要があります．

### アクセスコントロールリスト (ACL) 操作

gfs_acl_init 関数は ACL 構造体 (gfarm_acl_t) を初期化し， gfs_acl_free 関数で ACL 構造体を開放します． gfs_acl_dup 関数は ACL 構造体を複製します．

gfs_acl_create_entry 関数は ACL 構造体の ACL エントリ (gfarm_acl_entry_t) をひとつ生成して追加し， gfs_acl_get_entry 関数で ACL 構造体の ACL エントリをひとつ取得し， gfs_acl_delete_entry 関数で ACL 構造体の ACL エントリをひとつ削除します．

gfs_acl_valid 関数は ACL 構造体が有効な形式かどうか確認します． gfs_acl_check 関数ならばより詳しく確認できます．

gfs_acl_calc_mask 関数は ACL 構造体の GFARM_ACL_MASK タグのエントリを計算 して，GFARM_ACL_MASK が既に存在すれば上書きし，存在しなければ作成します．

gfs_acl_get_tag_type 関数は ACL エントリから ACL タグ (gfarm_acl_tag_t) (ACL エントリの種類) を取得します． gfs_acl_set_tag_type 関数は ACL エントリの ACL タグを差し替えます．

gfs_acl_get_permset 関数は ACL エントリから ACL パーミッションセット (gfarm_acl_permset_t) を取り出します． gfs_acl_set_permset 関数は ACL エントリへ ACL パーミッションセットを差し替えます．

gfs_acl_add_perm 関数は ACL パーミッションセットに ACL パーミッション値 (gfarm_acl_perm_t) を追加します． gfs_acl_clear_perms 関数は ACL パーミッションセットからすべての ACL パーミッション値をクリアします． gfs_acl_delete_perm 関数は ACL パーミッションセットから ACL パーミッション値をひとつ削除します．

gfs_acl_get_qualifier 関数は ACL エントリから，ユーザ名またはグループ名を取得します． GFARM_ACL_USER または GFARM_ACL_GROUP タグの ACL エントリから取得できます． gfs_acl_set_qualifier 関数は ACL エントリに対して，指定したユーザ名またはグループ名を 差し替えます．

gfs_acl_delete_def_file 関数は，ファイルやディレクトリからデフォルト ACL を削除します． gfs_acl_get_file 関数は，ファイルやディレクトリから ACL 構造体を取得します． gfs_acl_set_file 関数は，ファイルやディレクトリの ACL 構造体を差し替えます． 事前に gfs_acl_sort 関数でソートしてください．

gfs_acl_to_text 関数は ACL 構造体を ACL 文字列形式に変換します． gfs_acl_to_any_text 関数のほうがより高機能です． gfs_acl_from_text 関数は ACL 文字列形式から ACL 構造体に変換します．

gfs_acl_get_perm 関数は ACL パーミッションセットの中から ひとつのパーミッションをテストします．

gfs_acl_check 関数は ACL 構造体が有効な形式かどうか確認します． また，エラーの場所とエラーの種類がわかります． gfs_acl_valid 関数よりも高機能です． gfs_acl_error 関数は gfs_acl_check 関数のエラーを文字列に変換します．

gfs_acl_entries 関数は ACL エントリの数を数えます．

gfs_acl_equiv_mode 関数は，ACL 構造体が基本 ACL (GFARM_ACL_USER_OBJ, GFARM_ACL_GROUP_OBJ, GFARM_ACL_OTHER) だけで構成されているかどうか確認します． また，基本 ACL 部分から gfarm_mode_t に変換できます．

gfs_acl_cmp 関数は二つの ACL 構造体を比較します．

gfs_acl_from_mode 関数は gfarm_mode_t から ACL 構造体を生成します．

gfs_acl_to_any_text 関数は ACL 構造体を ACL 文字列形式に変換します． 出力形式をオプションなどで変更できます． gfs_acl_to_text 関数と比べて高機能です．

gfs_acl_to_xattr_value 関数は ACL 構造体を拡張属性に格納するための ACL バイナリデータに変換します． 事前に gfs_acl_sort 関数でソートしてください． gfs_acl_from_xattr_value 関数は拡張属性から取り出した ACL バイナリデータを ACL 構造体に変換します．

gfs_acl_sort 関数は ACL 構造体を有効な形式となる順番にソートします．

gfs_acl_from_text_with_default 関数は "default:" で始まる ACL エントリを持つ ACL 文字列を解釈し，アクセス ACL 構造体とデフォルト ACL 構造体を 2 個生成します．

### エラーコード

ほとんどの Gfarm ライブラリの関数は gfarm_error_t 型の Gfarm エラーコー ドを返します。 gfarm_error_string 関数は Gfarm エラーコードを表す文字列を返します。 gfarm_errno_to_error 関数は errno を Gfarm エラーコードに変換します。 gfarm_error_to_errno 関数は Gfarm エラーコードを errno に変換します。

### 文字列配列操作ユーティリティ

文字列配列を表す gfarm_stringlist 型の変数は， gfarm_stringlist_init 関数で初期化し， gfarm_stringlist_add 関数で文字列を一つ追加し， gfarm_stringlist_cat 関数で文字列を複数追加し， gfarm_stringlist_free 関数で解放することができます． 文字列配列の各要素文字列には gfarm_stringlist_elem 関数あるいは GFARM_STRINGLIST_ELEM() マクロでアクセスすることができます． また，文字列配列を構成する文字列の数は gfarm_stringlist_length 関数で得ることができます．

gfarm_strings_free_deeply 関数は，文字列配列およびそれを構成する各文字列に対して 標準ライブラリ関数の free() を呼び出して解放します．

### 文字列配列操作ユーティリティマクロ

GFARM_STRINGLIST_ELEM(list, i)

  gfarm_stringlist 型の `list` 引数が表す文字列配列の `i` 番目の要素を 表すマクロです．このマクロは左辺値として使えます． 値として評価した場合には gfarm_stringlist_elem 関数と同一の結果を返します．

GFARM_STRINGLIST_STRARRAY(list)

  gfarm_stringlist 型の `list` 引数が 表す文字列配列の先頭要素へのポインタを返します． 返り値は，文字へのポインタへのポインタとなります．