36.12. "posixfile" --- ロック機構をサポートするファイル類似オブジェクト
***********************************************************************

バージョン 1.5 で非推奨: このモジュールが提供しているよりもうまく処理
ができ、可搬性も高いロック操作が "fcntl.lockf()" で提供されています。

このモジュールでは、組み込みのファイルオブジェクトの上にいくつかの追加
機能を実装しています。特に、このオブジェクトはファイルのロック機構、フ
ァイルフラグへの操作、およびファイルオブジェクトを複製するための簡単な
インタフェースを実装しています。このモジュールは新たなファイルオブジェ
クト posixfile を定義しています。このオブジェクトは全ての標準ファイル
オブジェクトのメソッドに加え、下記に述べるメソッドを持っています。この
モジュールはファイルのロック機構に "fcntl.fcntl()" を用いるため、ある
種の Unix でしか動作しません。

posixfile オブジェクトをインスタンス化するには、 "posixfile.open()" 関
数を使います。生成されるオブジェクトは標準ファイルオブジェクトとだいた
い同じルック&フィールです。

"posixfile" モジュールでは、以下の定数を定義しています:

posixfile.SEEK_SET

   オフセットをファイルの先頭から計算します。

posixfile.SEEK_CUR

   オフセットを現在のファイル位置から計算します。

posixfile.SEEK_END

   オフセットをファイルの末尾から計算します。

"posixfile" モジュールでは以下の関数を定義しています:

posixfile.open(filename[, mode[, bufsize]])

   指定したファイル名とモードで新しい posixfile オブジェクトを作成しま
   す。 *filename* 、 *mode* および *bufsize* 引数は組み込みの
   "open()" 関数と同じように解釈されます。

posixfile.fileopen(fileobject)

   指定した標準ファイルオブジェクトで新しい posixfile オブジェクトを作
   成します。作成されるオブジェクトは元のファイルオブジェクトと同じフ
   ァイル名およびモードを持っています。

posixfile オブジェクトでは以下の追加メソッドを定義しています:

posixfile.lock(fmt[, len[, start[, whence]]])

   ファイルオブジェクトが参照しているファイルの指定部分にロックをかけ
   ます。指定の書式は下のテーブルで説明されています。 *len* 引数にはロ
   ックする部分の長さを指定します。標準の値は "0" です。 *start* には
   ロックする部分の先頭オフセットを指定し、その標準値は "0" です。
   *whence* 引数はオフセットをどこからの相対位置にするかを指定します。
   この値は定数 "SEEK_SET" 、 "SEEK_CUR" 、または "SEEK_END" のいずれ
   かになります。標準の値は "SEEK_SET" です。引数についてのより詳しい
   情報はシステムの *fcntl(2)* マニュアルページを参照してください。

posixfile.flags([flags])

   ファイルオブジェクトが参照しているファイルに指定したフラグを設定し
   ます。新しいフラグは特に指定しない限り以前のフラグと OR されます。
   指定書式は下のテーブルで説明されています。 *flags* 引数なしの場合、
   現在のフラグを示す文字列が返されます("?" 修飾子と同じです) 。フラグ
   についてのより詳しい情報はシステムの *fcntl(2)* マニュアルページを
   参照してください。

posixfile.dup()

   ファイルオブジェクトと、背後のファイルポインタおよびファイル記述子
   を複製します。返されるオブジェクトは新たに開かれたファイルのように
   振舞います。

posixfile.dup2(fd)

   ファイルオブジェクトと、背後のファイルポインタおよびファイル記述子
   を複製します。新たなオブジェクトは指定したファイル記述子を持ちます
   。それ以外の点では、返されるオブジェクトは新たに開かれたファイルの
   ように振舞います。

posixfile.file()

   posixfile オブジェクトが参照している標準ファイルオブジェクトを返し
   ます。この関数は標準ファイルオブジェクトを使うよう強制している関数
   を使う場合に時々必要になります。

全てのメソッドで、要求された操作が失敗した場合には "IOError" が送出さ
れます。

"lock()" の書式指定文字には以下のような意味があります:

+----------+-------------------------------------------------+
| フォーマ | 意味                                            |
| ット     |                                                 |
+==========+=================================================+
| "u"      | 指定領域のロックを解除します                    |
+----------+-------------------------------------------------+
| "r"      | 指定領域の読み出しロックを要求します            |
+----------+-------------------------------------------------+
| "w"      | 指定領域の書き込みロックを要求します            |
+----------+-------------------------------------------------+

これに加え、以下の修飾子を書式に追加できます:

+------------+----------------------------------+---------+
| 修飾子     | 意味                             | 注釈    |
+============+==================================+=========+
| "|"        | ロック操作が許可されるまで待ちま |         |
|            | す                               |         |
+------------+----------------------------------+---------+
| "?"        | 要求されたロックと衝突している第 | (1)     |
|            | 一のロックを返すか、衝突がない場 |         |
|            | 合には "None" を返します。       |         |
+------------+----------------------------------+---------+

注釈:

1. 返されるロックは "(mode, len, start, whence, pid)" の形式で、
   *mode* はロックのタイプを表す文字 ('r' または 'w') です。この修飾子
   はロック要求の許可を行わせません; すなわち、問い合わせの目的にしか
   使えません。

"flags()" の書式指定文字には以下のような意味があります:

+----------+-------------------------------------------------+
| フォーマ | 意味                                            |
| ット     |                                                 |
+==========+=================================================+
| "a"      | 追記のみ (append only) フラグ                   |
+----------+-------------------------------------------------+
| "c"      | 実行時クローズ (close on exec) フラグ           |
+----------+-------------------------------------------------+
| "n"      | 無遅延 (no delay) フラグ (非ブロック (non-      |
|          | blocking) フラグとも呼ばれま す)                |
+----------+-------------------------------------------------+
| "s"      | 同期 (synchronization) フラグ                   |
+----------+-------------------------------------------------+

これに加え、以下の修飾子を書式に追加できます:

+------------+-----------------------------------+---------+
| 修飾子     | 意味                              | 注釈    |
+============+===================================+=========+
| "!"        | 指定したフラグを通常の ‘オン’ に  | (1)     |
|            | せず ‘オフ’ にします              |         |
+------------+-----------------------------------+---------+
| "="        | フラグを標準の ‘OR’ 操作ではなく  | (1)     |
|            | 置換します。                      |         |
+------------+-----------------------------------+---------+
| "?"        | 設定されているフラグを表現する文  | (2)     |
|            | 字からなる文字列を返します。      |         |
+------------+-----------------------------------+---------+

注釈:

1. "!" および "=" 修飾子は互いに排他の関係にあります。

2. この文字列が表すフラグは同じ呼び出しによってフラグが置き換えられ
   た 後のものです。

例:

   import posixfile

   file = posixfile.open('testfile', 'w')
   file.lock('w|')
   ...
   file.lock('u')
   file.close()
