'\" t
.\"     Title: gfarm
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 26 Jun 2010
.\"    Manual: Gfarm
.\"    Source: Gfarm
.\"  Language: English
.\"
.TH "GFARM" "3" "26 Jun 2010" "Gfarm" "Gfarm"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
gfarm \- Gfarm ファイルシステム API ライブラリ
.SH "SYNOPSIS"
.sp
.nf
#include <gfarm/gfarm\&.h>

.fi
.SH "DESCRIPTION"
.PP
Gfarm ライブラリは，Gfarm ファイルシステムや，スケジューリング 機能に対するインターフェースを提供します．このマニュアルはライブラリ の概要を記述します．各関数の詳細は，関数単位のマニュアルを参照して ください．
.SS "初期化／終了処理"
.PP
\fBgfarm_initialize\fR()
関数は Gfarm ライブラリの初期化に，
\fBgfarm_terminate\fR()
関数は Gfarm ライブラリの終了処理に用います．
.SS "ファイル入出力処理"
.PP
既存のファイルをストリームとしてオープンするには
\fBgfs_pio_open\fR()
関数を， 新規ファイルを作成してストリームとしてオープンするには
\fBgfs_pio_create\fR()
関数を用います． ファイルのクローズは
\fBgfs_pio_close\fR()
関数を使います．
.PP
\fBgfs_pio_error\fR()
関数はオープンしているストリームに関してエラーが生じているか を判別し，
\fBgfs_pio_eof\fR()
関数は読み込みオープンしているストリームがファイル 末尾に達しているかを判別します．
\fBgfs_pio_seek\fR()
関数は，ストリーム中の現在位置を変更します．
.PP
\fBgfs_pio_getc\fR()
関数はストリームから一文字読み込み，
\fBgfs_pio_ungetc\fR()
関数は逆に読み込んだ一文字をストリームに戻します．
\fBgfs_pio_getline\fR()
関数や
\fBgfs_pio_gets\fR()
関数，
\fBgfs_pio_readline\fR()
関数は，ストリームから一行を読み込み，
\fBgfs_pio_readdelim\fR()
関数は，ストリームから指定したデリミタまでを読み込みます．
\fBgfs_pio_read\fR()
関数は，ストリームから指定したバイト数だけ読み込みます．
.PP
\fBgfs_pio_putc\fR()
関数はストリームへ一文字書きだし，
\fBgfs_pio_putline\fR()
関数や
\fBgfs_pio_puts\fR()
関数はストリームへ一行書きだします．
\fBgfs_pio_write\fR()
関数は，ストリームへ指定したバイト数だけ書き込みます．
\fBgfs_pio_flush\fR()
関数や，
\fBgfs_pio_sync\fR()
関数，
\fBgfs_pio_datasync\fR()
関数は，バッファリングしているデータを記憶装置に書き出します．
\fBgfs_pio_truncate\fR()
関数は，ファイルのサイズを変更します．
.SS "ディレクトリアクセス"
.PP
\fBgfs_opendir\fR()
関数でディレクトリをオープンすると，
\fBgfs_readdir\fR()
関数で，そのディレクトリを構成するエントリを得ることが できます．オープンしたディレクトリへのアクセスは，
\fBgfs_closedir\fR()
関数で終了します．
.PP
\fBgfs_glob_init\fR()
関数で初期化した gfs_glob_t を
\fBgfs_glob\fR()
関数に渡すことで，ワイルドカードの展開を行うことが できます． 利用が終わったら，この領域は
\fBgfs_glob_free\fR()
関数で開放します．
\fBgfs_glob_add\fR()
関数は，gfs_glob_t にエントリを追加するのに用います．
.SS "ファイル／ディレクトリ操作"
.PP
\fBgfs_chmod\fR()
関数でファイルのモードを変更し，
\fBgfs_chown\fR()
関数でファイルの所有者を変更し，
\fBgfs_utimes\fR()
関数でファイルの更新時刻とアクセス時刻を変更します．
.PP
\fBgfs_mkdir\fR()
関数はディレクトリを作成し，
\fBgfs_rmdir\fR()
関数はディレクトリを削除します．
\fBgfs_unlink\fR()
関数はファイルを削除し，
\fBgfs_rename\fR()
関数はディレクトリやファイルを改名します．
.PP
\fBgfs_stat\fR()
関数は指定したファイルあるいはディレクトリのサイズや 更新時刻などの情報を返します． この関数が返した gfs_stat 構造体は
\fBgfs_stat_free\fR()
関数を用いて解放する必要があります．
.SS "アクセスコントロールリスト (ACL) 操作"
.PP
\fBgfs_acl_init\fR()
関数は ACL 構造体 (gfarm_acl_t) を初期化し，
\fBgfs_acl_free\fR()
関数で ACL 構造体を開放します．
\fBgfs_acl_dup\fR()
関数は ACL 構造体を複製します．
.PP
\fBgfs_acl_create_entry\fR()
関数は ACL 構造体の ACL エントリ (gfarm_acl_entry_t) をひとつ生成して追加し，
\fBgfs_acl_get_entry\fR()
関数で ACL 構造体の ACL エントリをひとつ取得し，
\fBgfs_acl_delete_entry\fR()
関数で ACL 構造体の ACL エントリをひとつ削除します．
.PP
\fBgfs_acl_valid\fR()
関数は ACL 構造体が有効な形式かどうか確認します． gfs_acl_check 関数ならばより詳しく確認できます．
.PP
\fBgfs_acl_calc_mask\fR()
関数は ACL 構造体の GFARM_ACL_MASK タグのエントリを計算 して，GFARM_ACL_MASK が既に存在すれば上書きし，存在しなければ作成します．
.PP
\fBgfs_acl_get_tag_type\fR()
関数は ACL エントリから ACL タグ (gfarm_acl_tag_t) (ACL エントリの種類) を取得します．
\fBgfs_acl_set_tag_type\fR()
関数は ACL エントリの ACL タグを差し替えます．
.PP
\fBgfs_acl_get_permset\fR()
関数は ACL エントリから ACL パーミッションセット (gfarm_acl_permset_t) を取り出します．
\fBgfs_acl_set_permset\fR()
関数は ACL エントリへ ACL パーミッションセットを差し替えます．
.PP
\fBgfs_acl_add_perm\fR()
関数は ACL パーミッションセットに ACL パーミッション値 (gfarm_acl_perm_t) を追加します．
\fBgfs_acl_clear_perms\fR()
関数は ACL パーミッションセットからすべての ACL パーミッション値をクリアします．
\fBgfs_acl_delete_perm\fR()
関数は ACL パーミッションセットから ACL パーミッション値をひとつ削除します．
.PP
\fBgfs_acl_get_qualifier\fR()
関数は ACL エントリから，ユーザ名またはグループ名を取得します． GFARM_ACL_USER または GFARM_ACL_GROUP タグの ACL エントリから取得できます．
\fBgfs_acl_set_qualifier\fR()
関数は ACL エントリに対して，指定したユーザ名またはグループ名を 差し替えます．
.PP
\fBgfs_acl_delete_def_file\fR()
関数は，ファイルやディレクトリからデフォルト ACL を削除します．
\fBgfs_acl_get_file\fR()
関数は，ファイルやディレクトリから ACL 構造体を取得します．
\fBgfs_acl_set_file\fR()
関数は，ファイルやディレクトリの ACL 構造体を差し替えます． 事前に gfs_acl_sort 関数でソートしてください．
.PP
\fBgfs_acl_to_text\fR()
関数は ACL 構造体を ACL 文字列形式に変換します． gfs_acl_to_any_text 関数のほうがより高機能です．
\fBgfs_acl_from_text\fR()
関数は ACL 文字列形式から ACL 構造体に変換します．
.PP
\fBgfs_acl_get_perm\fR()
関数は ACL パーミッションセットの中から ひとつのパーミッションをテストします．
.PP
\fBgfs_acl_check\fR()
関数は ACL 構造体が有効な形式かどうか確認します． また，エラーの場所とエラーの種類がわかります． gfs_acl_valid 関数よりも高機能です．
\fBgfs_acl_error\fR()
関数は gfs_acl_check 関数のエラーを文字列に変換します．
.PP
\fBgfs_acl_entries\fR()
関数は ACL エントリの数を数えます．
.PP
\fBgfs_acl_equiv_mode\fR()
関数は，ACL 構造体が基本 ACL (GFARM_ACL_USER_OBJ, GFARM_ACL_GROUP_OBJ, GFARM_ACL_OTHER) だけで構成されているかどうか確認します． また，基本 ACL 部分から gfarm_mode_t に変換できます．
.PP
\fBgfs_acl_cmp\fR()
関数は二つの ACL 構造体を比較します．
.PP
\fBgfs_acl_from_mode\fR()
関数は gfarm_mode_t から ACL 構造体を生成します．
.PP
\fBgfs_acl_to_any_text\fR()
関数は ACL 構造体を ACL 文字列形式に変換します． 出力形式をオプションなどで変更できます． gfs_acl_to_text 関数と比べて高機能です．
.PP
\fBgfs_acl_to_xattr_value\fR()
関数は ACL 構造体を拡張属性に格納するための ACL バイナリデータに変換します． 事前に gfs_acl_sort 関数でソートしてください．
\fBgfs_acl_from_xattr_value\fR()
関数は拡張属性から取り出した ACL バイナリデータを ACL 構造体に変換します．
.PP
\fBgfs_acl_sort\fR()
関数は ACL 構造体を有効な形式となる順番にソートします．
.PP
\fBgfs_acl_from_text_with_default\fR()
関数は "default:" で始まる ACL エントリを持つ ACL 文字列を解釈し，アクセス ACL 構造体とデフォルト ACL 構造体を 2 個生成します．
.SS "エラーコード"
.PP
ほとんどの Gfarm ライブラリの関数は gfarm_error_t 型の Gfarm エラーコー ドを返します。
\fBgfarm_error_string\fR()
関数は Gfarm エラーコードを表す文字列を返します。
\fBgfarm_errno_to_error\fR()
関数は errno を Gfarm エラーコードに変換します。
\fBgfarm_error_to_errno\fR()
関数は Gfarm エラーコードを errno に変換します。
.SS "文字列配列操作ユーティリティ"
.PP
文字列配列を表す gfarm_stringlist 型の変数は，
\fBgfarm_stringlist_init\fR()
関数で初期化し，
\fBgfarm_stringlist_add\fR()
関数で文字列を一つ追加し，
\fBgfarm_stringlist_cat\fR()
関数で文字列を複数追加し，
\fBgfarm_stringlist_free\fR()
関数で解放することができます． 文字列配列の各要素文字列には
\fBgfarm_stringlist_elem\fR()
関数あるいは GFARM_STRINGLIST_ELEM() マクロでアクセスすることができます． また，文字列配列を構成する文字列の数は
\fBgfarm_stringlist_length\fR()
関数で得ることができます．
.PP
\fBgfarm_strings_free_deeply\fR()
関数は，文字列配列およびそれを構成する各文字列に対して 標準ライブラリ関数の free() を呼び出して解放します．
.SS "文字列配列操作ユーティリティマクロ"
.PP
GFARM_STRINGLIST_ELEM(list, i)
.RS 4
gfarm_stringlist 型の
\fIlist\fR
引数が表す文字列配列の
\fIi\fR
番目の要素を 表すマクロです．このマクロは左辺値として使えます． 値として評価した場合には
\fBgfarm_stringlist_elem\fR()
関数と同一の結果を返します．
.RE
.PP
GFARM_STRINGLIST_STRARRAY(list)
.RS 4
gfarm_stringlist 型の
\fIlist\fR
引数が 表す文字列配列の先頭要素へのポインタを返します． 返り値は，文字へのポインタへのポインタとなります．
.RE