<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">


<refentry id="gfarm.3">

<refentryinfo><date>26 Jun 2010</date></refentryinfo>

<refmeta>
<refentrytitle>gfarm</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>Gfarm</refmiscinfo>
</refmeta>

<refnamediv id="name">
<refname>gfarm</refname>
<refpurpose>Gfarm ファイルシステム API ライブラリ</refpurpose>
</refnamediv>
<refsynopsisdiv id="synopsis">
<synopsis format="linespecific">
#include &lt;gfarm/gfarm.h&gt;

</synopsis>
</refsynopsisdiv>

<!-- body begins here -->

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

<refsect2 id="initialize-finalize">
<title>初期化／終了処理</title>
<para>
<citerefentry>
<refentrytitle>gfarm_initialize</refentrytitle>
</citerefentry> 関数は Gfarm ライブラリの初期化に，
<citerefentry>
<refentrytitle>gfarm_terminate</refentrytitle>
</citerefentry> 関数は Gfarm ライブラリの終了処理に用います．
</para>
</refsect2>

<refsect2 id="input-output-operations">
<title>ファイル入出力処理</title>
<para>
既存のファイルをストリームとしてオープンするには
<citerefentry>
<refentrytitle>gfs_pio_open</refentrytitle>
</citerefentry> 関数を，
新規ファイルを作成してストリームとしてオープンするには
<citerefentry>
<refentrytitle>gfs_pio_create</refentrytitle>
</citerefentry> 関数を用います．
ファイルのクローズは
<citerefentry>
<refentrytitle>gfs_pio_close</refentrytitle>
</citerefentry> 関数を使います．
</para>

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

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

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

<citerefentry>
<refentrytitle>gfs_pio_truncate</refentrytitle>
</citerefentry> 関数は，ファイルのサイズを変更します．
</para>
</refsect2>

<refsect2 id="directory-access">
<title>ディレクトリアクセス</title>
<!--
<para>
<citerefentry>
<refentrytitle>gfs_chdir</refentrytitle>
</citerefentry> 関数は，カレント作業ディレクトリを変更します．
<citerefentry>
<refentrytitle>gfs_realpath</refentrytitle>
</citerefentry> 関数は，引数のフルパス名を返します．
</para>
 -->
<para>
<citerefentry>
<refentrytitle>gfs_opendir</refentrytitle>
</citerefentry> 関数でディレクトリをオープンすると，
<citerefentry>
<refentrytitle>gfs_readdir</refentrytitle>
</citerefentry> 関数で，そのディレクトリを構成するエントリを得ることが
できます．オープンしたディレクトリへのアクセスは，
<citerefentry>
<refentrytitle>gfs_closedir</refentrytitle>
</citerefentry> 関数で終了します．
</para>

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

<refsect2 id="file-directory-manipulation">
<title>ファイル／ディレクトリ操作</title>
<para>
<citerefentry>
<refentrytitle>gfs_chmod</refentrytitle>
</citerefentry> 関数でファイルのモードを変更し，
<citerefentry>
<refentrytitle>gfs_chown</refentrytitle>
</citerefentry> 関数でファイルの所有者を変更し，
<citerefentry>
<refentrytitle>gfs_utimes</refentrytitle>
</citerefentry> 関数でファイルの更新時刻とアクセス時刻を変更します．
</para>

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

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

