"fcntl" --- The "fcntl" and "ioctl" system calls
************************************************

======================================================================

This module performs file and I/O control on file descriptors. It is
an interface to the "fcntl()" and "ioctl()" Unix routines. See the
*fcntl(2)* and *ioctl(2)* Unix manual pages for full details.

Availability: Unix, not Emscripten, not WASI.

このモジュール内の全ての関数はファイル記述子 *fd* を最初の引数に取りま
す。 この値は "sys.stdin.fileno()" が返すような整数のファイル記述子で
も、 "sys.stdin" 自体のような、純粋にファイル記述子だけを返す
"fileno()" メソッドを提供している "io.IOBase"  オブジェクトでもかまい
ません。

バージョン 3.3 で変更: 以前は "IOError" を送出していたこのモジュールの
操作が、 "OSError" を送出するようになりました。

バージョン 3.8 で変更: The fcntl module now contains "F_ADD_SEALS",
"F_GET_SEALS", and "F_SEAL_*" constants for sealing of
"os.memfd_create()" file descriptors.

バージョン 3.9 で変更: On macOS, the fcntl module exposes the
"F_GETPATH" constant, which obtains the path of a file from a file
descriptor. On Linux(>=3.15), the fcntl module exposes the
"F_OFD_GETLK", "F_OFD_SETLK" and "F_OFD_SETLKW" constants, which are
used when working with open file description locks.

バージョン 3.10 で変更: On Linux >= 2.6.11, the fcntl module exposes
the "F_GETPIPE_SZ" and "F_SETPIPE_SZ" constants, which allow to check
and modify a pipe's size respectively.

バージョン 3.11 で変更: On FreeBSD, the fcntl module exposes the
"F_DUP2FD" and "F_DUP2FD_CLOEXEC" constants, which allow to duplicate
a file descriptor, the latter setting "FD_CLOEXEC" flag in addition.

このモジュールには、以下の関数が定義されています:

fcntl.fcntl(fd, cmd, arg=0)

   操作 *cmd* をファイル記述子 *fd* (または "fileno()" メソッドを提供
   しているファイルオブジェクト) に対して実行します。 *cmd* として用い
   られる値はオペレーティングシステム依存で、 "fcntl" モジュール内に関
   連する C ヘッダファイルと同じ名前が使われている定数の形で利用出来ま
   す。引数 *arg* は整数値か "bytes" オブジェクトをとります。引数が整
   数値の場合、この関数の戻り値は C 言語の "fcntl()" を呼び出した際の
   整数の戻り値になります。引数が bytes の場合には、 "struct.pack()"
   で作られるようなバイナリの構造体を表します。バイナリデータはバッフ
   ァにコピーされ、そのアドレスが C 言語の "fcntl()" 呼び出しに渡され
   ます。 呼び出しが成功した後に戻される値はバッファの内容で、 "bytes"
   オブジェクトに変換されています。 返されるオブジェクトは *arg* 引数
   と同じ長さになります。 この値は 1024 バイトに制限されています。 オ
   ペレーティングシステムからバッファに返される情報の長さが 1024 バイ
   トよりも大きい場合、大抵はセグメンテーション違反となるか、より不可
   思議なデータの破損を引き起こします。

   If the "fcntl()" call fails, an "OSError" is raised.

   引数 "fd", "cmd", "arg" を指定して 監査イベント "fcntl.fcntl" を送
   出します。

