Betriebssystem-Dienstprogramme

PyObject *PyOS_FSPath(PyObject *path)

Rückgabewert: Neue Referenz. Teil der Stable ABI seit Version 3.6.

Gibt die Dateisystemrepräsentation für path zurück. Wenn das Objekt ein str- oder bytes-Objekt ist, wird eine neue strong reference zurückgegeben. Wenn das Objekt die os.PathLike-Schnittstelle implementiert, wird __fspath__() zurückgegeben, solange es ein str- oder bytes-Objekt ist. Andernfalls wird TypeError ausgelöst und NULL zurückgegeben.

Hinzugefügt in Version 3.6.

int Py_FdIsInteractive(FILE *fp, const char *filename)

Gibt wahr (ungleich Null) zurück, wenn die Standard-I/O-Datei fp mit dem Namen filename als interaktiv angesehen wird. Dies ist der Fall für Dateien, für die isatty(fileno(fp)) wahr ist. Wenn PyConfig.interactive ungleich Null ist, gibt diese Funktion auch wahr zurück, wenn der filename-Zeiger NULL ist oder wenn der Name mit einem der Strings '<stdin>' oder '???' übereinstimmt.

Diese Funktion darf nicht aufgerufen werden, bevor Python initialisiert wurde.

void PyOS_BeforeFork()

Teil der Stable ABI auf Plattformen mit fork() seit Version 3.7.

Funktion zur Vorbereitung interner Zustände vor dem Forken eines Prozesses. Diese sollte vor dem Aufruf von fork() oder einer ähnlichen Funktion, die den aktuellen Prozess klont, aufgerufen werden. Nur verfügbar auf Systemen, auf denen fork() definiert ist.

Warnung

Der C fork()-Aufruf sollte nur vom „main“-Thread (des „main“-Interpreters) aus erfolgen. Das Gleiche gilt für PyOS_BeforeFork().

Hinzugefügt in Version 3.7.

void PyOS_AfterFork_Parent()

Teil der Stable ABI auf Plattformen mit fork() seit Version 3.7.

Funktion zur Aktualisierung interner Zustände nach dem Forken eines Prozesses. Diese sollte im Elternprozess nach dem Aufruf von fork() oder einer ähnlichen Funktion, die den aktuellen Prozess klont, aufgerufen werden, unabhängig davon, ob das Klonen des Prozesses erfolgreich war. Nur verfügbar auf Systemen, auf denen fork() definiert ist.

Warnung

Der C fork()-Aufruf sollte nur vom „main“-Thread (des „main“-Interpreters) aus erfolgen. Das Gleiche gilt für PyOS_AfterFork_Parent().

Hinzugefügt in Version 3.7.

void PyOS_AfterFork_Child()

Teil der Stable ABI auf Plattformen mit fork() seit Version 3.7.

Funktion zur Aktualisierung des internen Interpreterzustands nach dem Forken eines Prozesses. Diese muss im Kindprozess nach dem Aufruf von fork() oder einer ähnlichen Funktion, die den aktuellen Prozess klont, aufgerufen werden, wenn die Möglichkeit besteht, dass der Prozess zurück in den Python-Interpreter aufruft. Nur verfügbar auf Systemen, auf denen fork() definiert ist.

Warnung

Der C fork()-Aufruf sollte nur vom „main“-Thread (des „main“-Interpreters) aus erfolgen. Das Gleiche gilt für PyOS_AfterFork_Child().

Hinzugefügt in Version 3.7.

Siehe auch

os.register_at_fork() erlaubt die Registrierung benutzerdefinierter Python-Funktionen, die von PyOS_BeforeFork(), PyOS_AfterFork_Parent() und PyOS_AfterFork_Child() aufgerufen werden.

void PyOS_AfterFork()

Teil der Stable ABI auf Plattformen mit fork().

Funktion zur Aktualisierung einiger interner Zustände nach dem Forken eines Prozesses; diese sollte im neuen Prozess aufgerufen werden, wenn der Python-Interpreter weiterhin verwendet werden soll. Wenn eine neue ausführbare Datei in den neuen Prozess geladen wird, muss diese Funktion nicht aufgerufen werden.

Seit Version 3.7 veraltet: Diese Funktion wird durch PyOS_AfterFork_Child() abgelöst.

int PyOS_CheckStack()

