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

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

数値は最下位バイトから順に格納されます。

このモジュールは複数のデータ形式のバージョンをサポートしています。 詳
細は "Python モジュールのドキュメント" を参照してください。

Py_MARSHAL_VERSION

   現在の形式のバージョン。 "marshal.version" を参照してください。

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

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

   この関数は失敗することがあり、その場合はエラー指示子を設定します。
   それを確認するために "PyErr_Occurred()" を使います。

   注釈:

     Python 3.15 以前では、"file" への書き込みに失敗しても、この関数は
     エラー指示子を設定しません。 "PyMarshal_WriteObjectToFile()" と同
     じ注意事項が当てはまります。

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

   Python オブジェクト *value* を *file* へ整列化します。*version* は
   ファイルフォーマットを示します。

   この関数は失敗することがあり、その場合はエラー指示子を設定します。
   それを確認するために "PyErr_Occurred()" を使います。

   注釈:

     Python 3.15 以前では、"file" にデータの一部だけを書き込んで、エラ
     ー指示子を設定せずに戻る場合があります。 例えば、"value" に整列化
     できないオブジェクトが含まれる場合や、"file" への書き込みに失敗し
     た場合です (gh-155907 を参照)。 これらのバージョンをサポートする
     コードでは、"PyErr_Occurred()" だけを使ってデータ全体が書き込まれ
     たかどうかを判断することはできません。
     "PyMarshal_WriteObjectToString()" を使ってその結果を自分で書き込
     むか、書き込まれた内容を検証してください。

PyObject *PyMarshal_WriteObjectToString(PyObject *value, int version)
    *戻り値: 新しい参照。*

   *value* の整列化表現が入ったバイト列オブジェクトを返します。
   *version* はファイルフォーマットを示します。

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

long PyMarshal_ReadLongFromFile(FILE *file)

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

   エラーの場合、適切な例外 ("EOFError") を設定し "-1" を返します。

int PyMarshal_ReadShortFromFile(FILE *file)

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

   エラーの場合、適切な例外 ("EOFError") を設定し "-1" を返します。

PyObject *PyMarshal_ReadObjectFromFile(FILE *file)
    *戻り値: 新しい参照。*

   読み出し用に開かれた FILE* 内のデータストリームから Python オブジェ
   クトを返します。

   エラーの場合、適切な例外 ("EOFError", "ValueError", "TypeError") を
   設定し "NULL" を返します。

PyObject *PyMarshal_ReadLastObjectFromFile(FILE *file)
    *戻り値: 新しい参照。*

   読み取り用に開かれた FILE* のデータストリームから Python オブジェク
   トを読み取って返します。 "PyMarshal_ReadObjectFromFile()" と異なり
   、この関数はファイルからこれ以上オブジェクトを読み取らないことを前
   提とします。 そのため、ファイルのデータをまとめてメモリに読み込み、
   ファイルから 1 バイトずつ読み取る代わりにメモリ上のデータから復元で
   きます。 そのファイルからほかに何も読み取らないと確信できる場合だけ
   使ってください。

   エラーの場合、適切な例外 ("EOFError", "ValueError", "TypeError") を
   設定し "NULL" を返します。

PyObject *PyMarshal_ReadObjectFromString(const char *data, Py_ssize_t len)
    *戻り値: 新しい参照。*

   *data* が指す *len* バイトのバイト列バッファ内のデータストリームか
   ら Python オブジェクトを返します。

   エラーの場合、適切な例外 ("EOFError", "ValueError", "TypeError") を
   設定し "NULL" を返します。
