fcntl — Die Systemaufrufe fcntl und ioctl

Dieses Modul führt Datei- und E/A-Steuerungen auf Dateideskriptoren durch. Es ist eine Schnittstelle zu den Unix-Routinen fcntl() und ioctl(). Ausführliche Informationen finden Sie in den Unix-Handbuchseiten fcntl(2) und ioctl(2).

Verfügbarkeit: Unix, nicht WASI.

Alle Funktionen in diesem Modul nehmen einen Dateideskriptor fd als erstes Argument. Dies kann ein ganzzahliger Dateideskriptor sein, wie er von sys.stdin.fileno() zurückgegeben wird, oder ein io.IOBase-Objekt, wie z. B. sys.stdin selbst, das eine fileno()-Methode bereitstellt, die einen echten Dateideskriptor zurückgibt.

Geändert in Version 3.3: Operationen in diesem Modul lösten früher eine IOError aus, wo sie jetzt eine OSError auslösen.

Geändert in Version 3.8: Das Modul fcntl enthält jetzt die Konstanten F_ADD_SEALS, F_GET_SEALS und F_SEAL_* zum Versiegeln von Dateideskriptoren, die von os.memfd_create() (os.memfd_create()) zurückgegeben werden.

Geändert in Version 3.9: Unter macOS stellt das Modul fcntl die Konstante F_GETPATH bereit, die den Pfad einer Datei anhand eines Dateideskriptors abruft. Unter Linux (>=3.15) stellt das Modul fcntl die Konstanten F_OFD_GETLK, F_OFD_SETLK und F_OFD_SETLKW bereit, die beim Arbeiten mit Sperren für offene Dateibeschreibungen verwendet werden.

Geändert in Version 3.10: Unter Linux (>= 2.6.11) stellt das Modul fcntl die Konstanten F_GETPIPE_SZ und F_SETPIPE_SZ bereit, mit denen die Größe einer Pipe überprüft bzw. geändert werden kann.

Geändert in Version 3.11: Unter FreeBSD stellt das Modul fcntl die Konstanten F_DUP2FD und F_DUP2FD_CLOEXEC bereit, mit denen ein Dateideskriptor dupliziert werden kann, wobei letztere zusätzlich das FD_CLOEXEC-Flag setzen.

Geändert in Version 3.12: Unter Linux (>= 4.5) stellt das Modul fcntl die Konstanten FICLONE und FICLONERANGE bereit, die es ermöglichen, Teile von Daten einer Datei mit einer anderen Datei zu teilen, indem sie auf bestimmten Dateisystemen (z. B. btrfs, OCFS2 und XFS) reflinks (kopieren bei Schreiben) erstellen. Dieses Verhalten wird üblicherweise als „Copy-on-Write“ bezeichnet.

Geändert in Version 3.13: Unter Linux (>= 2.6.32) stellt das Modul fcntl die Konstanten F_GETOWN_EX, F_SETOWN_EX, F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP bereit, mit denen E/A-Verfügbarkeitssignale an einen bestimmten Thread, Prozess oder eine Prozessgruppe geleitet werden können. Unter Linux (>= 4.13) stellt das Modul fcntl die Konstanten F_GET_RW_HINT, F_SET_RW_HINT, F_GET_FILE_RW_HINT, F_SET_FILE_RW_HINT und RWH_WRITE_LIFE_* bereit, mit denen der Kernel über die relative erwartete Lebensdauer von Schreibvorgängen auf einem bestimmten Inode oder über eine bestimmte offene Dateibeschreibung informiert werden kann. Unter Linux (>= 5.1) und NetBSD stellt das Modul fcntl die Konstante F_SEAL_FUTURE_WRITE für die Verwendung mit den Operationen F_ADD_SEALS und F_GET_SEALS bereit. Unter FreeBSD stellt das Modul fcntl die Konstanten F_READAHEAD, F_ISUNIONSTACK und F_KINFO bereit. Unter macOS und FreeBSD stellt das Modul fcntl die Konstante F_RDAHEAD bereit. Unter NetBSD und AIX stellt das Modul fcntl die Konstante F_CLOSEM bereit. Unter NetBSD stellt das Modul fcntl die Konstante F_MAXFD bereit. Unter macOS und NetBSD stellt das Modul fcntl die Konstanten F_GETNOSIGPIPE und F_SETNOSIGPIPE bereit.

