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 :c:func:`PyErr_CheckSignals em vez desta função. :c:func:!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 :c:macro:!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.
Return the current dictionary of -X options, similarly to sys._xoptions. On error, NULL is returned and an exception is set.

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.

Raise an auditing event with any active hooks. Return zero for success and non-zero with an exception set on failure.

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.

Note that # format characters should always be treated as Py_ssize_t, regardless of whether PY_SSIZE_T_CLEAN was defined.

sys.audit() performs the same function from Python code.

Process Control¶

void Py_FatalError(const char *message)¶

Parte da ABI Estável.

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.

The Py_FatalError() function is replaced with a macro which logs automatically the name of the current function, unless the Py_LIMITED_API macro is defined.

Alterado na versão 3.9: Log the function name automatically.

void Py_Exit(int status)¶: Parte da ABI Estável.
Exit the current process. This calls Py_FinalizeEx() and then calls the standard C library function exit(status). If Py_FinalizeEx() indicates an error, the exit status is set to 120.

Alterado na versão 3.6: Errors from finalization no longer ignored.

int Py_AtExit(void (*func)())¶: Parte da ABI Estável.
Register a cleanup function to be called by Py_FinalizeEx(). The cleanup function will be called with no arguments and should return no value. At most 32 cleanup functions can be registered. When the registration is successful, Py_AtExit() returns 0; on failure, it returns -1. The cleanup function registered last is called first. Each cleanup function will be called at most once. Since Python’s internal finalization will have completed before the cleanup function, no Python APIs should be called by func.

Ver também

PyUnstable_AtExit() for passing a void *data argument.

Utilitários do sistema operacional¶

Funções de sistema¶

Process Control¶

Tabela de Conteúdo

Tópico anterior

Próximo tópico

Esta página