# Utilitários do sistema operacional

PyObject *PyOS_FSPath(PyObject *path)
  Retorna valor: Nova referência. Parte da ABI Estável desde a versão 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.

  Adicionado na versão 3.6.

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

  Retorna verdadeiro (não zero) se o arquivo padrão de E/S fp com o nome filename for considerado interativo. Este é o caso dos arquivos para os quais `isatty(fileno(fp))` é verdade. Se `PyConfig.interactive` for não zero, esta função também retorna true se o ponteiro filename for `NULL` ou se o nome for igual a uma das strings `'<stdin>'` ou `'???'`.

  Esta função não deve ser chamada antes da inicialização do Python.

void PyOS_BeforeFork()
  Parte da ABI Estável on platforms with fork() desde a versão 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()`.

  Adicionado na versão 3.7.

void PyOS_AfterFork_Parent()
  Parte da ABI Estável on platforms with fork() desde a versão 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()`.

  Adicionado na versão 3.7.

void PyOS_AfterFork_Child()
  Parte da ABI Estável on platforms with fork() desde a versão 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()`.

  Adicionado 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()
  Parte da ABI Estável 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.

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

int PyOS_CheckStack()
  Parte da ABI Estável on platforms with USE_STACKCHECK desde a versão 3.7.

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

typedef void (*PyOS_sighandler_t)(int)
  Parte da ABI Estável.

PyOS_sighandler_t PyOS_getsig(int i)
  Parte da ABI Estável.

  Retorna o manipulador de sinal atual para o sinal i. Este é um invólucro fino em torno de `sigaction()` ou `signal()`. Não chame essas funções diretamente!

PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)
  Parte da ABI Estável.

  Define o manipulador de sinal para o sinal i como h; retornar o manipulador de sinal antigo. Este é um invólucro fino em torno de `sigaction()` ou `signal()`. Não chame essas funções diretamente!

int PyOS_InterruptOccurred(void)
  Parte da ABI Estável.

  Verifica se um sinal `SIGINT` foi recebido.

  Retorna `1` se um `SIGINT` ocorreu e limpa o sinalizador de sinal, ou `0` caso contrário.

  Na maioria dos casos, você deve preferir `PyErr_CheckSignals()` em vez desta função. `PyErr_CheckSignals()` invoca os manipuladores de sinal apropriados para todos os sinais pendentes, permitindo que o código Python lide com o sinal corretamente. Esta função detecta apenas `SIGINT` e não invoca nenhum manipulador de sinal do Python.

  Esta função é segura para sinais de async e não pode falhar. O chamador deve manter um estado de thread anexado.

wchar_t *Py_DecodeLocale(const char *arg, size_t *size)
  Parte da ABI Estável desde a versão 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()`.

  Adicionado 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: A função agora usa a codificação UTF-8 no Windows se `PyPreConfig.legacy_windows_fs_encoding` for zero;

