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

PyObject *PyOS_FSPath(PyObject *path)
  Return value: New reference. Part of the Stable ABI since version 3.6.

  Return the file system representation for path. If the object is a `str` or `bytes` object, then a new strong reference is returned. 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.

  Added in version 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 `PyConfig.interactive` is non-zero, this function also returns true if the filename pointer is `NULL` or if the name is equal to one of the strings `'<stdin>'` or `'???'`.

  This function must not be called before Python is initialized.

void PyOS_BeforeFork()
  Part of the Stable ABI on platforms with fork() since version 3.7.

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

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

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

  Added in version 3.7.

void PyOS_AfterFork_Parent()
  Part of the Stable ABI on platforms with fork() since version 3.7.

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

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

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

  Added in version 3.7.

void PyOS_AfterFork_Child()
  Part of the Stable ABI on platforms with fork() since version 3.7.

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

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

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

  Added in version 3.7.

  Дивись також

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

void PyOS_AfterFork()
  Part of the Stable ABI on platforms with fork().

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

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

int PyOS_CheckStack()
  Part of the Stable ABI on platforms with USE_STACKCHECK since version 3.7.

  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 certain versions of Windows using the Microsoft Visual C++ compiler). `USE_STACKCHECK` will be defined automatically; you should never change the definition in your own code.

typedef void (*PyOS_sighandler_t)(int)
  Part of the Stable ABI.

PyOS_sighandler_t PyOS_getsig(int i)
  Part of the Stable ABI.

  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 PyOS_setsig(int i, PyOS_sighandler_t h)
  Part of the Stable ABI.

  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!

int PyOS_InterruptOccurred(void)
  Part of the Stable ABI.

  Check if a `SIGINT` signal has been received.

  Returns `1` if a `SIGINT` has occurred and clears the signal flag, or `0` otherwise.

  In most cases, you should prefer `PyErr_CheckSignals()` over this function. `PyErr_CheckSignals()` invokes the appropriate signal handlers for all pending signals, allowing Python code to handle the signal properly. This function only detects `SIGINT` and does not invoke any Python signal handlers.

  This function is async-signal-safe and this function cannot fail. The caller must hold an attached thread state.

wchar_t *Py_DecodeLocale(const char *arg, size_t *size)
  Part of the Stable ABI since version 3.7.

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

  Цю функцію не слід викликати безпосередньо: використовуйте `PyConfig` API з функцією `PyConfig_SetBytesString()`, яка гарантує, що Python попередньо ініціалізовано.

  Цю функцію не можна викликати до Python попередньо ініціалізовано і щоб локаль LC_CTYPE була правильно налаштована: див. функцію `Py_PreInitialize()`.

  Декодуйте рядок байтів із filesystem encoding and error handler. Якщо обробником помилок є surrogateescape error handler, недекодовані байти декодуються як символи в діапазоні U+DC80..U+DCFF; і якщо послідовність байтів може бути декодована як сурогатний символ, байти екрануються за допомогою обробника помилок surrogateescape замість їх декодування.

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

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

  filesystem encoding and error handler вибираються `PyConfig_Read()`: див. члени `filesystem_encoding` і `filesystem_errors` `PyConfig`.

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

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

  Дивись також

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

  Added in version 3.5.

  Змінено в версії 3.7: Тепер функція використовує кодування UTF-8 у режимі Python UTF-8 Mode.

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

char *Py_EncodeLocale(const wchar_t *text, size_t *error_pos)
  Part of the Stable ABI since version 3.7.

  Закодуйте широкий рядок символів у filesystem encoding and error handler. Якщо обробником помилок є surrogateescape error handler, сурогатні символи в діапазоні U+DC80..U+DCFF перетворюються на байти 0x80..0xFF.

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

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

  filesystem encoding and error handler вибираються `PyConfig_Read()`: див. члени `filesystem_encoding` і `filesystem_errors` `PyConfig`.

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

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

  Цю функцію не можна викликати до Python попередньо ініціалізовано і щоб локаль LC_CTYPE була правильно налаштована: див. функцію `Py_PreInitialize()`.

  Дивись також

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

  Added in version 3.5.

  Змінено в версії 3.7: Тепер функція використовує кодування UTF-8 у режимі Python UTF-8 Mode.

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

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

  Similar to `fopen()`, but path is a Python object and an exception is set on error.

  path must be a `str` object, a `bytes` object, or a path-like object.

  On success, return the new file pointer. On error, set an exception and return `NULL`.

  The file must be closed by `Py_fclose()` rather than calling directly `fclose()`.

  The file descriptor is created non-inheritable (PEP 446).

  The caller must have an attached thread state.

  Added in version 3.14.

