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 WASI.
Усі функції в цьому модулі приймають файловий дескриптор fd як перший аргумент. Це може бути цілочисельний файловий дескриптор, наприклад, повернутий sys.stdin.fileno(), або об’єкт io.IOBase, як-от сам sys.stdin, який надає fileno(), який повертає справжній дескриптор файлу.
Змінено в версії 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.
Змінено в версії 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.
Викликає подію аудиту
fcntl.fcntlз аргументамиfd,cmd,arg.
- 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])
Викликає подію аудиту
fcntl.ioctlз аргументамиfd,request,arg.
- fcntl.flock(fd, operation, /)¶
Виконайте операцію блокування operation для файлового дескриптора fd (також приймаються файлові об’єкти, що містять метод
fileno()). Перегляньте посібник Unix flock(2) для отримання детальної інформації. (У деяких системах ця функція емулюється за допомогоюfcntl().)If the
flock()call fails, anOSErrorexception is raised.Викликає подію аудиту
fcntl.flockз аргументамиfd,operation.
- 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)
Типовим значенням для початку є 0, що означає початок на початку файлу. Типовим значенням для len є 0, що означає блокування до кінця файлу. За замовчуванням для whence також дорівнює 0.
Викликає подію аудиту
fcntl.lockfз аргументамиfd,cmd,len,start,whence.
Приклади (усі в системі, сумісній з 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() може бути кращим.