Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r71873 | jeroen.ruigrok | 2009-04-25 13:15:06 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to expanding.
........
r71874 | jeroen.ruigrok | 2009-04-25 13:59:09 +0200 (za, 25 apr 2009) | 2 lines
First attempt to document PyObject_HEAD_INIT and PyVarObject_HEAD_INIT.
........
r71882 | jeroen.ruigrok | 2009-04-25 14:49:10 +0200 (za, 25 apr 2009) | 3 lines
Issue #4239: adjust email examples not to use connect() and terminate with
quit() and not close().
........
r71890 | jeroen.ruigrok | 2009-04-25 15:07:40 +0200 (za, 25 apr 2009) | 3 lines
Rewrite a sentence to be more in line with the rest of the documentation with
regard to person and audience.
........
r71893 | jeroen.ruigrok | 2009-04-25 15:58:58 +0200 (za, 25 apr 2009) | 2 lines
Reformat file prior to editing.
........
r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines
The type for ppos has been Py_ssize_t since 2.5, reflect this in the
documentation.
........
r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines
Reformat paragraph.
........
r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines
Issue #4129: Belatedly document which C API functions had their argument(s) or
return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this
might cause problems on 64-bit platforms.
........
r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: Document more int -> Py_ssize_t changes.
........
r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines
Reference to an int type, whereas it's a Py_ssize_t as the synopsis states.
........
r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines
Since I edited this file, reformat for future edits.
........
r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71920 | jeroen.ruigrok | 2009-04-25 21:44:55 +0200 (za, 25 apr 2009) | 5 lines
Issue #4129: More documentation pointers about int -> Py_ssize_t.
Also fix up the documentation for PyObject_GC_Resize(). It seems that since
it first got documented, the documentation was actually for
_PyObject_GC_Resize().
........
r71921 | jeroen.ruigrok | 2009-04-25 21:46:19 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: Documentation notes for int -> Py_ssize_t changes.
........
r71922 | jeroen.ruigrok | 2009-04-25 21:49:05 +0200 (za, 25 apr 2009) | 2 lines
Reformat, since I've been busy here anyway.
........
r71923 | jeroen.ruigrok | 2009-04-25 21:54:34 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: Add a versionchanged notice for a few forgotten entries.
........
r71925 | jeroen.ruigrok | 2009-04-25 22:37:39 +0200 (za, 25 apr 2009) | 2 lines
Since it's a macro, actually refer to it as such instead of function.
........
r71926 | jeroen.ruigrok | 2009-04-25 22:40:10 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71927 | jeroen.ruigrok | 2009-04-25 22:41:40 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: int -> Py_ssize_t documentation.
........
r71928 | jeroen.ruigrok | 2009-04-25 22:43:30 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71929 | jeroen.ruigrok | 2009-04-25 22:44:58 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: int -> Py_ssize_t documentation.
........
r71931 | jeroen.ruigrok | 2009-04-25 22:50:27 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: int -> Py_ssize_t documentation.
........
r71932 | jeroen.ruigrok | 2009-04-25 22:55:39 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: more int -> Py_ssize_t documentation.
........
r71933 | jeroen.ruigrok | 2009-04-25 22:58:35 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: more int -> Py_ssize_t documentation.
........
r71934 | jeroen.ruigrok | 2009-04-25 23:02:34 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: field changed from int to Py_ssize_t.
........
r71937 | jeroen.ruigrok | 2009-04-25 23:16:05 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: document int -> Py_ssize_t changes.
........
diff --git a/Doc/c-api/marshal.rst b/Doc/c-api/marshal.rst
index 4df6288..34a83f4 100644
--- a/Doc/c-api/marshal.rst
+++ b/Doc/c-api/marshal.rst
@@ -5,25 +5,26 @@
Data marshalling support
========================
-These routines allow C code to work with serialized objects using the same data
-format as the :mod:`marshal` module. There are functions to write data into the
-serialization format, and additional functions that can be used to read the data
-back. Files used to store marshalled data must be opened in binary mode.
+These routines allow C code to work with serialized objects using the same
+data format as the :mod:`marshal` module. There are functions to write data
+into the serialization format, and additional functions that can be used to
+read the data back. Files used to store marshalled data must be opened in
+binary mode.
Numeric values are stored with the least significant byte first.
-The module supports two versions of the data format: version 0 is the historical
-version, version 1 (new in Python 2.4) shares interned strings in the file, and
-upon unmarshalling. Version 2 (new in Python 2.5) uses a binary format for
-floating point numbers.
-*Py_MARSHAL_VERSION* indicates the current file format (currently 2).
+The module supports two versions of the data format: version 0 is the
+historical version, version 1 (new in Python 2.4) shares interned strings in
+the file, and upon unmarshalling. Version 2 (new in Python 2.5) uses a binary
+format for floating point numbers. *Py_MARSHAL_VERSION* indicates the current
+file format (currently 2).
.. cfunction:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version)
- Marshal a :ctype:`long` integer, *value*, to *file*. This will only write the
- least-significant 32 bits of *value*; regardless of the size of the native
- :ctype:`long` type.
+ Marshal a :ctype:`long` integer, *value*, to *file*. This will only write
+ the least-significant 32 bits of *value*; regardless of the size of the
+ native :ctype:`long` type.
.. versionchanged:: 2.4
*version* indicates the file format.
@@ -48,24 +49,24 @@
The following functions allow marshalled values to be read back in.
XXX What about error detection? It appears that reading past the end of the
-file will always result in a negative numeric value (where that's relevant), but
-it's not clear that negative values won't be handled properly when there's no
-error. What's the right way to tell? Should only non-negative values be written
-using these routines?
+file will always result in a negative numeric value (where that's relevant),
+but it's not clear that negative values won't be handled properly when there's
+no error. What's the right way to tell? Should only non-negative values be
+written using these routines?
.. cfunction:: long PyMarshal_ReadLongFromFile(FILE *file)
- Return a C :ctype:`long` from the data stream in a :ctype:`FILE\*` opened for
- reading. Only a 32-bit value can be read in using this function, regardless of
- the native size of :ctype:`long`.
+ Return a C :ctype:`long` from the data stream in a :ctype:`FILE\*` opened
+ for reading. Only a 32-bit value can be read in using this function,
+ regardless of the native size of :ctype:`long`.
.. cfunction:: int PyMarshal_ReadShortFromFile(FILE *file)
- Return a C :ctype:`short` from the data stream in a :ctype:`FILE\*` opened for
- reading. Only a 16-bit value can be read in using this function, regardless of
- the native size of :ctype:`short`.
+ Return a C :ctype:`short` from the data stream in a :ctype:`FILE\*` opened
+ for reading. Only a 16-bit value can be read in using this function,
+ regardless of the native size of :ctype:`short`.
.. cfunction:: PyObject* PyMarshal_ReadObjectFromFile(FILE *file)
@@ -78,17 +79,22 @@
.. cfunction:: PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)
Return a Python object from the data stream in a :ctype:`FILE\*` opened for
- reading. Unlike :cfunc:`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. On error, sets the appropriate exception (:exc:`EOFError` or
- :exc:`TypeError`) and returns *NULL*.
+ reading. Unlike :cfunc:`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. On error, sets the appropriate exception
+ (:exc:`EOFError` or :exc:`TypeError`) and returns *NULL*.
.. cfunction:: PyObject* PyMarshal_ReadObjectFromString(char *string, Py_ssize_t len)
- Return a Python object from the data stream in a character buffer containing
- *len* bytes pointed to by *string*. On error, sets the appropriate exception
- (:exc:`EOFError` or :exc:`TypeError`) and returns *NULL*.
+ Return a Python object from the data stream in a character buffer
+ containing *len* bytes pointed to by *string*. On error, sets the
+ appropriate exception (:exc:`EOFError` or :exc:`TypeError`) and returns
+ *NULL*.
+
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *len*. This might require
+ changes in your code for properly supporting 64-bit systems.