This document is for an old version of Python that is no longer supported. You should upgrade, and read the Python documentation for the current stable release.

# Утиліти операційної системи

PyObject* `PyOS_FSPath`( PyObject *path)
  Return value: New reference.

  Return the file system representation for path. If the object is a `str` or `bytes` object, then its reference count is incremented. If the object implements the `os.PathLike` interface, then `__fspath__()` is returned as long as it is a `str` or `bytes` object. Otherwise `TypeError` is raised and `NULL` is returned.

  Нове в версії 3.6.

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

  Return true (nonzero) if the standard I/O file fp with name filename is deemed interactive. This is the case for files for which `isatty(fileno(fp))` is true. If the global flag `Py_InteractiveFlag` is true, this function also returns true if the filename pointer is `NULL` or if the name is equal to one of the strings `'<stdin>'` or `'???'`.

void `PyOS_BeforeFork`()

  Функція для підготовки деякого внутрішнього стану перед розгалуженням процесу. Це слід викликати перед викликом `fork()` або будь-якої подібної функції, яка клонує поточний процес. Доступно лише в системах, де визначено `fork()`.

  Попередження

  Виклик C `fork()` має здійснюватися лише з «main» потоку (з «main» інтерпретатора). Те саме стосується `PyOS_BeforeFork()`.

  Нове в версії 3.7.

void `PyOS_AfterFork_Parent`()

  Функція для оновлення деякого внутрішнього стану після розгалуження процесу. Це слід викликати з батьківського процесу після виклику `fork()` або будь-якої подібної функції, яка клонує поточний процес, незалежно від того, чи клонування процесу було успішним. Доступно лише в системах, де визначено `fork()`.

  Попередження

  Виклик C `fork()` має здійснюватися лише з «main» потоку (з «main» інтерпретатора). Те саме стосується `PyOS_AfterFork_Parent()`.

  Нове в версії 3.7.

void `PyOS_AfterFork_Child`()

  Функція для оновлення стану внутрішнього інтерпретатора після розгалуження процесу. Це має бути викликано з дочірнього процесу після виклику `fork()` або будь-якої подібної функції, яка клонує поточний процес, якщо є шанс, що процес знову викличе інтерпретатор Python. Доступно лише в системах, де визначено `fork()`.

  Попередження

  Виклик C `fork()` має здійснюватися лише з «main» потоку (з «main» інтерпретатора). Те саме стосується `PyOS_AfterFork_Child()`.

  Нове в версії 3.7.

  Дивись також

  `os.register_at_fork()` дозволяє реєструвати користувацькі функції Python для виклику `PyOS_BeforeFork()`, `PyOS_AfterFork_Parent()` і `PyOS_AfterFork_Child()`.

void `PyOS_AfterFork`()

  Функція для оновлення деякого внутрішнього стану після розгалуження процесу; це слід викликати в новому процесі, якщо інтерпретатор Python продовжуватиме використовуватися. Якщо новий виконуваний файл завантажується в новий процес, цю функцію не потрібно викликати.

  Застаріло починаючи з версії 3.7: Цю функцію замінює `PyOS_AfterFork_Child()`.

int `PyOS_CheckStack`()

  Return true when the interpreter runs out of stack space. This is a reliable check, but is only available when `USE_STACKCHECK` is defined (currently on Windows using the Microsoft Visual C++ compiler). `USE_STACKCHECK` will be defined automatically; you should never change the definition in your own code.

PyOS_sighandler_t `PyOS_getsig`(int i)

  Return the current signal handler for signal i. This is a thin wrapper around either `sigaction()` or `signal()`. Do not call those functions directly! `PyOS_sighandler_t` is a typedef alias for `void (*)(int)`.

