データ整列化 (data marshalling) のサポート
******************************************

以下のルーチン群は、 "marshal" モジュールと同じ形式を使った整列化オブ
ジェクトを C コードから使えるようにします。整列化形式でデータを書き出
す関数に加えて、データを読み戻す関数もあります。整列化されたデータを記
録するファイルはバイナリモードで開かれていなければなりません。

数値は最小桁が先にくるように記録されます。

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).

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

   Marshal a "long" integer, *value*, to *file*.  This will only write
   the least-significant 32 bits of *value*; regardless of the size of
   the native "long" type.

   バージョン 2.4 で変更: *version* indicates the file format.

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

   Marshal a Python object, *value*, to *file*.

   バージョン 2.4 で変更: *version* indicates the file format.

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

   Return a string object containing the marshalled representation of
   *value*.

   バージョン 2.4 で変更: *version* indicates the file format.

以下の関数を使うと、整列化された値を読み戻せます。

XXX エラー検知はどうなってる? ファイルの末尾を読み出すと、 (それが関連
したところでは) 常に負の数値が結果として生じるようであるけれども、エラ
ーがない時に負の値が適切に処理されないことはクリアではない。それを知る
ための正しい方法は? これらのルーチンを使って非負の値だけ書くべきなのか
?

long PyMarshal_ReadLongFromFile(FILE *file)

   読み出し用に開かれた "FILE*" 内のデータストリームから、 C の "long"
   型データを読み出して返します。この関数は、ネイティブの "long" のサ
   イズに関係なく、 32 ビットの値だけを読み出せます。

int PyMarshal_ReadShortFromFile(FILE *file)

   読み出し用に開かれた "FILE*" 内のデータストリームから、 C の
   "short" 型データを読み出して返します。この関数は、ネイティブの
   "short" のサイズに関係なく、 16 ビットの値だけを読み出せます。

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

   Return a Python object from the data stream in a "FILE*" opened for
   reading.  On error, sets the appropriate exception ("EOFError" or
   "TypeError") and returns *NULL*.

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

   Return a Python object from the data stream in a "FILE*" opened for
   reading.  Unlike "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 ("EOFError" or
   "TypeError") and returns *NULL*.

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

   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 ("EOFError" or "TypeError") and returns
   *NULL*.

   バージョン 2.5 で変更: This function used an "int" type for *len*.
   This might require changes in your code for properly supporting
   64-bit systems.
