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

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

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

このモジュールでは、3つのバージョンのデータ形式をサポートしています。
バージョン "0" は従来のもので、(Python 2.4 で新たに追加された) バージ
ョン "1" は intern 化された文字列をファイル内で共有し、逆マーシャル化
の時にも共有されるようにします。 (Python 2.5 で新たに追加された) バー
ジョン2は、浮動小数点数に対してバイナリフォーマットを利用します。
*PY_MARSHAL_VERSION* は現在のバージョン (バージョン 2) を示します。

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

   "long" 型の整数値 *value* を *file* へ整列化します。この関数は
   *value* の下桁 32 ビットを書き込むだけです; ネイティブの "long" 型
   サイズには関知しません。

   バージョン 2.4 で変更: ファイル形式を示す *version* が追加されまし
   た。

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

   Python オブジェクト *value* を *file* へ整列化します。

   バージョン 2.4 で変更: ファイル形式を示す *version* が追加されまし
   た。

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

   *value* の整列化表現が入った文字列オブジェクトを返します。

   バージョン 2.4 で変更: ファイル形式を示す *version* が追加されまし
   た。

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

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?

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

   読み出し用に開かれた "FILE*" 内のデータストリームから、 Python オブ
   ジェクトを読み出して返します。エラーが生じた場合、適切な例外
   ("EOFError" または "TypeError") を送出して *NULL* を返します。

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

   読み出し用に開かれた "FILE*" 内のデータストリームから、 Python オブ
   ジェクトを読み出して返します。 "PyMarshal_ReadObjectFromFile()" と
   違い、この関数はファイル中に後続のオブジェクトが存在しないと仮定し
   、ファイルからメモリ上にファイルデータを一気にメモリにロードして、
   逆整列化機構がファイルから一バイトづつ読み出す代わりにメモリ上のデ
   ータを操作できるようにします。対象のファイルから他に何も読み出さな
   いと分かっている場合にのみ、この関数を使ってください。エラーが生じ
   た場合、適切な例外 ("EOFError" または "TypeError") を送出して
   *NULL* を返します。

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

   *string* が指している *len* バイトの文字列バッファに納められたデー
   タストリームから Python オブジェクトを読み出して返します。エラーが
   生じた場合、適切な例外 ("EOFError" または "TypeError") を送出して
   *NULL* を返します。

   バージョン 2.5 で変更: この関数は以前は *len* の型に "int" を利用し
   ていました。この変更により、 64 bit システムを正しくサポートするに
   は修正が必要になります。
