# Utilitários do sistema operacional

PyObject *`PyOS_FSPath`(PyObject *path)
  Retorna valor: Nova referência. Part of the Stable ABI since version 3.6.

  Retorna a representação do sistema de arquivos para path. Se o objeto for um objeto `str` ou `bytes`, então uma nova referência forte é retornada. Se o objeto implementa a interface `os.PathLike`, então `__fspath__()` é retornado desde que seja um objeto `str` ou `bytes`. Caso contrário, `TypeError` é levantada e `NULL` é retornado.

  Novo na versão 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`()
  Part of the Stable ABI on platforms with fork() since version 3.7.

  Função para preparar algum estado interno antes de ser feito um fork do processo. Isso deve ser chamado antes de chamar `fork()` ou qualquer função semelhante que clone o processo atual. Disponível apenas em sistemas onde `fork()` é definido.

  Aviso

  A chamada C `fork()` só deve ser feita a partir da thread “main” (do interpretador “main”). O mesmo vale para `PyOS_BeforeFork()`.

  Novo na versão 3.7.

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

  Função para atualizar algum estado interno depois de ser feito um fork do processo. Isso deve ser chamado a partir do processo pai depois de chamar `fork()` ou qualquer função semelhante que clone o processo atual, independentemente da clonagem do processo ter sido bem-sucedida ou não. Disponível apenas em sistemas onde `fork()` é definido.

  Aviso

  A chamada C `fork()` só deve ser feita a partir da thread “main” (do interpretador “main”). O mesmo vale para `PyOS_AfterFork_Parent()`.

  Novo na versão 3.7.

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

  Função para atualizar o estado interno do interpretador depois de ser feito um fork do processo. Isso deve ser chamado a partir do processo filho depois de chamar `fork()` ou qualquer função semelhante que clone o processo atual, se houver alguma chance do processo ter uma chamada de retorno para o interpretador Python. Disponível apenas em sistemas onde `fork()` é definido.

  Aviso

  A chamada C `fork()` só deve ser feita a partir da thread “main” (do interpretador “main”). O mesmo vale para `PyOS_AfterFork_Child()`.

  Novo na versão 3.7.

  Ver também

  `os.register_at_fork()` permite registrar funções personalizadas do Python para serem chamadas por `PyOS_BeforeFork()`, `PyOS_AfterFork_Parent()` e `PyOS_AfterFork_Child()`.

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

  Função para atualizar algum estado interno após ser feito um fork de processo; isso deve ser chamado no novo processo se o interpretador do Python continuar a ser usado. Se um novo executável é carregado no novo processo, esta função não precisa ser chamada.

  Obsoleto desde a versão 3.7: Esta função foi sucedida por `PyOS_AfterFork_Child()`.

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

  Retorna verdadeiro quando o interpretador ficar sem espaço de pilha. Esta é uma verificação confiável, mas só está disponível quando `USE_STACKCHECK` está definido (atualmente no Windows usando o compilador Microsoft Visual C++). `USE_STACKCHECK` será definido automaticamente; você nunca deve mudar a definição em seu próprio código.

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` is a typedef alias for `void (*)(int)`.

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! `PyOS_sighandler_t` is a typedef alias for `void (*)(int)`.

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

  Aviso

  Esta função não deve ser chamada diretamente: use a API `PyConfig` com a função `PyConfig_SetBytesString()` que garante que Python esteja pré-inicializado.

  Esta função não deve ser chamada antes de Python estar pré-inicializado e para que a localidade LC_CTYPE seja configurada corretamente: consulte a função `Py_PreInitialize()`.

  Decodifica uma string de bytes do tratador de erros e codificação do sistema de arquivos. Se o tratador de erros for o tratador de errors surrogateescape, bytes não decodificáveis são decodificados como caracteres no intervalo U+DC80..U+DCFF; e se uma string de bytes puder ser decodificada como um caractere substituto, os bytes são escapados usando o tratador de erros surrogateescape em vez de decodificá-los.

  Retorna um ponteiro para uma string de caracteres largos recém-alocada, usa `PyMem_RawFree()` para liberar a memória. Se o tamanho não for `NULL`, escreve o número de caracteres largos excluindo o caractere nulo em `*size`

  Retorna `NULL` em erro de decodificação ou erro de alocação de memória. Se size não for `NULL`, `*size` é definido como `(size_t)-1` em erro de memória ou definido como `(size_t)-2` em erro de decodificação.

  tratador de erros e codificação do sistema de arquivos são selecionados por `PyConfig_Read()`: veja os membros `filesystem_encoding` e `filesystem_errors` de `PyConfig`.

  Erros de decodificação nunca devem acontecer, a menos que haja um bug na biblioteca C.

  Use a função `Py_EncodeLocale()` para codificar a string de caracteres de volta para uma string de bytes.

  Ver também

  As funções `PyUnicode_DecodeFSDefaultAndSize()` e `PyUnicode_DecodeLocaleAndSize()`.

  Novo na versão 3.5.

  Alterado na versão 3.7: A função agora usa a codificação UTF-8 no Modo UTF-8 do Python.

  Alterado na versão 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)
  Part of the Stable ABI since version 3.7.

  Codifica uma string de caracteres largos para o tratador de erros e codificação do sistema de arquivos. Se o tratador de erros for um tratador de erros substituto, os caracteres substitutos no intervalo U+DC80..U+DCFF são convertidos em bytes 0x80..0xFF.

  Retorna um ponteiro para uma string de bytes recém-alocada; use `PyMem_Free()` para liberar a memória. Retorna `NULL` em caso de erro de codificação ou de erro de alocação de memória.

  Se error_pos não for `NULL`, `*error_pos` será definido como `(size_t)-1` em caso de sucesso, ou definido como o índice do caractere inválido em caso de erro de codificação.

  tratador de erros e codificação do sistema de arquivos são selecionados por `PyConfig_Read()`: veja os membros `filesystem_encoding` e `filesystem_errors` de `PyConfig`.

  Use a função `Py_DecodeLocale()` para decodificar a string de bytes de volta para uma string de caracteres largos.

  Aviso

  Esta função não deve ser chamada antes de Python estar pré-inicializado e para que a localidade LC_CTYPE seja configurada corretamente: consulte a função `Py_PreInitialize()`.

  Ver também

  As funções `PyUnicode_EncodeFSDefault()` e `PyUnicode_EncodeLocale()`.

  Novo na versão 3.5.

  Alterado na versão 3.7: A função agora usa a codificação UTF-8 no Modo UTF-8 do Python.

  Alterado na versão 3.8: The function now uses the UTF-8 encoding on Windows if `Py_LegacyWindowsFSEncodingFlag` is zero.