fcntl.ioctl(fd, request, arg=0, mutate_flag=True)

   この関数は "fcntl()" 関数と同じですが、引数の扱いがより複雑であると
   ころが異なります。

   パラメータ *request* は32ビットに収まる値に制限されます。 *request*
   引数として使うのに関係のある追加の定数は "termios" モジュールにあり
   、関連する C ヘッダファイルで使われているのと同じ名前が付けられてい
   ます。

   パラメタ *arg* は、整数、 ("bytes" のような) 読み出し専用のバッファ
   インターフェースをサポートするオブジェクト、("bytearray" のような)
   読み書きバッファインターフェースをサポートするオブジェクトのどれか
   です。

   最後の型のオブジェクトを除き、動作は "fcntl()" 関数と同じです。

   可変なバッファが渡された場合、動作は *mutate_flag* 引数の値で決定さ
   れます。

   この値が偽の場合、バッファの可変性は無視され、読み出し専用バッファ
   の場合と同じ動作になりますが、上で述べた 1024 バイトの制限は回避さ
   れます -- 従って、オペレーティングシステムが希望するバッファ長まで
   であれば正しく動作します。

   *mutate_flag* が真 (デフォルト) の場合、バッファは (実際には) 根底
   にある "ioctl()" システムコールに渡され、後者の戻り値が呼び出し側の
   Python に引き渡され、バッファの新たな内容は  "ioctl()" の動作を反映
   します。この説明はやや単純化されています。というのは、与えられたバ
   ッファが 1024 バイト長よりも短い場合、バッファはまず 1024 バイト長
   の静的なバッファにコピーされてから "ioctl()" に渡され、その後引数で
   与えたバッファに戻しコピーされるからです。

   If the "ioctl()" call fails, an "OSError" exception is raised.

   以下に例を示します:

      >>> import array, fcntl, struct, termios, os
      >>> os.getpgrp()
      13341
      >>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, "  "))[0]
      13341
      >>> buf = array.array('h', [0])
      >>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1)
      0
      >>> buf
      array('h', [13341])

   引数 "fd", "request", "arg" を指定して 監査イベント "fcntl.ioctl"
   を送出します。

fcntl.flock(fd, operation)

   ファイル記述子 *fd* ("fileno()" メソッドを提供しているファイルオブ
   ジェクトも含む) に対してロック操作 *operation* を実行します。 詳細
   は Unix マニュアルの *flock(2)* を参照してください (システムによっ
   ては、この関数は "fcntl()" を使ってエミュレーションされています)。

   If the "flock()" call fails, an "OSError" exception is raised.

   引数 "fd", "operation" を指定して 監査イベント "fcntl.flock" を送出
   します。

fcntl.lockf(fd, cmd, len=0, start=0, whence=0)

   本質的に "fcntl()" によるロッキングの呼び出しをラップしたものです。
   *fd* はロックまたはアンロックするファイルのファイル記述子
   ("fileno()" メソッドを提供するファイルオブジェクトも受け付けられま
   す) で、 *cmd* は以下の値のうちいずれかになります:

   fcntl.LOCK_UN

      Release an existing lock.

   fcntl.LOCK_SH

      Acquire a shared lock.

   fcntl.LOCK_EX

      Acquire an exclusive lock.

   fcntl.LOCK_NB

      Bitwise OR with any of the other three "LOCK_*" constants to
      make the request non-blocking.

   If "LOCK_NB" is used and the lock cannot be acquired, an "OSError"
   will be raised and the exception will have an *errno* attribute set
   to "EACCES" or "EAGAIN" (depending on the operating system; for
   portability, check for both values).  On at least some systems,
   "LOCK_EX" can only be used if the file descriptor refers to a file
   opened for writing.

   *len* はロックを行いたいバイト数、 *start* はロック領域先頭の
   *whence* からの相対的なバイトオフセット、 *whence* は
   "io.IOBase.seek()" と同じで、具体的には:

   * "0" -- relative to the start of the file ("os.SEEK_SET")

   * "1" -- relative to the current buffer position ("os.SEEK_CUR")

   * "2" -- relative to the end of the file ("os.SEEK_END")

   *start* の標準の値は 0 で、ファイルの先頭から開始することを意味しま
   す。*len* の標準の値は 0 で、ファイルの終了までロックすることを表し
   ます。*whence* の標準の値も 0 です。

   引数 "fd", "cmd", "len", "start", "whence" を指定して 監査イベント
   "fcntl.lockf" を送出します。

以下に (全ての SVR4 互換システムでの) 例を示します:

   import struct, fcntl, os

   f = open(...)
   rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY)

   lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0)
   rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata)

最初の例では、戻り値 *rv* は整数値を保持しています; 二つ目の例では
"bytes" オブジェクトを保持しています。 *lockdata* 変数の構造体レイアウ
トはシステム依存です --- 従って "flock()" を呼ぶ方が良いでしょう。

参考:

  "os" モジュール
     If the locking flags "O_SHLOCK" and "O_EXLOCK" are present in the
     "os" module (on BSD only), the "os.open()" function provides an
     alternative to the "lockf()" and "flock()" functions.
