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