> **Источник:** https://python-all.ru/3.8/c-api/sys.html > > «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor. --- # Утилиты операционной системы #### `PyObject* PyOS_FSPath(PyObject *path)` *Возвращаемое значение: новая ссылка.* Возвращает представление файловой системы для *пути*. Если объект является объектом [`str`](https://python-all.ru/3.8/library/stdtypes.html#str) или [`bytes`](https://python-all.ru/3.8/library/stdtypes.html#bytes), то его счётчик ссылок увеличивается. Если объект реализует интерфейс [`os.PathLike`](https://python-all.ru/3.8/library/os.html#os.PathLike), то [`__fspath__()`](https://python-all.ru/3.8/library/os.html#os.PathLike.__fspath__) возвращается, если он является объектом [`str`](https://python-all.ru/3.8/library/stdtypes.html#str) или [`bytes`](https://python-all.ru/3.8/library/stdtypes.html#bytes). В противном случае возбуждается [`TypeError`](https://python-all.ru/3.8/library/exceptions.html#TypeError) и возвращается `NULL`. Новое в версии 3.6. #### `int Py_FdIsInteractive(FILE *fp, const char *filename)` Возвращает истину (ненулевое значение), если стандартный файл ввода-вывода *fp* с именем *filename* считается интерактивным. Это верно для файлов, для которых `isatty(fileno(fp))` истинно. Если глобальный флаг [`Py_InteractiveFlag`](https://python-all.ru/3.8/c-api/init.html#c.Py_InteractiveFlag) установлен в истину, эта функция также возвращает истину, если указатель *filename* равен `NULL` или если имя равно одной из строк `''` или `'???'`. #### `void PyOS_BeforeFork()` Функция для подготовки внутреннего состояния перед ветвлением процесса. Её следует вызывать перед вызовом `fork()` или любой аналогичной функции, клонирующей текущий процесс. Доступна только в системах, где определён `fork()`. > **Предупреждение** > > Вызов C `fork()` должен выполняться только из [«главного» потока](https://python-all.ru/3.8/c-api/init.html#fork-and-threads) ([«главного» интерпретатора](https://python-all.ru/3.8/c-api/init.html#sub-interpreter-support)). То же самое верно для `PyOS_BeforeFork()`. Добавлено в версии 3.7. #### `void PyOS_AfterFork_Parent()` Функция для обновления внутреннего состояния после ветвления процесса. Её следует вызывать из родительского процесса после вызова `fork()` или любой аналогичной функции, клонирующей текущий процесс, независимо от того, успешно ли прошло клонирование. Доступна только в системах, где определён `fork()`. > **Предупреждение** > > Вызов C `fork()` должен выполняться только из [«главного» потока](https://python-all.ru/3.8/c-api/init.html#fork-and-threads) ([«главного» интерпретатора](https://python-all.ru/3.8/c-api/init.html#sub-interpreter-support)). То же самое верно для `PyOS_AfterFork_Parent()`. Добавлено в версии 3.7. #### `void PyOS_AfterFork_Child()` Функция для обновления внутреннего состояния интерпретатора после ветвления процесса. Её необходимо вызывать из дочернего процесса после вызова `fork()` или любой аналогичной функции, клонирующей текущий процесс, если есть вероятность, что процесс снова вызовет интерпретатор Python. Доступна только в системах, где определён `fork()`. > **Предупреждение** > > Вызов C `fork()` должен выполняться только из [«главного» потока](https://python-all.ru/3.8/c-api/init.html#fork-and-threads) ([«главного» интерпретатора](https://python-all.ru/3.8/c-api/init.html#sub-interpreter-support)). То же самое верно для `PyOS_AfterFork_Child()`. Добавлено в версии 3.7. > **См. также** > > [`os.register_at_fork()`](https://python-all.ru/3.8/library/os.html#os.register_at_fork) позволяет регистрировать пользовательские функции Python, которые будут вызываться [`PyOS_BeforeFork()`](https://python-all.ru/3.8/c-api/sys.html#c.PyOS_BeforeFork), [`PyOS_AfterFork_Parent()`](https://python-all.ru/3.8/c-api/sys.html#c.PyOS_AfterFork_Parent) и [`PyOS_AfterFork_Child()`](https://python-all.ru/3.8/c-api/sys.html#c.PyOS_AfterFork_Child). #### `void PyOS_AfterFork()` Функция для обновления некоторого внутреннего состояния после ветвления процесса; её следует вызвать в новом процессе, если интерпретатор Python будет продолжать использоваться. Если в новый процесс загружается новый исполняемый файл, эту функцию вызывать не нужно. Устарело с версии 3.7: Эта функция заменена на [`PyOS_AfterFork_Child()`](https://python-all.ru/3.8/c-api/sys.html#c.PyOS_AfterFork_Child). #### `int PyOS_CheckStack()` Возвращает истину, когда интерпретатору не хватает места в стеке. Это надёжная проверка, но доступна только при определении `USE_STACKCHECK` (в настоящее время в Windows с использованием компилятора Microsoft Visual C++). `USE_STACKCHECK` будет определён автоматически; никогда не следует изменять это определение в своём коде. #### `PyOS_sighandler_t PyOS_getsig(int i)` Возвращает текущий обработчик сигнала для сигнала *i*. Это тонкая обёртка вокруг `sigaction()` или `signal()`. Не вызывайте эти функции напрямую! `PyOS_sighandler_t` – это псевдоним typedef для `void (*)(int)`. #### `PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)` Устанавливает обработчик сигнала для сигнала *i* равным *h*; возвращает старый обработчик сигнала. Это тонкая обёртка вокруг либо `sigaction()`, либо `signal()`. Не вызывайте эти функции напрямую! `PyOS_sighandler_t` – это псевдоним typedef для `void (*)(int)`. #### `wchar_t* Py_DecodeLocale(const char* arg, size_t *size)` Декодирует байтовую строку из кодировки локали с помощью [обработчика ошибок surrogateescape](https://python-all.ru/3.8/library/codecs.html#surrogateescape): недекодируемые байты декодируются как символы в диапазоне U+DC80..U+DCFF. Если последовательность байтов может быть декодирована как суррогатный символ, то такие байты экранируются с помощью обработчика ошибок surrogateescape вместо их декодирования. Кодировка (от высшего приоритета к низшему): - `UTF-8` на macOS, Android и VxWorks; - `UTF-8` на Windows, если [`Py_LegacyWindowsFSEncodingFlag`](https://python-all.ru/3.8/c-api/init.html#c.Py_LegacyWindowsFSEncodingFlag) равен нулю; - `UTF-8` если включён режим UTF-8 Python; - `ASCII` если локаль `LC_CTYPE` равна `"C"`, `nl_langinfo(CODESET)` возвращает кодировку `ASCII` (или псевдоним), а функции `mbstowcs()` и `wcstombs()` используют кодировку `ISO-8859-1`. - текущая кодировка локали. Возвращает указатель на новую выделенную строку широких символов; для освобождения памяти используйте [`PyMem_RawFree()`](https://python-all.ru/3.8/c-api/memory.html#c.PyMem_RawFree). Если size не равен `NULL`, записывает количество широких символов, исключая нулевой символ, в `*size`. Возвращает `NULL` при ошибке декодирования или ошибке выделения памяти. Если *size* не равен `NULL`, `*size` устанавливается в `(size_t)-1` при ошибке памяти или в `(size_t)-2` при ошибке декодирования. Ошибки декодирования никогда не должны происходить, если только нет ошибки в библиотеке C. Используйте функцию [`Py_EncodeLocale()`](https://python-all.ru/3.8/c-api/sys.html#c.Py_EncodeLocale) для обратного кодирования строки символов в байтовую строку. > **См. также** > > Функции [`PyUnicode_DecodeFSDefaultAndSize()`](https://python-all.ru/3.8/c-api/unicode.html#c.PyUnicode_DecodeFSDefaultAndSize) и [`PyUnicode_DecodeLocaleAndSize()`](https://python-all.ru/3.8/c-api/unicode.html#c.PyUnicode_DecodeLocaleAndSize). Новое в версии 3.5. Изменено в версии 3.7: Функция теперь использует кодировку UTF-8 в режиме UTF-8. Изменено в версии 3.8: Теперь функция использует кодировку UTF-8 в Windows, если [`Py_LegacyWindowsFSEncodingFlag`](https://python-all.ru/3.8/c-api/init.html#c.Py_LegacyWindowsFSEncodingFlag) равен нулю; #### `char* Py_EncodeLocale(const wchar_t *text, size_t *error_pos)` Кодирует широкую символьную строку в кодировку локали с помощью [обработчика ошибок surrogateescape](https://python-all.ru/3.8/library/codecs.html#surrogateescape): суррогатные символы в диапазоне U+DC80..U+DCFF преобразуются в байты 0x80..0xFF. Кодировка (от высшего приоритета к низшему): - `UTF-8` на macOS, Android и VxWorks; - `UTF-8` на Windows, если [`Py_LegacyWindowsFSEncodingFlag`](https://python-all.ru/3.8/c-api/init.html#c.Py_LegacyWindowsFSEncodingFlag) равен нулю; - `UTF-8` если включён режим UTF-8 Python; - `ASCII` если локаль `LC_CTYPE` равна `"C"`, `nl_langinfo(CODESET)` возвращает кодировку `ASCII` (или псевдоним), а функции `mbstowcs()` и `wcstombs()` используют кодировку `ISO-8859-1`. - текущая кодировка локали. Функция использует кодировку UTF-8 в режиме UTF-8 Python. Возвращает указатель на вновь выделенную байтовую строку, используется [`PyMem_Free()`](https://python-all.ru/3.8/c-api/memory.html#c.PyMem_Free)\\nдля освобождения памяти. Возвращает `NULL` при ошибке кодирования или ошибке выделения\\nпамяти. Если error\_pos не равен `NULL`, то `*error_pos` устанавливается в `(size_t)-1` в случае успеха или в индекс недопустимого символа при ошибке кодирования. Используйте функцию [`Py_DecodeLocale()`](https://python-all.ru/3.8/c-api/sys.html#c.Py_DecodeLocale) для обратного декодирования байтовой строки в строку широких символов. > **См. также** > > Функции [`PyUnicode_EncodeFSDefault()`](https://python-all.ru/3.8/c-api/unicode.html#c.PyUnicode_EncodeFSDefault) и [`PyUnicode_EncodeLocale()`](https://python-all.ru/3.8/c-api/unicode.html#c.PyUnicode_EncodeLocale). Новое в версии 3.5. Изменено в версии 3.7: Функция теперь использует кодировку UTF-8 в режиме UTF-8. Изменено в версии 3.8: Теперь функция использует кодировку UTF-8 в Windows, если [`Py_LegacyWindowsFSEncodingFlag`](https://python-all.ru/3.8/c-api/init.html#c.Py_LegacyWindowsFSEncodingFlag) равен нулю; # Системные функции Это служебные функции, предоставляющие функциональность модуля [`sys`](https://python-all.ru/3.8/library/sys.html#module-sys) коду на C. Все они работают со словарём модуля [`sys`](https://python-all.ru/3.8/library/sys.html#module-sys) текущего потока интерпретатора, который хранится во внутренней структуре состояния потока. #### `PyObject *PySys_GetObject(const char *name)` *Возвращаемое значение: заимствованная ссылка.* Возвращает объект *name* из модуля [`sys`](https://python-all.ru/3.8/library/sys.html#module-sys) или `NULL`, если он не существует, без установки исключения. #### `int PySys_SetObject(const char *name, PyObject *v)` Устанавливает *name* в модуле [`sys`](https://python-all.ru/3.8/library/sys.html#module-sys) равным *v*, если *v* не равно `NULL`; в противном случае *name* удаляется из модуля sys. Возвращает `0` в случае успеха, `-1` при ошибке. #### `void PySys_ResetWarnOptions()` Сбрасывает [`sys.warnoptions`](https://python-all.ru/3.8/library/sys.html#sys.warnoptions) в пустой список. Эта функция может быть вызвана до [`Py_Initialize()`](https://python-all.ru/3.8/c-api/init.html#c.Py_Initialize). #### `void PySys_AddWarnOption(const wchar_t *s)` Добавляет *s* к [`sys.warnoptions`](https://python-all.ru/3.8/library/sys.html#sys.warnoptions). Эта функция должна вызываться до [`Py_Initialize()`](https://python-all.ru/3.8/c-api/init.html#c.Py_Initialize), чтобы повлиять на список фильтра предупреждений. #### `void PySys_AddWarnOptionUnicode(PyObject *unicode)` Добавляет *unicode* к [`sys.warnoptions`](https://python-all.ru/3.8/library/sys.html#sys.warnoptions). Примечание: эта функция пока не может использоваться за пределами реализации CPython, поскольку для её работы её нужно вызывать до неявного импорта [`warnings`](https://python-all.ru/3.8/library/warnings.html#module-warnings) в [`Py_Initialize()`](https://python-all.ru/3.8/c-api/init.html#c.Py_Initialize), но она не может быть вызвана, пока среда выполнения не будет достаточно инициализирована для создания объектов Unicode. #### `void PySys_SetPath(const wchar_t *path)` Устанавливает [`sys.path`](https://python-all.ru/3.8/library/sys.html#sys.path) в объект списка путей, найденных в *path*, который должен быть списком путей, разделённых разделителем пути поиска платформы (`:` в Unix, `;` в Windows). #### `void PySys_WriteStdout(const char *format, ...)` Записывает выходную строку, описываемую *format*, в [`sys.stdout`](https://python-all.ru/3.8/library/sys.html#sys.stdout). Исключения не вызываются, даже если произошло усечение (см. ниже). *format* должен ограничивать общий размер форматированной выходной строки до 1000 байт или менее – после 1000 байт строка усекается. В частности, это означает, что не должно быть неограниченных форматов «%s»; их следует ограничивать с помощью «%.\s», где \ – десятичное число, рассчитанное так, чтобы \ плюс максимальный размер другого форматированного текста не превышал 1000 байт. Также следует остерегаться «%f», который может печатать сотни цифр для очень больших чисел. Если возникает проблема или [`sys.stdout`](https://python-all.ru/3.8/library/sys.html#sys.stdout) не задан, форматированное сообщение записывается в настоящий (на уровне C) *stdout*. #### `void PySys_WriteStderr(const char *format, ...)` Аналогично [`PySys_WriteStdout()`](https://python-all.ru/3.8/c-api/sys.html#c.PySys_WriteStdout), но выводит в [`sys.stderr`](https://python-all.ru/3.8/library/sys.html#sys.stderr) или *stderr* вместо этого. #### `void PySys_FormatStdout(const char *format, ...)` Функция подобна PySys\_WriteStdout(), но форматирует сообщение с помощью [`PyUnicode_FromFormatV()`](https://python-all.ru/3.8/c-api/unicode.html#c.PyUnicode_FromFormatV) и не обрезает сообщение до произвольной длины. Новое в версии 3.2. #### `void PySys_FormatStderr(const char *format, ...)` Аналогично [`PySys_FormatStdout()`](https://python-all.ru/3.8/c-api/sys.html#c.PySys_FormatStdout), но выводит в [`sys.stderr`](https://python-all.ru/3.8/library/sys.html#sys.stderr) или *stderr* вместо этого. Новое в версии 3.2. #### `void PySys_AddXOption(const wchar_t *s)` Разбирает *s* как набор опций [`-X`](https://python-all.ru/3.8/using/cmdline.html#id5) и добавляет их в текущее отображение опций, возвращаемое [`PySys_GetXOptions()`](https://python-all.ru/3.8/c-api/sys.html#c.PySys_GetXOptions). Эту функцию можно вызывать до [`Py_Initialize()`](https://python-all.ru/3.8/c-api/init.html#c.Py_Initialize). Новое в версии 3.2. #### `PyObject *PySys_GetXOptions()` *Возвращаемое значение: заимствованная ссылка.* Возвращает текущий словарь опций [`-X`](https://python-all.ru/3.8/using/cmdline.html#id5), аналогично [`sys._xoptions`](https://python-all.ru/3.8/library/sys.html#sys._xoptions). При ошибке возвращается `NULL` и устанавливается исключение. Новое в версии 3.2. #### `int PySys_Audit(const char *event, const char *format, ...)` Вызывает событие аудита с любыми активными перехватчиками. Возвращает ноль при успехе и ненулевое значение с установленным исключением при ошибке. Если были добавлены какие-либо хуки, *format* и остальные аргументы будут использованы для создания кортежа для передачи. Кроме `N`, доступны те же символы формата, что и в [`Py_BuildValue()`](https://python-all.ru/3.8/c-api/arg.html#c.Py_BuildValue). Если построенное значение не является кортежем, оно будет добавлено в кортеж из одного элемента. (Опция формата `N` потребляет ссылку, но поскольку невозможно узнать, будут ли аргументы этой функции потреблены, её использование может привести к утечкам ссылок.) Обратите внимание, что символы форматирования `#` всегда должны рассматриваться как `Py_ssize_t`, независимо от того, был ли определён `PY_SSIZE_T_CLEAN`. [`sys.audit()`](https://python-all.ru/3.8/library/sys.html#sys.audit) выполняет ту же функцию из кода Python. Новое в версии 3.8. Изменено в версии 3.8.2: Требуется `Py_ssize_t` для символов форматирования `#`. Ранее выдавалось неизбежное предупреждение об устаревании. #### `int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)` Добавляет вызываемый объект *hook* в список активных хуков аудита.\\nВозвращает ноль при успехе\\nи ненулевое значение при ошибке. Если среда выполнения уже инициализирована, также устанавливает\\nошибку при неудаче. Хуки, добавленные через этот API, вызываются для всех\\nинтерпретаторов, созданных средой выполнения. Указатель *userData* передаётся в функцию-обработчик. Поскольку функции-обработчики могут вызываться из разных сред выполнения, этот указатель не должен напрямую ссылаться на состояние Python. Эту функцию можно безопасно вызывать до [`Py_Initialize()`](https://python-all.ru/3.8/c-api/init.html#c.Py_Initialize). При вызове после инициализации среды выполнения существующие перехватчики аудита уведомляются и могут молча прервать операцию, вызвав ошибку, являющуюся подклассом [`Exception`](https://python-all.ru/3.8/library/exceptions.html#Exception) (другие ошибки не будут скрыты). Функция-обработчик имеет тип `int (*)(const char *event, PyObject *args, void *userData)`, где *args* гарантированно является [`PyTupleObject`](https://python-all.ru/3.8/c-api/tuple.html#c.PyTupleObject). Функция-обработчик всегда вызывается при удержании GIL интерпретатором Python, вызвавшим событие. См. [**PEP 578**](https://python-all.ru/3.8/c-api/sys.html) для подробного описания аудита. Функции в среде выполнения и стандартной библиотеке, которые вызывают события, перечислены в [таблице событий аудита](https://python-all.ru/3.8/library/audit_events.html#audit-events). Подробности приведены в документации каждой функции. Если интерпретатор инициализирован, эта функция вызывает событие аудита `sys.addaudithook` без аргументов. Если какой-либо из существующих обработчиков возбуждает исключение, производное от [`Exception`](https://python-all.ru/3.8/library/exceptions.html#Exception), новый обработчик не будет добавлен, и исключение сбрасывается. В результате вызывающий код не может предполагать, что его обработчик был добавлен, если только он не контролирует все существующие обработчики. Новое в версии 3.8. # Управление процессами #### `void Py_FatalError(const char *message)` Выводит фатальное сообщение об ошибке и завершает процесс. Очистка не выполняется. Эту функцию следует вызывать только при обнаружении условия, которое делает опасным продолжение использования интерпретатора Python; например, когда управление объектами повреждено. В Unix вызывается стандартная функция библиотеки C `abort()`, которая пытается создать файл `core`. #### `void Py_Exit(int status)` Завершает текущий процесс. Вызывает [`Py_FinalizeEx()`](https://python-all.ru/3.8/c-api/init.html#c.Py_FinalizeEx), а затем вызывает стандартную функцию библиотеки C `exit(status)`. Если [`Py_FinalizeEx()`](https://python-all.ru/3.8/c-api/init.html#c.Py_FinalizeEx) указывает на ошибку, код завершения устанавливается в 120. Изменено в версии 3.6: Ошибки при финализации больше не игнорируются. #### `int Py_AtExit(void (*func)())` Регистрирует функцию очистки, которая будет вызвана с помощью [`Py_FinalizeEx()`](https://python-all.ru/3.8/c-api/init.html#c.Py_FinalizeEx). Функция очистки будет вызвана без аргументов и не должна возвращать значение. Можно зарегистрировать не более 32 функций очистки. При успешной регистрации [`Py_AtExit()`](https://python-all.ru/3.8/c-api/sys.html#c.Py_AtExit) возвращает `0`; при неудаче – `-1`. Последняя зарегистрированная функция очистки вызывается первой. Каждая функция очистки будет вызвана не более одного раза. Поскольку внутренняя финализация Python завершится до вызова функции очистки, *func* не должна вызывать никакие API Python.