PyOS_sighandler_t `PyOS_setsig`(int i, PyOS_sighandler_t h)

  Set the signal handler for signal i to be h; return the old signal handler. This is a thin wrapper around either `sigaction()` or `signal()`. Do not call those functions directly! `PyOS_sighandler_t` is a typedef alias for `void (*)(int)`.

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

  Decode a byte string from the locale encoding with the surrogateescape error handler: undecodable bytes are decoded as characters in range U+DC80..U+DCFF. If a byte sequence can be decoded as a surrogate character, escape the bytes using the surrogateescape error handler instead of decoding them.

  Encoding, highest priority to lowest priority:

  - `UTF-8` on macOS, Android, and VxWorks;

  - `UTF-8` on Windows if `Py_LegacyWindowsFSEncodingFlag` is zero;

  - `UTF-8` if the Python UTF-8 mode is enabled;

  - `ASCII` if the `LC_CTYPE` locale is `"C"`, `nl_langinfo(CODESET)` returns the `ASCII` encoding (or an alias), and `mbstowcs()` and `wcstombs()` functions uses the `ISO-8859-1` encoding.

  - the current locale encoding.

  Поверніть вказівник на щойно виділений широкий рядок символів, використовуйте `PyMem_RawFree()`, щоб звільнити пам’ять. Якщо розмір не дорівнює `NULL`, запишіть кількість широких символів, за винятком нульового символу, у `*size`

  Повертає `NULL` у разі помилки декодування або помилки виділення пам’яті. Якщо size не дорівнює `NULL`, `*size` встановлюється на `(size_t)-1` у разі помилки пам’яті або встановлюється на `(size_t)-2` у разі помилки декодування.

  Помилки декодування ніколи не повинні траплятися, якщо немає помилки в бібліотеці C.

  Використовуйте функцію `Py_EncodeLocale()`, щоб закодувати рядок символів назад у рядок байтів.

  Дивись також

  Функції `PyUnicode_DecodeFSDefaultAndSize()` і `PyUnicode_DecodeLocaleAndSize()`.

  Нове в версії 3.5.

  Змінено в версії 3.7: The function now uses the UTF-8 encoding in the UTF-8 mode.

  Змінено в версії 3.8: The function now uses the UTF-8 encoding on Windows if `Py_LegacyWindowsFSEncodingFlag` is zero;

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

  Encode a wide character string to the locale encoding with the surrogateescape error handler: surrogate characters in the range U+DC80..U+DCFF are converted to bytes 0x80..0xFF.

  Encoding, highest priority to lowest priority:

  - `UTF-8` on macOS, Android, and VxWorks;

  - `UTF-8` on Windows if `Py_LegacyWindowsFSEncodingFlag` is zero;

  - `UTF-8` if the Python UTF-8 mode is enabled;

  - `ASCII` if the `LC_CTYPE` locale is `"C"`, `nl_langinfo(CODESET)` returns the `ASCII` encoding (or an alias), and `mbstowcs()` and `wcstombs()` functions uses the `ISO-8859-1` encoding.

  - the current locale encoding.

  The function uses the UTF-8 encoding in the Python UTF-8 mode.

  Поверніть вказівник на щойно виділений рядок байтів, використовуйте `PyMem_Free()`, щоб звільнити пам’ять. Повертає `NULL` у разі помилки кодування або помилки виділення пам’яті.

  Якщо error_pos не дорівнює `NULL`, `*error_pos` встановлюється на `(size_t)-1` у разі успіху або встановлюється на індекс недійсного символу в разі помилки кодування.

  Використовуйте функцію `Py_DecodeLocale()`, щоб декодувати рядок байтів назад до широкого рядка символів.

  Дивись також

  Функції `PyUnicode_EncodeFSDefault()` і `PyUnicode_EncodeLocale()`.

  Нове в версії 3.5.

  Змінено в версії 3.7: The function now uses the UTF-8 encoding in the UTF-8 mode.

  Змінено в версії 3.8: The function now uses the UTF-8 encoding on Windows if `Py_LegacyWindowsFSEncodingFlag` is zero.

# Системні функції

Це службові функції, які роблять функціональні можливості модуля `sys` доступними для коду C. Усі вони працюють із dict модуля `sys` поточного потоку інтерпретатора, який міститься у внутрішній структурі стану потоку.

PyObject *`PySys_GetObject`(const char *name)
  Return value: Borrowed reference.

  Повертає ім’я об’єкта з модуля `sys` або `NULL`, якщо він не існує, без встановлення винятку.

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

  Встановіть name у модулі `sys` на v, якщо v не має значення `NULL`, у цьому випадку name буде видалено з модуля sys. Повертає `0` у разі успіху, `-1` у разі помилки.

void `PySys_ResetWarnOptions`()

  Скинути `sys.warnoptions` до порожнього списку. Цю функцію можна викликати перед `Py_Initialize()`.

void `PySys_AddWarnOption`(const wchar_t *s)

  Append s to `sys.warnoptions`. This function must be called prior to `Py_Initialize()` in order to affect the warnings filter list.

void `PySys_AddWarnOptionUnicode`( PyObject *unicode)

  Append unicode to `sys.warnoptions`.

  Note: this function is not currently usable from outside the CPython implementation, as it must be called prior to the implicit import of `warnings` in `Py_Initialize()` to be effective, but can’t be called until enough of the runtime has been initialized to permit the creation of Unicode objects.

void `PySys_SetPath`(const wchar_t *path)

  Set `sys.path` to a list object of paths found in path which should be a list of paths separated with the platform’s search path delimiter (`:` on Unix, `;` on Windows).

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

  Запишіть вихідний рядок, описаний format, у `sys.stdout`. Ніяких винятків не викликається, навіть якщо відбувається скорочення (див. нижче).

  format має обмежувати загальний розмір відформатованого вихідного рядка до 1000 байтів або менше – після 1000 байтів вихідний рядок скорочується. Зокрема, це означає, що необмежені формати «%s» не повинні відбуватися; їх слід обмежити за допомогою «%. <N> s», де <N> — це десяткове число, обчислене таким чином, що <N> плюс максимальний розмір іншого відформатованого тексту не перевищує 1000 байт. Також слідкуйте за «%f», який може друкувати сотні цифр для дуже великих чисел.

  Якщо виникає проблема або `sys.stdout` не налаштовано, форматоване повідомлення записується в реальний (рівень C) stdout.

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

  Як `PySys_WriteStdout()`, але натомість записуйте в `sys.stderr` або stderr.

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

  Функція схожа на PySys_WriteStdout(), але форматує повідомлення за допомогою `PyUnicode_FromFormatV()` і не скорочує повідомлення до довільної довжини.

  Нове в версії 3.2.

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

  Як `PySys_FormatStdout()`, але замість цього записуйте в `sys.stderr` або stderr.

  Нове в версії 3.2.