Teil der Stable ABI auf Plattformen mit USE_STACKCHECK seit Version 3.7.

Gibt wahr zurück, wenn der Interpreter keinen Stack-Speicher mehr hat. Dies ist eine zuverlässige Prüfung, ist aber nur verfügbar, wenn USE_STACKCHECK definiert ist (derzeit auf bestimmten Versionen von Windows mit dem Microsoft Visual C++ Compiler). USE_STACKCHECK wird automatisch definiert; Sie sollten die Definition niemals in Ihrem eigenen Code ändern.

typedef void (*PyOS_sighandler_t)(int)

Teil der Stable ABI.

PyOS_sighandler_t PyOS_getsig(int i)

Teil der Stable ABI.

Gibt den aktuellen Signal-Handler für Signal i zurück. Dies ist ein dünner Wrapper um entweder sigaction() oder signal(). Rufen Sie diese Funktionen nicht direkt auf!

PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)

Teil der Stable ABI.

Setzt den Signal-Handler für Signal i auf h; gibt den alten Signal-Handler zurück. Dies ist ein dünner Wrapper um entweder sigaction() oder signal(). Rufen Sie diese Funktionen nicht direkt auf!

wchar_t *Py_DecodeLocale(const char *arg, size_t *size)

Teil der Stable ABI seit Version 3.7.

Warnung

Diese Funktion sollte nicht direkt aufgerufen werden: Verwenden Sie die PyConfig API mit der Funktion PyConfig_SetBytesString(), die sicherstellt, dass Python vorinitialisiert wird.

Diese Funktion darf nicht aufgerufen werden, bevor Python vorinitialisiert wurde und die LC_CTYPE-Locale ordnungsgemäß konfiguriert ist: siehe die Funktion Py_PreInitialize().

Dekodiert eine Byte-Zeichenkette aus der Dateisystemkodierung und dem Fehlerbehandlungsmechanismus. Wenn der Fehlerbehandlungsmechanismus der Surrogateescape-Fehlerbehandlungsmechanismus ist, werden nicht dekodierbare Bytes als Zeichen im Bereich U+DC80..U+DCFF dekodiert; und wenn eine Byte-Sequenz als Surrogatzeichen dekodiert werden kann, werden die Bytes stattdessen mit dem Surrogateescape-Fehlerbehandlungsmechanismus maskiert, anstatt sie zu dekodieren.

Gibt einen Zeiger auf eine neu zugeordnete Wide-Zeichenkette zurück, verwenden Sie PyMem_RawFree(), um den Speicher freizugeben. Wenn size nicht NULL ist, schreiben Sie die Anzahl der Wide-Zeichen, ausschließlich des Nullzeichens, in *size

Gibt NULL bei Dekodierungsfehlern oder Speicherzuordnungsfehlern zurück. Wenn size nicht NULL ist, wird *size bei Speicherfehlern auf (size_t)-1 und bei Dekodierungsfehlern auf (size_t)-2 gesetzt.

Die Dateisystemkodierung und der Fehlerbehandlungsmechanismus werden durch PyConfig_Read() ausgewählt: siehe die Mitglieder filesystem_encoding und filesystem_errors von PyConfig.

Dekodierungsfehler sollten niemals auftreten, es sei denn, es liegt ein Fehler in der C-Bibliothek vor.

Verwenden Sie die Funktion Py_EncodeLocale(), um die Zeichenkette zurück in eine Byte-Zeichenkette zu kodieren.

Siehe auch

Die Funktionen PyUnicode_DecodeFSDefaultAndSize() und PyUnicode_DecodeLocaleAndSize().

Hinzugefügt in Version 3.5.

Geändert in Version 3.7: Die Funktion verwendet nun die UTF-8-Kodierung im Python UTF-8-Modus.

Geändert in Version 3.8: Die Funktion verwendet nun unter Windows die UTF-8-Kodierung, wenn PyPreConfig.legacy_windows_fs_encoding Null ist;

char *Py_EncodeLocale(const wchar_t *text, size_t *error_pos)

Teil der Stable ABI seit Version 3.7.

Kodiert eine Wide-Zeichenkette in die Dateisystemkodierung und den Fehlerbehandlungsmechanismus. Wenn der Fehlerbehandlungsmechanismus der Surrogateescape-Fehlerbehandlungsmechanismus ist, werden Surrogatzeichen im Bereich U+DC80..U+DCFF in die Bytes 0x80..0xFF konvertiert.

