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, /)¶
Perform the operation cmd on file descriptor fd (file objects providing a
fileno()method are accepted as well). The values used for cmd are operating system dependent, and are available as constants in thefcntlmodule, using the same names as used in the relevant C header files. The argument arg can either be an integer value, abytesobject, or a string. The type and size of arg must match the type and size of the argument of the operation as specified in the relevant C documentation.When arg is an integer, the function returns the integer return value of the C
fcntl()call.When the argument is bytes, it represents a binary structure, for example, created by
struct.pack(). A string value is encoded to binary using the UTF-8 encoding. The binary data is copied to a buffer whose address is passed to the Cfcntl()call. The return value after a successful call is the contents of the buffer, converted to abytesobject. The length of the returned object will be the same as the length of the arg argument. This is limited to 1024 bytes.If the
fcntl()call fails, anOSErroris raised.注釈
If the type or the size of arg does not match the type or size of the argument of the operation (for example, if an integer is passed when a pointer is expected, or the information returned in the buffer by the operating system is larger than 1024 bytes), this is most likely to result in a segmentation violation or a more subtle data corruption.
引数
fd,cmd,argを指定して 監査イベントfcntl.fcntlを送出します。
- fcntl.ioctl(fd, request, arg=0, mutate_flag=True, /)¶
この関数は
fcntl()関数と同じですが、引数の扱いがより複雑であるところが異なります。The request parameter is limited to values that can fit in 32-bits or 64-bits, depending on the platform. Additional constants of interest for use as the request argument can be found in the
termiosmodule, under the same names as used in the relevant C header files.The parameter arg can be an integer, a bytes-like object, or a string. The type and size of arg must match the type and size of the argument of the operation as specified in the relevant C documentation.
If arg does not support the read-write buffer interface or the mutate_flag is false, behavior is as for the
fcntl()function.If arg supports the read-write buffer interface (like
bytearray) and mutate_flag is true (the default), then the buffer is (in effect) passed to the underlyingioctl()system call, the latter's return code is passed back to the calling Python, and the buffer's new contents reflect the action of theioctl(). This is a slight simplification, because if the supplied buffer is less than 1024 bytes long it is first copied into a static buffer 1024 bytes long which is then passed toioctl()and copied back into the supplied buffer.If the
ioctl()call fails, anOSErrorexception is raised.注釈
If the type or size of arg does not match the type or size of the operation's argument (for example, if an integer is passed when a pointer is expected, or the information returned in the buffer by the operating system is larger than 1024 bytes, or the size of the mutable bytes-like object is too small), this is most likely to result in a segmentation violation or a more subtle data corruption.
以下に例を示します:
>>> 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() を呼ぶ方が良いでしょう。