void `PySys_AddXOption`(const wchar_t *s)

  Parse s as a set of `-X` options and add them to the current options mapping as returned by `PySys_GetXOptions()`. This function may be called prior to `Py_Initialize()`.

  Нове в версії 3.2.

PyObject *`PySys_GetXOptions`()
  Return value: Borrowed reference.

  Повертає поточний словник параметрів `-X`, подібно до `sys._xoptions`. У разі помилки повертається `NULL` і встановлюється виняток.

  Нове в версії 3.2.

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

  Викликати подію аудиту з будь-якими активними хуками. Повертає нуль у разі успіху та відмінний від нуля з винятком, встановленим у випадку невдачі.

  If any hooks have been added, format and other arguments will be used to construct a tuple to pass. Apart from `N`, the same format characters as used in `Py_BuildValue()` are available. If the built value is not a tuple, it will be added into a single-element tuple. (The `N` format option consumes a reference, but since there is no way to know whether arguments to this function will be consumed, using it may cause reference leaks.)

  Зауважте, що символи формату `#` завжди слід розглядати як `Py_ssize_t`, незалежно від того, чи було визначено `PY_SSIZE_T_CLEAN`.

  `sys.audit()` виконує ту саму функцію з коду Python.

  Нове в версії 3.8.

  Змінено в версії 3.8.2: Вимагати `Py_ssize_t` для символів формату `#`. Раніше виникало неминуче попередження про застарілу версію.

int `PySys_AddAuditHook`(Py_AuditHookFunction hook, void *userData)

  Додайте хук, який можна викликати, до списку активних хуків аудиту. Повертає нуль у разі успіху та ненуль у разі невдачі. Якщо середовище виконання було ініціалізовано, також установіть помилку в разі помилки. Хуки, додані через цей API, викликаються для всіх інтерпретаторів, створених середовищем виконання.

  Покажчик userData передається в функцію-перехоплювач. Оскільки функції підключення можуть викликатися з різних середовищ виконання, цей вказівник не повинен посилатися безпосередньо на стан Python.

  Цю функцію безпечно викликати перед `Py_Initialize()`. Під час виклику після ініціалізації середовища виконання наявні перехоплювачі аудиту отримують сповіщення та можуть мовчки перервати операцію, викликавши помилку підкласу з `Exception` (інші помилки не будуть заглушені).

  The hook function is of type `int (*)(const char *event, PyObject *args, void *userData)`, where args is guaranteed to be a `PyTupleObject`. The hook function is always called with the GIL held by the Python interpreter that raised the event.

  Дивіться PEP 578 для детального опису аудиту. Функції середовища виконання та стандартної бібліотеки, які викликають події, перераховані в таблиці подій аудиту. Подробиці наведено в документації кожної функції.

  If the interpreter is initialized, this function raises a auditing event `sys.addaudithook` with no arguments. If any existing hooks raise an exception derived from `Exception`, the new hook will not be added and the exception is cleared. As a result, callers cannot assume that their hook has been added unless they control all existing hooks.

  Нове в версії 3.8.

# Контроль процесів

void `Py_FatalError`(const char *message)

  Print a fatal error message and kill the process. No cleanup is performed. This function should only be invoked when a condition is detected that would make it dangerous to continue using the Python interpreter; e.g., when the object administration appears to be corrupted. On Unix, the standard C library function `abort()` is called which will attempt to produce a `core` file.

  Функцію `Py_FatalError()` замінено макросом, який автоматично реєструє назву поточної функції, якщо не визначено макрос `Py_LIMITED_API`.

  Змінено в версії 3.9: Автоматично реєструйте назву функції.

void `Py_Exit`(int status)

  Вийти з поточного процесу. Це викликає `Py_FinalizeEx()`, а потім викликає стандартну функцію бібліотеки C `exit(status)`. Якщо `Py_FinalizeEx()` вказує на помилку, статус виходу встановлюється на 120.

  Змінено в версії 3.6: Помилки під час фіналізації більше не ігноруються.

int `Py_AtExit`(void (*func)())

  Зареєструйте функцію очищення, яку буде викликати `Py_FinalizeEx()`. Функція очищення буде викликана без аргументів і не повинна повертати значення. Можна зареєструвати щонайбільше 32 функції очищення. Після успішної реєстрації `Py_AtExit()` повертає `0`; у разі помилки повертає `-1`. Першою викликається функція очищення, зареєстрована останньою. Кожна функція очищення буде викликана щонайбільше один раз. Оскільки внутрішня фіналізація Python буде завершена до виконання функції очищення, жодні API Python не повинні викликатися за допомогою func.