Gibt einen Zeiger auf eine neu zugeordnete Byte-Zeichenkette zurück, verwenden Sie PyMem_Free(), um den Speicher freizugeben. Gibt NULL bei Kodierungsfehlern oder Speicherzuordnungsfehlern zurück.

Wenn error_pos nicht NULL ist, wird *error_pos bei Erfolg auf (size_t)-1 oder bei einem Kodierungsfehler auf den Index des ungültigen Zeichens gesetzt.

Die Dateisystemkodierung und der Fehlerbehandlungsmechanismus werden durch PyConfig_Read() ausgewählt: siehe die Mitglieder filesystem_encoding und filesystem_errors von PyConfig.

Verwenden Sie die Funktion Py_DecodeLocale(), um die Byte-Zeichenkette zurück in eine Wide-Zeichenkette zu dekodieren.

Warnung

Diese Funktion darf nicht aufgerufen werden, bevor Python vorinitialisiert wurde und die LC_CTYPE-Locale ordnungsgemäß konfiguriert ist: siehe die Funktion Py_PreInitialize().

Siehe auch

Die Funktionen PyUnicode_EncodeFSDefault() und PyUnicode_EncodeLocale().

Hinzugefügt in Version 3.5.

Geändert in Version 3.7: Die Funktion verwendet nun die UTF-8-Kodierung im Python UTF-8-Modus.

Geändert in Version 3.8: Die Funktion verwendet nun unter Windows die UTF-8-Kodierung, wenn PyPreConfig.legacy_windows_fs_encoding Null ist.

FILE *Py_fopen(PyObject *path, const char *mode)

Ähnlich wie fopen(), aber path ist ein Python-Objekt und bei einem Fehler wird eine Ausnahme gesetzt.

path muss ein str-Objekt, ein bytes-Objekt oder ein Pfad-ähnliches Objekt sein.

Bei Erfolg wird der neue Dateizeiger zurückgegeben. Bei einem Fehler wird eine Ausnahme gesetzt und NULL zurückgegeben.

Die Datei muss mit Py_fclose() geschlossen werden, anstatt direkt fclose() aufzurufen.

Der Dateideskriptor wird als nicht erblich erstellt (PEP 446).

Der Aufrufer muss einen Thread-Status angehängt haben.

Hinzugefügt in Version 3.14.

int Py_fclose(FILE *file)

Schließt eine Datei, die mit Py_fopen() geöffnet wurde.

Bei Erfolg wird 0 zurückgegeben. Bei einem Fehler wird EOF zurückgegeben und errno gesetzt, um den Fehler anzuzeigen. In beiden Fällen führt jeder weitere Zugriff (einschließlich eines weiteren Aufrufs von Py_fclose()) auf den Stream zu undefiniertem Verhalten.

Hinzugefügt in Version 3.14.

Systemfunktionen

Dies sind Hilfsfunktionen, die Funktionalität aus dem Modul sys für C-Code zugänglich machen. Sie alle arbeiten mit dem aktuellen Interpreter-Thread-eigenen sys-Modul-Dictionary, das sich im internen Thread-Zustandsstruktur befindet.

PyObject *PySys_GetObject(const char *name)

Rückgabewert: Ausgeliehene Referenz. Teil der Stable ABI.

Gibt das Objekt name aus dem Modul sys zurück oder NULL, wenn es nicht existiert, ohne eine Ausnahme zu setzen.

int PySys_SetObject(const char *name, PyObject *v)

Teil der Stable ABI.

Setzt name im Modul sys auf v, es sei denn, v ist NULL, in diesem Fall wird name aus dem sys-Modul gelöscht. Gibt 0 bei Erfolg und -1 bei einem Fehler zurück.

void PySys_ResetWarnOptions()

Teil der Stable ABI.

Setzt sys.warnoptions auf eine leere Liste zurück. Diese Funktion kann vor Py_Initialize() aufgerufen werden.

Seit Version 3.13 veraltet, wird in Version 3.15 entfernt: Löschen Sie stattdessen sys.warnoptions und warnings.filters.

void PySys_WriteStdout(const char *format, ...)

Teil der Stable ABI.