Geändert in Version 3.14: Unter Linux (>= 6.1) stellt das Modul fcntl die Konstante F_DUPFD_QUERY bereit, um einen Dateideskriptor abzufragen, der auf dieselbe Datei zeigt.

Das Modul definiert die folgenden Funktionen

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

Führt die Operation cmd auf dem Dateideskriptor fd aus (Datei-Objekte, die eine fileno()-Methode bereitstellen, werden ebenfalls akzeptiert). Die für cmd verwendeten Werte sind betriebssystemabhängig und als Konstanten im Modul fcntl verfügbar, mit denselben Namen wie in den entsprechenden C-Headerdateien. Das Argument arg kann entweder ein ganzzahliger Wert, ein bytes-ähnliches Objekt oder ein String sein. Der Typ und die Größe von arg müssen mit dem Typ und der Größe des Arguments der Operation übereinstimmen, wie in der entsprechenden C-Dokumentation angegeben.

Wenn arg eine Ganzzahl ist, gibt die Funktion den ganzzahligen Rückgabewert des C-Aufrufs fcntl() zurück.

Wenn das Argument ein bytes-ähnliches Objekt ist, repräsentiert es eine binäre Struktur, die z. B. von struct.pack() erstellt wurde. Ein Stringwert wird mit der UTF-8-Kodierung in Binärdaten umgewandelt. Die Binärdaten werden in einen Puffer kopiert, dessen Adresse an den C-Aufruf fcntl() übergeben wird. Der Rückgabewert nach einem erfolgreichen Aufruf sind die Inhalte des Puffers, konvertiert in ein bytes-Objekt. Die Länge des zurückgegebenen Objekts entspricht der Länge des Arguments arg. Dies ist auf 1024 Bytes begrenzt.

Wenn der Aufruf fcntl() fehlschlägt, wird eine OSError ausgelöst.

Hinweis

Wenn Typ oder Größe von arg nicht mit Typ oder Größe des Arguments der Operation übereinstimmen (z. B. wenn eine Ganzzahl übergeben wird, wenn ein Zeiger erwartet wird, oder die vom Betriebssystem im Puffer zurückgegebenen Informationen größer als 1024 Bytes sind), führt dies höchstwahrscheinlich zu einer Segmentierungsverletzung oder einer subtileren Datenbeschädigung.

Löst ein Auditing-Event fcntl.fcntl mit den Argumenten fd, cmd, arg aus.

Geändert in Version 3.14: Unterstützung für beliebige bytes-ähnliche Objekte, nicht nur bytes.

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

Diese Funktion ist identisch mit der Funktion fcntl(), mit dem Unterschied, dass die Argumentbehandlung noch komplizierter ist.

Der Parameter request ist auf Werte beschränkt, die je nach Plattform in 32-Bit oder 64-Bit passen. Zusätzliche interessante Konstanten für die Verwendung als request-Argument finden Sie im Modul termios unter denselben Namen wie in den entsprechenden C-Headerdateien.

Der Parameter arg kann eine Ganzzahl, ein bytes-ähnliches Objekt oder ein String sein. Der Typ und die Größe von arg müssen mit dem Typ und der Größe des Arguments der Operation übereinstimmen, wie in der entsprechenden C-Dokumentation angegeben.

Wenn arg die Read-Write-Buffer-Schnittstelle nicht unterstützt oder mutate_flag falsch ist, ist das Verhalten dasselbe wie bei der Funktion fcntl().

Wenn arg die Read-Write-Buffer-Schnittstelle unterstützt (wie bytearray) und mutate_flag wahr ist (Standardwert), dann wird der Puffer (effektiv) an den zugrunde liegenden ioctl()-Systemaufruf übergeben, dessen Rückgabecode an das aufrufende Python zurückgegeben wird, und der neue Inhalt des Puffers spiegelt die Aktion von ioctl() wider. Dies ist eine leichte Vereinfachung, denn wenn der bereitgestellte Puffer kleiner als 1024 Bytes ist, wird er zuerst in einen statischen Puffer von 1024 Bytes kopiert, der dann an ioctl() übergeben und zurück in den bereitgestellten Puffer kopiert wird.

