:mod:`posixfile` --- ロック機構をサポートするファイル類似オブジェクト
=====================================================================

.. module:: posixfile
   :platform: Unix
   :synopsis: ロック機構をサポートするファイル類似オブジェクト。
   :deprecated:
.. moduleauthor:: Jaap Vermeulen
.. sectionauthor:: Jaap Vermeulen


.. index:: pair: POSIX; file object

.. deprecated:: 1.5
   このモジュールが提供しているよりもうまく処理ができ、可搬性も高いロック操作が
   :func:`fcntl.lockf` で提供されています。

.. index:: single: fcntl() (in module fcntl)

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

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

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


.. data:: SEEK_SET

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


.. data:: SEEK_CUR

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


.. data:: SEEK_END

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

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


.. function:: open(filename[, mode[, bufsize]])

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


.. function:: fileopen(fileobject)

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

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


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

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


.. method:: posixfile.flags([flags])

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


.. method:: posixfile.dup()

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


.. method:: posixfile.dup2(fd)

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


.. method:: posixfile.file()

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

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

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

+----------+--------------------------------------+
| 書式指定 | 意味                                 |
+==========+======================================+
| ``u``    | 指定領域のロックを解除します         |
+----------+--------------------------------------+
| ``r``    | 指定領域の読み出しロックを要求します |
+----------+--------------------------------------+
| ``w``    | 指定領域の書き込みロックを要求します |
+----------+--------------------------------------+

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

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

注釈:

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

:meth:`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('/tmp/test', 'w')
   file.lock('w|')
   ...
   file.lock('u')
   file.close()