Schreibt die durch format beschriebene Ausgabesequenz nach sys.stdout. Es werden keine Ausnahmen ausgelöst, auch wenn eine Kürzung erfolgt (siehe unten).

format sollte die Gesamtgröße der formatierten Ausgabesequenz auf 1000 Bytes oder weniger begrenzen – nach 1000 Bytes wird die Ausgabesequenz abgeschnitten. Insbesondere bedeutet dies, dass keine uneingeschränkten "%s"-Formate auftreten sollten; diese sollten mit „%.<N>s“ begrenzt werden, wobei <N> eine Dezimalzahl ist, die so berechnet wird, dass <N> zuzüglich der maximalen Größe anderer formatierter Texte 1000 Bytes nicht überschreitet. Achten Sie auch auf "%f", das Hunderte von Ziffern für sehr große Zahlen ausgeben kann.

Wenn ein Problem auftritt oder sys.stdout nicht gesetzt ist, wird die formatierte Nachricht in die tatsächliche (C-Ebene) stdout geschrieben.

void PySys_WriteStderr(const char *format, ...)

Teil der Stable ABI.

Wie PySys_WriteStdout(), aber schreibt nach sys.stderr oder stderr.

void PySys_FormatStdout(const char *format, ...)

Teil der Stable ABI.

Funktion ähnlich wie PySys_WriteStdout(), formatiert die Nachricht jedoch mit PyUnicode_FromFormatV() und kürzt die Nachricht nicht auf eine willkürliche Länge.

Hinzugefügt in Version 3.2.

void PySys_FormatStderr(const char *format, ...)

Teil der Stable ABI.

Wie PySys_FormatStdout(), schreibt aber nach sys.stderr oder stderr.

Hinzugefügt in Version 3.2.

PyObject *PySys_GetXOptions()

Rückgabewert: Geborgte Referenz. Teil der Stable ABI seit Version 3.7.

Gibt das aktuelle Wörterbuch der -X-Optionen zurück, ähnlich wie sys._xoptions. Bei einem Fehler wird NULL zurückgegeben und eine Ausnahme gesetzt.

Hinzugefügt in Version 3.2.

int PySys_Audit(const char *event, const char *format, ...)

Teil des Stable ABI seit Version 3.13.

Löst ein Audit-Ereignis mit allen aktiven Hooks aus. Gibt Null für Erfolg und ungleich Null mit einer gesetzten Ausnahme im Fehlerfall zurück.

Das Argument event als Zeichenkette darf nicht NULL sein.

Wenn Hooks hinzugefügt wurden, werden format und andere Argumente verwendet, um ein Tupel zu erstellen, das übergeben wird. Abgesehen von N sind die gleichen Formatzeichen wie bei Py_BuildValue() verfügbar. Wenn der erstellte Wert kein Tupel ist, wird er in ein Tupel mit einem Element eingefügt.

Die Formatierungsoption N darf nicht verwendet werden. Sie verbraucht eine Referenz, aber da es keine Möglichkeit gibt zu wissen, ob Argumente an diese Funktion verbraucht werden, kann ihre Verwendung zu Referenzlecks führen.

Beachten Sie, dass Formatierungszeichen wie # immer als Py_ssize_t behandelt werden sollten, unabhängig davon, ob PY_SSIZE_T_CLEAN definiert war.

sys.audit() führt die gleiche Funktion vom Python-Code aus.

Siehe auch PySys_AuditTuple().

Hinzugefügt in Version 3.8.

Geändert in Version 3.8.2: Fordert Py_ssize_t für Formatzeichen #. Zuvor wurde eine unvermeidbare Deprecation-Warnung ausgegeben.

int PySys_AuditTuple(const char *event, PyObject *args)

Teil des Stable ABI seit Version 3.13.

Ähnlich wie PySys_Audit(), aber übergibt Argumente als Python-Objekt. args muss ein tuple sein. Um keine Argumente zu übergeben, kann args NULL sein.

Hinzugefügt in Version 3.13.

int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)

Hängt die aufrufbare hook an die Liste der aktiven Audit-Hooks an. Gibt Null bei Erfolg und ungleich Null bei einem Fehler zurück. Wenn die Laufzeitumgebung initialisiert wurde, wird im Fehlerfall auch eine Ausnahme gesetzt. Hooks, die über diese API hinzugefügt wurden, werden für alle von der Laufzeitumgebung erstellten Interpreter aufgerufen.

