Soporte de empaquetado (*marshalling*) de datos
***********************************************

Estas rutinas permiten que el código C funcione con objetos
serializados utilizando el mismo formato de datos que el módulo
"marshal". Hay funciones para escribir datos en el formato de
serialización y funciones adicionales que se pueden usar para volver a
leer los datos. Los archivos utilizados para almacenar datos ordenados
deben abrirse en modo binario.

Los valores numéricos se almacenan con el byte menos significativo
primero.

El módulo admite dos versiones del formato de datos: la versión 0 es
la versión histórica, la versión 1 comparte cadenas de caracteres
internas en el archivo y al desempaquetar (*unmarshalling*). La
versión 2 usa un formato binario para números de punto flotante.
"Py_MARSHAL_VERSION" indica el formato de archivo actual (actualmente
2).

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

   Empaqueta (*marshal*) un entero *value* long a un archivo *file*.
   Esto solo escribirá los 32 bits menos significativos de *value*;
   sin importar el tamaño del tipo long nativo. *version* indica el
   formato del archivo.

   Esta función puede fallar, en cuyo caso establece el indicador de
   error. Utiliza "PyErr_Occurred()" para comprobarlo.

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

   Empaqueta (*marshal*) un objeto Python, *value*, a un archivo
   *file*. *version* indica el formato del archivo.

   Esta función puede fallar, en cuyo caso establece el indicador de
   error. Utiliza "PyErr_Occurred()" para comprobarlo.

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

   Retorna un objeto de bytes que contiene la representación
   empaquetada (*marshalled*) de *value*. *version* indica el formato
   del archivo.

Las siguientes funciones permiten volver a leer los valores
empaquetados (*marshalled*).

long PyMarshal_ReadLongFromFile(FILE *file)

   Retorna un entero long de C desde el flujo de datos FILE* abierto
   para lectura. Solo se puede leer un valor de 32 bits con esta
   función, independientemente del tamaño nativo del tipo long.

   En caso de error, establece la excepción apropiada ("EOFError") y
   retorna "-1".

int PyMarshal_ReadShortFromFile(FILE *file)

   Retorna un entero short de C desde el flujo de datos FILE* abierto
   para lectura. Solo se puede leer un valor de 16 bits con esta
   función, independientemente del tamaño nativo del tipo short.

   En caso de error, establece la excepción apropiada ("EOFError") y
   retorna "-1".

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

   Retorna un objeto Python del flujo de datos FILE* abierto para
   lectura.

   En caso de error, establece la excepción apropiada ("EOFError",
   "ValueError" o "TypeError") y retorna "NULL".

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

   Retorna un objeto Python del flujo de datos FILE* abierto para
   lectura. A diferencia de "PyMarshal_ReadObjectFromFile()", esta
   función asume que no se leerán más objetos del archivo, lo que le
   permite cargar agresivamente los datos del archivo en la memoria
   para que la deserialización pueda operar desde dichos datos en
   lugar de leer un byte a la vez desde el archivo. Solo use esta
   variante si está seguro de que no leerá nada más del archivo.

   En caso de error, establece la excepción apropiada ("EOFError",
   "ValueError" o "TypeError") y retorna "NULL".

PyObject *PyMarshal_ReadObjectFromString(const char *data, Py_ssize_t len)
    *Return value: New reference.*

   Retorna un objeto Python del flujo de datos en un búfer de bytes
   que contiene *len* bytes a los que apunta *data*.

   En caso de error, establece la excepción apropiada ("EOFError",
   "ValueError" o "TypeError") y retorna "NULL".
