Data marshalling support¶

These routines allow C code to work with serialized objects using the samedata format as themarshal module. There are functions to write datainto the serialization format, and additional functions that can be used toread the data back. Files used to store marshalled data must be opened inbinary mode.

Numeric values are stored with the least significant byte first.

The module supports two versions of the data format: version 0 is thehistorical version, version 1 shares interned strings in the file, and uponunmarshalling. Version 2 uses a binary format for floating-point numbers.Py_MARSHAL_VERSION indicates the current file format (currently 2).

voidPyMarshal_WriteLongToFile(longvalue,FILE*file,intversion)¶

Marshal along integer,value, tofile. This will only writethe least-significant 32 bits ofvalue; regardless of the size of thenativelong type.version indicates the file format.

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

voidPyMarshal_WriteObjectToFile(PyObject*value,FILE*file,intversion)¶

Marshal a Python object,value, tofile.version indicates the file format.

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

PyObject*PyMarshal_WriteObjectToString(PyObject*value,intversion)¶

Return value: New reference.

Return a bytes object containing the marshalled representation ofvalue.version indicates the file format.

The following functions allow marshalled values to be read back in.

longPyMarshal_ReadLongFromFile(FILE*file)¶

Return a Clong from the data stream in aFILE* openedfor reading. Only a 32-bit value can be read in using this function,regardless of the native size oflong.

On error, sets the appropriate exception (EOFError) and returns-1.

intPyMarshal_ReadShortFromFile(FILE*file)¶

Return a Cshort from the data stream in aFILE* openedfor reading. Only a 16-bit value can be read in using this function,regardless of the native size ofshort.

On error, sets the appropriate exception (EOFError) and returns-1.

PyObject*PyMarshal_ReadObjectFromFile(FILE*file)¶

Return value: New reference.

Return a Python object from the data stream in aFILE* opened forreading.

On error, sets the appropriate exception (EOFError,ValueErrororTypeError) and returnsNULL.

PyObject*PyMarshal_ReadLastObjectFromFile(FILE*file)¶

Return value: New reference.

Return a Python object from the data stream in aFILE* opened forreading. UnlikePyMarshal_ReadObjectFromFile(), this functionassumes that no further objects will be read from the file, allowing it toaggressively load file data into memory so that the de-serialization canoperate from data in memory rather than reading a byte at a time from thefile. Only use these variant if you are certain that you won’t be readinganything else from the file.

On error, sets the appropriate exception (EOFError,ValueErrororTypeError) and returnsNULL.

PyObject*PyMarshal_ReadObjectFromString(constchar*data,Py_ssize_tlen)¶

Return value: New reference.

Return a Python object from the data stream in a byte buffercontaininglen bytes pointed to bydata.

On error, sets the appropriate exception (EOFError,ValueErrororTypeError) and returnsNULL.