|
1 .. highlightlang:: c |
|
2 |
|
3 .. _marshalling-utils: |
|
4 |
|
5 Data marshalling support |
|
6 ======================== |
|
7 |
|
8 These routines allow C code to work with serialized objects using the same data |
|
9 format as the :mod:`marshal` module. There are functions to write data into the |
|
10 serialization format, and additional functions that can be used to read the data |
|
11 back. Files used to store marshalled data must be opened in binary mode. |
|
12 |
|
13 Numeric values are stored with the least significant byte first. |
|
14 |
|
15 The module supports two versions of the data format: version 0 is the historical |
|
16 version, version 1 (new in Python 2.4) shares interned strings in the file, and |
|
17 upon unmarshalling. Version 2 (new in Python 2.5) uses a binary format for |
|
18 floating point numbers. |
|
19 *Py_MARSHAL_VERSION* indicates the current file format (currently 2). |
|
20 |
|
21 |
|
22 .. cfunction:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version) |
|
23 |
|
24 Marshal a :ctype:`long` integer, *value*, to *file*. This will only write the |
|
25 least-significant 32 bits of *value*; regardless of the size of the native |
|
26 :ctype:`long` type. |
|
27 |
|
28 .. versionchanged:: 2.4 |
|
29 *version* indicates the file format. |
|
30 |
|
31 |
|
32 .. cfunction:: void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version) |
|
33 |
|
34 Marshal a Python object, *value*, to *file*. |
|
35 |
|
36 .. versionchanged:: 2.4 |
|
37 *version* indicates the file format. |
|
38 |
|
39 |
|
40 .. cfunction:: PyObject* PyMarshal_WriteObjectToString(PyObject *value, int version) |
|
41 |
|
42 Return a string object containing the marshalled representation of *value*. |
|
43 |
|
44 .. versionchanged:: 2.4 |
|
45 *version* indicates the file format. |
|
46 |
|
47 |
|
48 The following functions allow marshalled values to be read back in. |
|
49 |
|
50 XXX What about error detection? It appears that reading past the end of the |
|
51 file will always result in a negative numeric value (where that's relevant), but |
|
52 it's not clear that negative values won't be handled properly when there's no |
|
53 error. What's the right way to tell? Should only non-negative values be written |
|
54 using these routines? |
|
55 |
|
56 |
|
57 .. cfunction:: long PyMarshal_ReadLongFromFile(FILE *file) |
|
58 |
|
59 Return a C :ctype:`long` from the data stream in a :ctype:`FILE\*` opened for |
|
60 reading. Only a 32-bit value can be read in using this function, regardless of |
|
61 the native size of :ctype:`long`. |
|
62 |
|
63 |
|
64 .. cfunction:: int PyMarshal_ReadShortFromFile(FILE *file) |
|
65 |
|
66 Return a C :ctype:`short` from the data stream in a :ctype:`FILE\*` opened for |
|
67 reading. Only a 16-bit value can be read in using this function, regardless of |
|
68 the native size of :ctype:`short`. |
|
69 |
|
70 |
|
71 .. cfunction:: PyObject* PyMarshal_ReadObjectFromFile(FILE *file) |
|
72 |
|
73 Return a Python object from the data stream in a :ctype:`FILE\*` opened for |
|
74 reading. On error, sets the appropriate exception (:exc:`EOFError` or |
|
75 :exc:`TypeError`) and returns *NULL*. |
|
76 |
|
77 |
|
78 .. cfunction:: PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file) |
|
79 |
|
80 Return a Python object from the data stream in a :ctype:`FILE\*` opened for |
|
81 reading. Unlike :cfunc:`PyMarshal_ReadObjectFromFile`, this function assumes |
|
82 that no further objects will be read from the file, allowing it to aggressively |
|
83 load file data into memory so that the de-serialization can operate from data in |
|
84 memory rather than reading a byte at a time from the file. Only use these |
|
85 variant if you are certain that you won't be reading anything else from the |
|
86 file. On error, sets the appropriate exception (:exc:`EOFError` or |
|
87 :exc:`TypeError`) and returns *NULL*. |
|
88 |
|
89 |
|
90 .. cfunction:: PyObject* PyMarshal_ReadObjectFromString(char *string, Py_ssize_t len) |
|
91 |
|
92 Return a Python object from the data stream in a character buffer containing |
|
93 *len* bytes pointed to by *string*. On error, sets the appropriate exception |
|
94 (:exc:`EOFError` or :exc:`TypeError`) and returns *NULL*. |