<refsect2 id="acl-operations">
<title>アクセスコントロールリスト (ACL) 操作</title>
<para>
<citerefentry>
<refentrytitle>gfs_acl_init</refentrytitle>
</citerefentry> 関数は ACL 構造体 (gfarm_acl_t) を初期化し，
<citerefentry>
<refentrytitle>gfs_acl_free</refentrytitle>
</citerefentry> 関数で ACL 構造体を開放します．
<citerefentry>
<refentrytitle>gfs_acl_dup</refentrytitle>
</citerefentry> 関数は ACL 構造体を複製します．
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_create_entry</refentrytitle>
</citerefentry> 関数は ACL 構造体の ACL エントリ (gfarm_acl_entry_t)
をひとつ生成して追加し，
<citerefentry>
<refentrytitle>gfs_acl_get_entry</refentrytitle>
</citerefentry> 関数で ACL 構造体の ACL エントリをひとつ取得し，
<citerefentry>
<refentrytitle>gfs_acl_delete_entry</refentrytitle>
</citerefentry> 関数で ACL 構造体の ACL エントリをひとつ削除します．
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_valid</refentrytitle>
</citerefentry> 関数は ACL 構造体が有効な形式かどうか確認します．
gfs_acl_check 関数ならばより詳しく確認できます．
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_calc_mask</refentrytitle>
</citerefentry> 関数は ACL 構造体の GFARM_ACL_MASK タグのエントリを計算
して，GFARM_ACL_MASK が既に存在すれば上書きし，存在しなければ作成します．
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_get_tag_type</refentrytitle>
</citerefentry> 関数は ACL エントリから ACL タグ (gfarm_acl_tag_t)
(ACL エントリの種類) を取得します．
<citerefentry>
<refentrytitle>gfs_acl_set_tag_type</refentrytitle>
</citerefentry> 関数は ACL エントリの ACL タグを差し替えます．
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_get_permset</refentrytitle>
</citerefentry> 関数は ACL エントリから ACL パーミッションセット 
(gfarm_acl_permset_t) を取り出します．
<citerefentry>
<refentrytitle>gfs_acl_set_permset</refentrytitle>
</citerefentry> 関数は ACL エントリへ ACL パーミッションセットを差し替えます．
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_add_perm</refentrytitle>
</citerefentry> 関数は ACL パーミッションセットに ACL パーミッション値 
(gfarm_acl_perm_t) を追加します．
<citerefentry>
<refentrytitle>gfs_acl_clear_perms</refentrytitle>
</citerefentry> 関数は ACL パーミッションセットからすべての 
ACL パーミッション値をクリアします．
<citerefentry>
<refentrytitle>gfs_acl_delete_perm</refentrytitle>
</citerefentry> 関数は ACL パーミッションセットから 
ACL パーミッション値をひとつ削除します．
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_get_qualifier</refentrytitle>
</citerefentry> 関数は ACL エントリから，ユーザ名またはグループ名を取得します．
GFARM_ACL_USER または GFARM_ACL_GROUP タグの ACL エントリから取得できます．
<citerefentry>
<refentrytitle>gfs_acl_set_qualifier</refentrytitle>
</citerefentry> 関数は ACL エントリに対して，指定したユーザ名またはグループ名を
差し替えます．
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_delete_def_file</refentrytitle>
</citerefentry> 関数は，ファイルやディレクトリからデフォルト ACL を削除します．
<citerefentry>
<refentrytitle>gfs_acl_get_file</refentrytitle>
</citerefentry> 関数は，ファイルやディレクトリから ACL 構造体を取得します．
<citerefentry>
<refentrytitle>gfs_acl_set_file</refentrytitle>
</citerefentry> 関数は，ファイルやディレクトリの ACL 構造体を差し替えます．
事前に gfs_acl_sort 関数でソートしてください．
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_to_text</refentrytitle>
</citerefentry> 関数は ACL 構造体を ACL 文字列形式に変換します．
gfs_acl_to_any_text 関数のほうがより高機能です．
<citerefentry>
<refentrytitle>gfs_acl_from_text</refentrytitle>
</citerefentry> 関数は ACL 文字列形式から ACL 構造体に変換します．
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_get_perm</refentrytitle>
</citerefentry> 関数は ACL パーミッションセットの中から
ひとつのパーミッションをテストします．
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_check</refentrytitle>
</citerefentry> 関数は ACL 構造体が有効な形式かどうか確認します．
また，エラーの場所とエラーの種類がわかります．
gfs_acl_valid 関数よりも高機能です．
<citerefentry>
<refentrytitle>gfs_acl_error</refentrytitle>
</citerefentry> 関数は gfs_acl_check 
関数のエラーを文字列に変換します．
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_entries</refentrytitle>
</citerefentry> 関数は ACL エントリの数を数えます．
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_equiv_mode</refentrytitle>
</citerefentry> 関数は，ACL 構造体が基本 ACL (GFARM_ACL_USER_OBJ,
GFARM_ACL_GROUP_OBJ, GFARM_ACL_OTHER) だけで構成されているかどうか確認します．
また，基本 ACL 部分から gfarm_mode_t に変換できます．
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_cmp</refentrytitle>
</citerefentry> 関数は二つの ACL 構造体を比較します．
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_from_mode</refentrytitle>
</citerefentry> 関数は gfarm_mode_t から ACL 構造体を生成します．
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_to_any_text</refentrytitle>
</citerefentry> 関数は ACL 構造体を ACL 文字列形式に変換します．
出力形式をオプションなどで変更できます．
gfs_acl_to_text 関数と比べて高機能です．
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_to_xattr_value</refentrytitle>
</citerefentry> 関数は ACL 構造体を拡張属性に格納するための 
ACL バイナリデータに変換します．
事前に gfs_acl_sort 関数でソートしてください．
<citerefentry>
<refentrytitle>gfs_acl_from_xattr_value</refentrytitle>
</citerefentry> 関数は拡張属性から取り出した ACL バイナリデータを 
ACL 構造体に変換します．
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_sort</refentrytitle>
</citerefentry> 関数は ACL 構造体を有効な形式となる順番にソートします．
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_from_text_with_default</refentrytitle>
</citerefentry> 関数は "default:" で始まる ACL エントリを持つ ACL 
文字列を解釈し，アクセス ACL 構造体とデフォルト ACL 構造体を 2 個生成します．
</para>
</refsect2>

