fcntl --- fcntl および ioctl システムコール¶
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 WASI.
このモジュール内の全ての関数はファイル記述子 fd を最初の引数に取ります。 この値は sys.stdin.fileno() が返すような整数のファイル記述子でも、 sys.stdin 自体のような、純粋にファイル記述子だけを返す fileno() メソッドを提供している io.IOBase オブジェクトでもかまいません。
バージョン 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.
バージョン 3.12 で変更: On Linux >= 4.5, the fcntl module exposes the FICLONE and
FICLONERANGE constants, which allow to share some data of one file with
another file by reflinking on some filesystems (e.g., btrfs, OCFS2, and
XFS). This behavior is commonly referred to as "copy-on-write".
バージョン 3.13 で変更: On Linux >= 2.6.32, the fcntl module exposes the
F_GETOWN_EX, F_SETOWN_EX, F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP constants, which allow to direct I/O availability signals
to a specific thread, process, or process group.
On Linux >= 4.13, the fcntl module exposes the
F_GET_RW_HINT, F_SET_RW_HINT, F_GET_FILE_RW_HINT,
F_SET_FILE_RW_HINT, and RWH_WRITE_LIFE_* constants, which allow
to inform the kernel about the relative expected lifetime of writes on
a given inode or via a particular open file description.
On Linux >= 5.1 and NetBSD, the fcntl module exposes the
F_SEAL_FUTURE_WRITE constant for use with F_ADD_SEALS and
F_GET_SEALS operations.
On FreeBSD, the fcntl module exposes the F_READAHEAD, F_ISUNIONSTACK, and F_KINFO constants.
On macOS and FreeBSD, the fcntl module exposes the F_RDAHEAD
constant.
On NetBSD and AIX, the fcntl module exposes the F_CLOSEM
constant.
On NetBSD, the fcntl module exposes the F_MAXFD constant.
On macOS and NetBSD, the fcntl module exposes the F_GETNOSIGPIPE
and F_SETNOSIGPIPE constant.
このモジュールには、以下の関数が定義されています:
- 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, anOSErroris 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, anOSErrorexception 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, anOSErrorexception 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_NBis used and the lock cannot be acquired, anOSErrorwill be raised and the exception will have an errno attribute set toEACCESorEAGAIN(depending on the operating system; for portability, check for both values). On at least some systems,LOCK_EXcan 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() を呼ぶ方が良いでしょう。