int Py_fclose(FILE *file)

  Close a file that was opened by `Py_fopen()`.

  On success, return `0`. On error, return `EOF` and `errno` is set to indicate the error. In either case, any further access (including another call to `Py_fclose()`) to the stream results in undefined behavior.

  Added in version 3.14.

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

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

PyObject *PySys_GetAttr(PyObject *name)
  Part of the Stable ABI since version 3.15.

  Get the attribute name of the `sys` module. Return a strong reference. Raise `RuntimeError` and return `NULL` if it does not exist or if the `sys` module cannot be found.

  If the non-existing object should not be treated as a failure, you can use `PySys_GetOptionalAttr()` instead.

  Added in version 3.15.

PyObject *PySys_GetAttrString(const char *name)
  Part of the Stable ABI since version 3.15.

  This is the same as `PySys_GetAttr()`, but name is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.

  If the non-existing object should not be treated as a failure, you can use `PySys_GetOptionalAttrString()` instead.

  Added in version 3.15.

int PySys_GetOptionalAttr(PyObject *name, PyObject **result)
  Part of the Stable ABI since version 3.15.

  Variant of `PySys_GetAttr()` which doesn’t raise exception if the object does not exist.

  - Set *result to a new strong reference to the object and return `1` if the object exists.

  - Set *result to `NULL` and return `0` without setting an exception if the object does not exist.

  - Set an exception, set *result to `NULL`, and return `-1`, if an error occurred.

  Added in version 3.15.

int PySys_GetOptionalAttrString(const char *name, PyObject **result)
  Part of the Stable ABI since version 3.15.

  This is the same as `PySys_GetOptionalAttr()`, but name is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.

  Added in version 3.15.

PyObject *PySys_GetObject(const char *name)
  Return value: Borrowed reference. Part of the Stable ABI.

  Similar to `PySys_GetAttrString()`, but return a borrowed reference and return `NULL` without setting exception on failure.

  Preserves exception that was set before the call.

int PySys_SetObject(const char *name, PyObject *v)
  Part of the Stable ABI.

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

void PySys_WriteStdout(const char *format, ...)
  Part of the Stable ABI.

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

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

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

void PySys_WriteStderr(const char *format, ...)
  Part of the Stable ABI.

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

void PySys_FormatStdout(const char *format, ...)
  Part of the Stable ABI.

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

  Added in version 3.2.

void PySys_FormatStderr(const char *format, ...)
  Part of the Stable ABI.

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

  Added in version 3.2.

PyObject *PySys_GetXOptions()
  Return value: Borrowed reference. Part of the Stable ABI since version 3.7.

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

  Added in version 3.2.

int PySys_Audit(const char *event, const char *format, ...)
  Part of the Stable ABI since version 3.13.

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

  The event string argument must not be NULL.

  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 must not be used. It 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.

  See also `PySys_AuditTuple()`.

  Added in version 3.8.

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

int PySys_AuditTuple(const char *event, PyObject *args)
  Part of the Stable ABI since version 3.13.

  Similar to `PySys_Audit()`, but pass arguments as a Python object. args must be a `tuple`. To pass no arguments, args can be NULL.

  Added in version 3.13.

int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)

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

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

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

  The hook function is always called with an attached thread state by the Python interpreter that raised the event.

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

  If the interpreter is initialized, this function raises an 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.

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

    The type of the hook function. event is the C string event argument passed to `PySys_Audit()` or `PySys_AuditTuple()`. args is guaranteed to be a `PyTupleObject`. userData is the argument passed to PySys_AddAuditHook().

  Added in version 3.8.

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

void Py_FatalError(const char *message)
  Part of the Stable ABI.

  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)
  Part of the Stable ABI.

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

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

int Py_AtExit(void (*func)())
  Part of the Stable ABI.

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

  Дивись також

  `PyUnstable_AtExit()` for passing a `void *data` argument.