<refsect2 id="error-handling">
<title>エラーコード</title>
<para>
ほとんどの Gfarm ライブラリの関数は gfarm_error_t 型の Gfarm エラーコー
ドを返します。
<citerefentry>
<refentrytitle>gfarm_error_string</refentrytitle>
</citerefentry> 関数は Gfarm エラーコードを表す文字列を返します。
<citerefentry>
<refentrytitle>gfarm_errno_to_error</refentrytitle>
</citerefentry> 関数は errno を Gfarm エラーコードに変換します。
<citerefentry>
<refentrytitle>gfarm_error_to_errno</refentrytitle>
</citerefentry> 関数は Gfarm エラーコードを errno に変換します。
</para>
</refsect2>

<refsect2 id="string-array-manipulation-utilities">
<title>文字列配列操作ユーティリティ</title>
<para>
文字列配列を表す gfarm_stringlist 型の変数は，
<citerefentry>
<refentrytitle>gfarm_stringlist_init</refentrytitle>
</citerefentry> 関数で初期化し，
<citerefentry>
<refentrytitle>gfarm_stringlist_add</refentrytitle>
</citerefentry> 関数で文字列を一つ追加し，
<citerefentry>
<refentrytitle>gfarm_stringlist_cat</refentrytitle>
</citerefentry> 関数で文字列を複数追加し，
<citerefentry>
<refentrytitle>gfarm_stringlist_free</refentrytitle>
</citerefentry> 関数で解放することができます．
文字列配列の各要素文字列には
<citerefentry>
<refentrytitle>gfarm_stringlist_elem</refentrytitle>
</citerefentry> 関数あるいは
GFARM_STRINGLIST_ELEM() マクロでアクセスすることができます．
また，文字列配列を構成する文字列の数は
<citerefentry>
<refentrytitle>gfarm_stringlist_length</refentrytitle>
</citerefentry> 関数で得ることができます．
</para>

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

</refsect2>

<refsect2 id="string-array-manipulation-macros">
<title>文字列配列操作ユーティリティマクロ</title>
<variablelist>

<varlistentry>
<term>GFARM_STRINGLIST_ELEM(list, i)</term>
<listitem>
<para>
gfarm_stringlist 型の <parameter moreinfo="none">list</parameter> 引数が表す文字列配列の
<parameter moreinfo="none">i</parameter> 番目の要素を
表すマクロです．このマクロは左辺値として使えます．
値として評価した場合には
<citerefentry>
<refentrytitle>gfarm_stringlist_elem</refentrytitle>
</citerefentry> 関数と同一の結果を返します．
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>GFARM_STRINGLIST_STRARRAY(list)</term>
<listitem>
<para>
gfarm_stringlist 型の <parameter moreinfo="none">list</parameter> 引数が
表す文字列配列の先頭要素へのポインタを返します．
返り値は，文字へのポインタへのポインタとなります．
</para>
</listitem>

</varlistentry>
</variablelist>

</refsect2>

</refsect1>

</refentry>