# Funções de sistema

Essas são funções utilitárias que tornam a funcionalidade do módulo `sys` acessível ao código C. Todas elas funcionam com o dicionário do módulo `sys` da thread do interpretador atual, que está contido na estrutura interna do estado de thread.

PyObject *`PySys_GetObject`(const char *name)
  Retorna valor: Referência emprestada. Part of the Stable ABI.

  Retorna o objeto name do módulo `sys` ou `NULL` se ele não existir, sem lançar uma exceção.

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

  Define name no módulo `sys` como v, a menos que v seja `NULL`, caso em que name é excluído do módulo sys. Retorna `0` em caso de sucesso e `-1` em caso de erro.

void `PySys_ResetWarnOptions`()
  Part of the Stable ABI.

  Redefine `sys.warnoptions` para uma lista vazia. Esta função pode ser chamada antes de `Py_Initialize()`.

void `PySys_AddWarnOption`(const wchar_t *s)
  Part of the Stable ABI.

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

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

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

  Escreve a string de saída descrita por format em `sys.stdout`. Nenhuma exceção será levantada, mesmo que ocorra truncamento (veja abaixo).

  format deve limitar o tamanho total da string de saída formatada a 1000 bytes ou menos – após 1000 bytes, a string de saída é truncada. Em particular, isso significa que não devem ocorrer formatos “%s” irrestritos; estes devem ser limitados usando “%.1s”, onde 2 é um número decimal calculado de forma que 3 mais o tamanho máximo de outros textos formatados não exceda 1000 bytes. Também fique atento a “%f”, que pode exibir centenas de dígitos para números muito grandes.

  Se ocorrer um problema, ou se `sys.stdout` não estiver definido, a mensagem formatada será escrita na saída padrão (nível C) stdout.

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

  Como `PySys_WriteStdout()`, mas escreve em `sys.stderr` ou stderr em vez disso.

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

  Função semelhante a PySys_WriteStdout(), mas formata a mensagem usando `PyUnicode_FromFormatV()` e não trunca a mensagem para um comprimento arbitrário.

  Novo na versão 3.2.

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

  Como `PySys_FormatStdout()`, mas escreve em `sys.stderr` ou stderr em vez disso.

  Novo na versão 3.2.