Der Zeiger userData wird an die Hook-Funktion übergeben. Da Hook-Funktionen von verschiedenen Laufzeitumgebungen aufgerufen werden können, sollte dieser Zeiger nicht direkt auf den Python-Zustand verweisen.

Diese Funktion kann sicher vor Py_Initialize() aufgerufen werden. Wenn sie nach der Laufzeitinitialisierung aufgerufen wird, werden bestehende Audit-Hooks benachrichtigt und können die Operation stillschweigend abbrechen, indem sie eine Unterklasse von Exception auslösen (andere Fehler werden nicht unterdrückt).

Die Hook-Funktion wird vom Python-Interpreter, der das Ereignis ausgelöst hat, immer mit einem angehängten Thread-Zustand aufgerufen.

Siehe PEP 578 für eine detaillierte Beschreibung der Audits. Funktionen in der Laufzeit und der Standardbibliothek, die Ereignisse auslösen, sind in der Tabelle der Audit-Ereignisse aufgeführt. Details finden Sie in der Dokumentation jeder Funktion.

Wenn der Interpreter initialisiert ist, löst diese Funktion ein Audit-Ereignis sys.addaudithook ohne Argumente aus. Wenn ein bestehender Hook eine Ausnahme auslöst, die von Exception abgeleitet ist, wird der neue Hook nicht hinzugefügt und die Ausnahme wird gelöscht. Infolgedessen können Aufrufer nicht davon ausgehen, dass ihr Hook hinzugefügt wurde, es sei denn, sie kontrollieren alle bestehenden Hooks.

typedef int (*Py_AuditHookFunction)(const char *event, PyObject *args, void *userData)

Der Typ der Hook-Funktion. event ist das C-String-Ereignisargument, das an PySys_Audit() oder PySys_AuditTuple() übergeben wird. args ist garantiert ein PyTupleObject. userData ist das an PySys_AddAuditHook() übergebene Argument.

Hinzugefügt in Version 3.8.

Prozesssteuerung

void Py_FatalError(const char *message)

Teil der Stable ABI.

Gibt eine schwerwiegende Fehlermeldung aus und beendet den Prozess. Es wird keine Bereinigung durchgeführt. Diese Funktion sollte nur aufgerufen werden, wenn eine Bedingung erkannt wird, die es gefährlich machen würde, den Python-Interpreter weiter zu verwenden; z.B. wenn die Objektverwaltung beschädigt zu sein scheint. Unter Unix wird die Standard-C-Bibliotheksfunktion abort() aufgerufen, die versucht, eine core-Datei zu erzeugen.

Die Funktion Py_FatalError() wird durch ein Makro ersetzt, das automatisch den Namen der aktuellen Funktion protokolliert, es sei denn, das Makro Py_LIMITED_API ist definiert.

Geändert in Version 3.9: Der Funktionsname wird automatisch protokolliert.

void Py_Exit(int status)

Teil der Stable ABI.

Beendet den aktuellen Prozess. Dies ruft Py_FinalizeEx() auf und ruft dann die Standard-C-Bibliotheksfunktion exit(status) auf. Wenn Py_FinalizeEx() einen Fehler anzeigt, wird der Exit-Status auf 120 gesetzt.

Geändert in Version 3.6: Fehler bei der Finalisierung werden nicht mehr ignoriert.

int Py_AtExit(void (*func)())

Teil der Stable ABI.

Registriert eine Bereinigungsfunktion, die von Py_FinalizeEx() aufgerufen wird. Die Bereinigungsfunktion wird ohne Argumente aufgerufen und sollte keinen Wert zurückgeben. Es können höchstens 32 Bereinigungsfunktionen registriert werden. Wenn die Registrierung erfolgreich ist, gibt Py_AtExit() 0 zurück; bei einem Fehler gibt sie -1 zurück. Die zuletzt registrierte Bereinigungsfunktion wird zuerst aufgerufen. Jede Bereinigungsfunktion wird höchstens einmal aufgerufen. Da die interne Finalisierung von Python abgeschlossen ist, bevor die Bereinigungsfunktion aufgerufen wird, sollten keine Python-APIs von func aufgerufen werden.

Siehe auch

PyUnstable_AtExit() zum Übergeben eines void *data-Arguments.