char *Py_EncodeLocale(const wchar_t *text, size_t *error_pos)
  Parte da ABI Estável desde a versão 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()`.

  Adicionado 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: A função agora usa a codificação UTF-8 no Windows se `PyPreConfig.legacy_windows_fs_encoding` for zero.

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

  Semelhante a `fopen()`, mas path é um objeto Python e uma exceção é definida em caso de erro.

  path deve ser um objeto `str`, um objeto `bytes` ou um objeto caminho ou similar.

  Em caso de sucesso, retorna um novo ponteiro para arquivo. Em caso de erro, define uma exceção e retorna `NULL`.

  O arquivo deve ser fechado por `Py_fclose()` em vez de chamar diretamente `fclose()`.

  O descritor de arquivo é criado não herdável (PEP 446).

  O chamador deve ter um estado de thread anexado.

  Adicionado na versão 3.14.

int Py_fclose(FILE *file)

  Feche um arquivo que foi aberto por `Py_fopen()`.

  Em caso de sucesso, retorna `0`. Em caso de erro, retorna `EOF` e `errno` é definido para indicar o erro. Em ambos os casos, qualquer acesso subsequente (incluindo outra chamada a `Py_fclose()`) ao fluxo resulta em comportamento indefinido.

  Adicionado na versão 3.14.

# 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_GetAttr(PyObject *name)
  Parte da ABI Estável desde a versão 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.

  Adicionado na versão 3.15.

PyObject *PySys_GetAttrString(const char *name)
  Parte da ABI Estável desde a versão 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.

  Adicionado na versão 3.15.

int PySys_GetOptionalAttr(PyObject *name, PyObject **result)
  Parte da ABI Estável desde a versão 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.

  Adicionado na versão 3.15.

int PySys_GetOptionalAttrString(const char *name, PyObject **result)
  Parte da ABI Estável desde a versão 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*.

  Adicionado na versão 3.15.

PyObject *PySys_GetObject(const char *name)
  Retorna valor: Referência emprestada. Parte da ABI Estável.

  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)
  Parte da ABI Estável.

  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_WriteStdout(const char *format, ...)
  Parte da ABI Estável.

  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, ...)
  Parte da ABI Estável.

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

void PySys_FormatStdout(const char *format, ...)
  Parte da ABI Estável.

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

  Adicionado na versão 3.2.

void PySys_FormatStderr(const char *format, ...)
  Parte da ABI Estável.

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

  Adicionado na versão 3.2.

PyObject *PySys_GetXOptions()
  Retorna valor: Referência emprestada. Parte da ABI Estável desde a versão 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.

  Adicionado na versão 3.2.

int PySys_Audit(const char *event, const char *format, ...)
  Parte da ABI Estável desde a versão 3.13.

  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.

  O argumento de string event não pode ser NULL.

  Se algum gancho tiver sido adicionado, o argumento format e outros serão usados para construir uma tupla a ser passada. Além de `N`, os mesmos caracteres de formatação usados em `Py_BuildValue()` estão disponíveis. Se o valor construído não for uma tupla, ele será adicionado a uma tupla de um único elemento.

  A opção de formato `N` não deve ser usada. Ela consome uma referência, mas como não há como saber se os argumentos dessa função serão consumidos, usá-la pode causar vazamentos de referência.

  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.

  Veja também `PySys_AuditTuple()`.

  Adicionado 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_AuditTuple(const char *event, PyObject *args)
  Parte da ABI Estável desde a versão 3.13.

  Semelhante a `PySys_Audit()`, mas passa argumentos como um objeto Python. args deve ser uma `tuple`. Para não passar argumentos, args pode ser NULL.

  Adicionado na versão 3.13.

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

  A função de gancho é sempre chamada com um estado de thread anexado pelo interpretador Python que levantou o evento.

  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.

  Se o interpretador estiver inicializado, esta função levanta um evento de auditoria `sys.addaudithook` sem argumentos. Se algum gancho existente levantar uma exceção derivada de `Exception`, o novo gancho não será adicionado e a exceção será tratada. Consequentemente, os chamadores não podem presumir que seu gancho foi adicionado, a menos que controlem todos os ganchos existentes.

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

    O tipo da função de gancho. event é o argumento de evento em string C passado para `PySys_Audit()` ou `PySys_AuditTuple()`. args tem a garantia de ser um `PyTupleObject`. userData é o argumento passado para PySys_AddAuditHook().

  Adicionado na versão 3.8.

# Controle de processos

void Py_FatalError(const char *message)
  Parte da ABI Estável.

  Exibe uma mensagem de erro fatal e encerra forçadamente o processo. Nenhuma limpeza é realizada. Esta função só deve ser invocada quando uma condição for detectada que torne perigoso continuar usando o interpretador Python; por exemplo, quando a administração de objetos parecer estar corrompida. No Unix, a função da biblioteca padrão C `abort()` é chamada, que tentará produzir um arquivo `core`.

  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)
  Parte da ABI Estável.

  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)())
  Parte da ABI Estável.

  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.

  Ver também

  `PyUnstable_AtExit()` para passar um argumento `void *data`.