void `PySys_AddXOption`(const wchar_t *s)
  Part of the Stable ABI since version 3.7.

  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()`.

  Novo na versão 3.2.

PyObject *`PySys_GetXOptions`()
  Retorna valor: Referência emprestada. Part of the Stable ABI since version 3.7.

  Retorna o dicionário atual de opções `-X`, de forma semelhante a `sys._xoptions`. Em caso de erro, retorna `NULL` e uma exceção é definida.

  Novo na versão 3.2.

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

  Levanta um evento de auditoria com todos os ganchos ativos. Retorna zero em caso de sucesso e um valor diferente de zero com uma exceção definida em caso de falha.

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

  Observe que os caracteres de formato `#` devem sempre ser tratados como `Py_ssize_t`, independentemente de `PY_SSIZE_T_CLEAN` ter sido definido.

  `sys.audit()` executa a mesma função a partir do código Python.

  Novo na versão 3.8.

  Alterado na versão 3.8.2: É necessário o tipo `Py_ssize_t` para caracteres de formato `#`. Anteriormente, um aviso de descontinuação era levantado.

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

  Adiciona o gancho chamável à lista de ganchos de auditoria ativos. Retorna zero em caso de sucesso e um valor diferente de zero em caso de falha. Se o ambiente de execução já tiver sido inicializado, também define um erro em caso de falha. Os ganchos adicionados por meio desta API são chamados para todos os interpretadores criados pelo ambiente de execução.

  O ponteiro userData é passado para a função de gancho. Como as funções de gancho podem ser chamadas de diferentes tempos de execução, esse ponteiro não deve se referir diretamente ao estado do Python.

  Esta função pode ser chamada com segurança antes de `Py_Initialize()`. Quando chamada após a inicialização em tempo de execução, os ganchos de auditoria existentes são notificados e podem abortar silenciosamente a operação, levantando um erro da classe `Exception` (outros erros não serão silenciados).

  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.

  Consulte a PEP 578 para uma descrição detalhada da auditoria. As funções no ambiente de execução e na biblioteca padrão que levantam eventos estão listadas na tabela de eventos de auditoria. Os detalhes estão na documentação de cada função.

  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.

  Novo na versão 3.8.

# Controle de processos

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.

  A função `Py_FatalError()` é substituída por uma macro que registra automaticamente o nome da função atual, a menos que a macro `Py_LIMITED_API` esteja definida.

  Alterado na versão 3.9: Registra o nome da função automaticamente.

void `Py_Exit`(int status)
  Part of the Stable ABI.

  Encerra o processo atual. Isso chama `Py_FinalizeEx()` e, em seguida, chama a função da biblioteca padrão C `exit(status)`. Se `Py_FinalizeEx()` indicar um erro, o código de status de saída será definido como 120.

  Alterado na versão 3.6: Erros da finalização não são mais ignorados.

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

  Registra uma função de limpeza para ser chamada por `Py_FinalizeEx()`. A função de limpeza será chamada sem argumentos e não deve retornar nenhum valor. No máximo 32 funções de limpeza podem ser registradas. Quando o registro for bem-sucedido, `Py_AtExit()` retorna `0`; em caso de falha, retorna `-1`. A última função de limpeza registrada é chamada primeiro. Cada função de limpeza será chamada no máximo uma vez. Como a finalização interna do Python terá sido concluída antes da função de limpeza, nenhuma API do Python deve ser chamada por func.