Wenn der ioctl()-Aufruf fehlschlägt, wird eine OSError-Ausnahme ausgelöst.

Hinweis

Wenn Typ oder Größe von arg nicht mit Typ oder Größe des Arguments der Operation übereinstimmen (z. B. wenn eine Ganzzahl übergeben wird, wenn ein Zeiger erwartet wird, oder die vom Betriebssystem im Puffer zurückgegebenen Informationen größer als 1024 Bytes sind, oder die Größe des veränderbaren bytes-ähnlichen Objekts zu klein ist), führt dies höchstwahrscheinlich zu einer Segmentierungsverletzung oder einer subtileren Datenbeschädigung.

Ein Beispiel

>>> 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])

Löst ein Auditing-Event fcntl.ioctl mit den Argumenten fd, request, arg aus.

Geändert in Version 3.14: Der GIL wird immer während eines Systemaufrufs freigegeben. Systemaufrufe, die mit EINTR fehlschlagen, werden automatisch wiederholt.

fcntl.flock(fd, operation, /)

Führt die Sperroperation operation auf dem Dateideskriptor fd aus (Datei-Objekte, die eine fileno()-Methode bereitstellen, werden ebenfalls akzeptiert). Details finden Sie in der Unix-Handbuchseite flock(2). (Auf einigen Systemen wird diese Funktion mithilfe von fcntl() emuliert.)

Wenn der Aufruf flock() fehlschlägt, wird eine OSError-Ausnahme ausgelöst.

Löst ein Auditing-Event fcntl.flock mit den Argumenten fd, operation aus.

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

Dies ist im Wesentlichen ein Wrapper um die Sperraufrufe von fcntl(). fd ist der Dateideskriptor (Datei-Objekte, die eine fileno()-Methode bereitstellen, werden ebenfalls akzeptiert) der zu sperrenden oder zu entsperrenden Datei, und cmd ist einer der folgenden Werte

fcntl.LOCK_UN

Hebt eine bestehende Sperre auf.

fcntl.LOCK_SH

Erwirbt eine Shared-Sperre.

fcntl.LOCK_EX

Erwirbt eine exklusive Sperre.

fcntl.LOCK_NB

Bitweises ODER mit einem der anderen drei LOCK_*-Konstanten, um die Anforderung nicht-blockierend zu machen.

Wenn LOCK_NB verwendet wird und die Sperre nicht erworben werden kann, wird eine OSError ausgelöst, und die Ausnahme hat ein Attribut errno, das auf EACCES oder EAGAIN gesetzt ist (abhängig vom Betriebssystem; zur Portabilität prüfen Sie beide Werte). Auf mindestens einigen Systemen kann LOCK_EX nur verwendet werden, wenn der Dateideskriptor eine zum Schreiben geöffnete Datei referenziert.

len ist die Anzahl der zu sperrenden Bytes, start ist der Byte-Offset, an dem die Sperre beginnt, relativ zu whence, und whence ist wie bei io.IOBase.seek(), insbesondere

Der Standardwert für start ist 0, was bedeutet, dass die Sperre am Anfang der Datei beginnt. Der Standardwert für len ist 0, was bedeutet, dass bis zum Ende der Datei gesperrt wird. Der Standardwert für whence ist ebenfalls 0.

Löst ein Auditing-Event fcntl.lockf mit den Argumenten fd, cmd, len, start, whence aus.

Beispiele (alle auf einem SVR4-konformen System)

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)

Beachten Sie, dass im ersten Beispiel die Rückgabewertvariable rv einen ganzzahligen Wert enthält; im zweiten Beispiel enthält sie ein bytes-Objekt. Das Layout der Variablen lockdata ist systemabhängig – daher kann die Verwendung des Aufrufs flock() besser sein.

Siehe auch

Modul os

Wenn die Sperrflags O_SHLOCK und O_EXLOCK im Modul os vorhanden sind (nur unter BSD), bietet die Funktion os.open() (os.open()) eine Alternative zu den Funktionen lockf() und flock().