Suporte a *marshalling* de dados
********************************

Essas rotinas permitem que o código C trabalhe com objetos
serializados usando o mesmo formato de dados que o módulo "marshal".
Existem funções para gravar dados no formato de serialização e funções
adicionais que podem ser usadas para ler os dados novamente. Os
arquivos usados para armazenar dados empacotados devem ser abertos no
modo binário.

Os valores numéricos são armazenados primeiro com o byte menos
significativo.

O módulo oferece suporte a várias versões do formato de dados;
consulte a "documentação do módulo Python" para obter detalhes.

Py_MARSHAL_VERSION

   A versão atual do formato. Veja "marshal.version".

void PyMarshal_WriteLongToFile(long value, FILE *file, int version)

   Aplica *marshalling* em um inteiro long, *value*, para *file*. Isso
   escreverá apenas os 32 bits menos significativos de *value*;
   independentemente do tamanho do tipo nativo long. *version* indica
   o formato do arquivo.

   Esta função pode falhar, caso em que define o indicador de erro.
   Use "PyErr_Occurred()" para verificar isso.

   Nota:

     In Python 3.15 and earlier, this function does not set the error
     indicator if writing to *file* fails. The same caveat applies as
     for "PyMarshal_WriteObjectToFile()".

void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)

   Aplica *marshalling* em um objeto Python, *value*, para *file*.
   *version* indica o formato do arquivo.

   Esta função pode falhar, caso em que define o indicador de erro.
   Use "PyErr_Occurred()" para verificar isso.

   Nota:

     In Python 3.15 and earlier, this function can write only part of
     the data to *file* and return without setting the error
     indicator, for example if *value* contains an object which cannot
     be marshalled or if writing to *file* fails (see gh-155907). Code
     which has to support these versions cannot rely on
     "PyErr_Occurred()" alone to know that all the data was written.
     It can use "PyMarshal_WriteObjectToString()" and write the result
     itself, or validate what was written.

PyObject *PyMarshal_WriteObjectToString(PyObject *value, int version)
    *Retorna valor: Nova referência.*

   Retorna um objeto de bytes que contém a representação
   pós-*marshalling* de *value*. *version* indica o formato do
   arquivo.

As seguintes funções permitem que os valores pós-*marshalling* sejam
lidos novamente.

long PyMarshal_ReadLongFromFile(FILE *file)

   Retorna um long C do fluxo de dados em um FILE* aberto para
   leitura. Somente um valor de 32 bits pode ser lido usando essa
   função, independentemente do tamanho nativo de long.

   Em caso de erro, define a exceção apropriada ("EOFError") e retorna
   "-1".

int PyMarshal_ReadShortFromFile(FILE *file)

   Retorna um short C do fluxo de dados em um FILE* aberto para
   leitura. Somente um valor de 16 bits pode ser lido usando essa
   função, independentemente do tamanho nativo de short.

   Em caso de erro, define a exceção apropriada ("EOFError") e retorna
   "-1".

PyObject *PyMarshal_ReadObjectFromFile(FILE *file)
    *Retorna valor: Nova referência.*

   Retorna um objeto Python do fluxo de dados em um FILE* aberto para
   leitura.

   Em caso de erro, define a exceção apropriada ("EOFError",
   "ValueError" ou "TypeError") e retorna "NULL".

PyObject *PyMarshal_ReadLastObjectFromFile(FILE *file)
    *Retorna valor: Nova referência.*

   Retorna um objeto Python do fluxo de dados em um FILE* aberto para
   leitura. Diferentemente de "PyMarshal_ReadObjectFromFile()", essa
   função presume que nenhum objeto adicional será lido do arquivo,
   permitindo que ela carregue agressivamente os dados do arquivo na
   memória, para que a desserialização possa operar a partir de dados
   na memória em vez de ler um byte por vez do arquivo. Use essa
   variante apenas se tiver certeza de que não estará lendo mais nada
   do arquivo.

   Em caso de erro, define a exceção apropriada ("EOFError",
   "ValueError" ou "TypeError") e retorna "NULL".

PyObject *PyMarshal_ReadObjectFromString(const char *data, Py_ssize_t len)
    *Retorna valor: Nova referência.*

   Retorna um objeto Python do fluxo de dados em um buffer de bytes
   contendo *len* bytes apontados por *data*.

   Em caso de erro, define a exceção apropriada ("EOFError",
   "ValueError" ou "TypeError") e retorna "NULL".
