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 possui suporte a duas versões do formato de dados: a versão 0
é a versão histórica, a versão 1 compartilha sequências de caracteres
internas no arquivo e após a desserialização. A versão 2 usa um
formato binário para números de ponto flutuante. "Py_MARSHAL_VERSION"
indica o formato do arquivo atual (atualmente 2).

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.

   This function can fail, in which case it sets the error indicator.
   Use "PyErr_Occurred()" to check for that.

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

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

   This function can fail, in which case it sets the error indicator.
   Use "PyErr_Occurred()" to check for that.

PyObject* PyMarshal_WriteObjectToString(PyObject *value, int version)
    *Return value: New reference.*

   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)

   Return a C "long" from the data stream in a "FILE*" opened for
   reading.  Only a 32-bit value can be read in using this function,
   regardless of the native size of "long".

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

int PyMarshal_ReadShortFromFile(FILE *file)

   Return a C "short" from the data stream in a "FILE*" opened for
   reading.  Only a 16-bit value can be read in using this function,
   regardless of the native size of "short".

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

PyObject* PyMarshal_ReadObjectFromFile(FILE *file)
    *Return value: New reference.*

   Return a Python object from the data stream in a "FILE*" opened for
   reading.

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

PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)
    *Return value: New reference.*

   Return a Python object from the data stream in a "FILE*" opened for
   reading.  Unlike "PyMarshal_ReadObjectFromFile()", this function
   assumes that no further objects will be read from the file,
   allowing it to aggressively load file data into memory so that the
   de-serialization can operate from data in memory rather than
   reading a byte at a time from the file.  Only use these variant if
   you are certain that you won't be reading anything else from the
   file.

   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)
    *Return value: New reference.*

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