オペレーティングシステム関連のユーティリティ
********************************************

PyObject *PyOS_FSPath(PyObject *path)
    *戻り値: 新しい参照。** 次に属します: Stable ABI (バージョン 3.6
   より).*

   "path" のファイルシステム表現を返します。 オブジェクトが "str" また
   は "bytes" の場合は、新しい *強参照* を返します。 "os.PathLike" イ
   ンターフェースを実装している場合は、"__fspath__()" の戻り値が "str"
   または "bytes" ならそれを返します。 それ以外の場合は "TypeError" を
   送出し、"NULL" を返します。

   Added in version 3.6.

int Py_FdIsInteractive(FILE *fp, const char *filename)

   名前が "filename" の標準 I/O ファイル "fp" が対話的と判定される場合
   に、真 (非ゼロ) を返します。 "isatty(fileno(fp))" が真となるファイ
   ルが該当します。 "PyConfig.interactive" が非ゼロの場合は、
   "filename" ポインタが "NULL"、または名前が "'<stdin>'" か "'???'"
   の場合にも真を返します。

   Python が初期化される前に呼び出してはいけません。

void PyOS_BeforeFork()
    * 次に属します: Stable ABI on platforms with fork() (バージョン
   3.7 より).*

   プロセスがフォークする前に、いくつかの内部状態を準備するための関数
   です。"fork()" や現在のプロセスを複製するその他の類似の関数を呼び出
   す前にこの関数を呼びださなければなりません。"fork()" が定義されてい
   るシステムでのみ利用できます。

   警告:

     C の "fork()" は、メインインタープリタ の メインスレッド からだけ
     呼び出してください。 "PyOS_BeforeFork()" も同様です。

   Added in version 3.7.

void PyOS_AfterFork_Parent()
    * 次に属します: Stable ABI on platforms with fork() (バージョン
   3.7 より).*

   プロセスがフォークした後に内部状態を更新するための関数です。
   "fork()" や、現在のプロセスを複製するその他の類似の関数を呼び出した
   後に、プロセスの複製が成功したかどうかにかかわらず、親プロセスから
   この関数を呼び出さなければなりません。"fork()" が定義されているシス
   テムでのみ利用できます。

   警告:

     C の "fork()" は、メインインタープリタ の メインスレッド からだけ
     呼び出してください。 "PyOS_AfterFork_Parent()" も同様です。

   Added in version 3.7.

void PyOS_AfterFork_Child()
    * 次に属します: Stable ABI on platforms with fork() (バージョン
   3.7 より).*

   プロセスのフォーク後にインタープリタの内部状態を更新する関数です。
   "fork()" や、現在のプロセスを複製する同様の関数を呼び出した後、その
   プロセスから Python インタープリタを再び呼び出す可能性が少しでもあ
   るなら、子プロセスからこの関数を呼び出す必要があります。 "fork()"
   が定義されているシステムでのみ利用できます。

   警告:

     C の "fork()" は、メインインタープリタ の メインスレッド からだけ
     呼び出してください。 "PyOS_AfterFork_Child()" も同様です。

   Added in version 3.7.

   参考:

     "os.register_at_fork()" を利用すると "PyOS_BeforeFork()"、
     "PyOS_AfterFork_Parent()" "PyOS_AfterFork_Child()" によって呼び出
     されるカスタムのPython関数を登録できます。

void PyOS_AfterFork()
    * 次に属します: Stable ABI on platforms with fork().*

   プロセスが fork した後の内部状態を更新するための関数です; fork 後
   Python インタプリタを使い続ける場合、新たなプロセス内でこの関数を呼
   び出さねばなりません。新たなプロセスに新たな実行可能物をロードする
   場合、この関数を呼び出す必要はありません。

   バージョン 3.7 で非推奨: この関数は "PyOS_AfterFork_Child()" によっ
   て置き換えられました。

int PyOS_CheckStack()
    * 次に属します: Stable ABI on platforms with USE_STACKCHECK (バー
   ジョン 3.7 より).*

   インタープリタのスタック領域が足りなくなった場合に真を返します。 こ
   れは信頼できるチェックですが、"USE_STACKCHECK" が定義されている場合
   (現在は Microsoft Visual C++ コンパイラを使う一部の Windows バージ
   ョン) だけ利用できます。 "USE_STACKCHECK" は自動的に定義されます。
   自分のコードで定義を変更してはいけません。

typedef void (*PyOS_sighandler_t)(int)
    * 次に属します: Stable ABI.*

PyOS_sighandler_t PyOS_getsig(int i)
    * 次に属します: Stable ABI.*

   シグナル "i" の現在のシグナルハンドラを返します。 "sigaction()" ま
   たは "signal()" の薄いラッパーです。 それらの関数を直接呼び出しては
   いけません。

PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)
    * 次に属します: Stable ABI.*

   シグナル "i" のシグナルハンドラを "h" に設定し、以前のハンドラを返
   します。 "sigaction()" または "signal()" の薄いラッパーです。 それ
   らの関数を直接呼び出してはいけません。

int PyOS_InterruptOccurred(void)
    * 次に属します: Stable ABI.*

   "SIGINT" シグナルを受信したかどうかを調べます。

   "SIGINT" が発生していればシグナルフラグをクリアして "1" を返し、そ
   れ以外の場合は "0" を返します。

   ほとんどの場合、この関数よりも "PyErr_CheckSignals()" を使う方が適
   切です。 "PyErr_CheckSignals()" は、保留中のすべてのシグナルに対応
   するシグナルハンドラを呼び出し、Python コードがシグナルを適切に処理
   できるようにします。 この関数は "SIGINT" の検出だけを行い、Python
   のシグナルハンドラは呼び出しません。

   この関数は非同期シグナルセーフで、失敗しません。 呼び出し元には *ア
   タッチされたスレッド状態* が必要です。

wchar_t *Py_DecodeLocale(const char *arg, size_t *size)
    * 次に属します: Stable ABI (バージョン 3.7 より).*

   警告:

     この関数は直接呼び出さないでください。 代わりに "PyConfig" API と
     "PyConfig_SetBytesString()" 関数を使ってください。 これにより、
     Python の事前初期化 が保証されます。LC_CTYPE ロケールを適切に設定
     するため、Python が事前初期化される 前にこの関数を呼び出してはい
     けません。 "Py_PreInitialize()" 関数を参照してください。

   *ファイルシステムのエンコーディングとエラーハンドラ* からバイト文字
   列をデコードします。エラーハンドラが surrogateescape エラーハンドラ
   なら、 デコードできないバイトは U+DC80 から U+DCFF までの範囲の文字
   としてデコードされ、バイト列がサロゲート文字としてデコードできる場
   合は、デコードするのではなく surrogateescape エラーハンドラを使って
   バイト列がエスケープされます。

   新しくメモリ確保されたワイドキャラクター文字列へのポインタを返しま
   す。 このメモリを解放するのには "PyMem_RawFree()" を使ってください
   。 引数 size が "NULL" でない場合は、 null 文字以外のワイドキャラク
   ターの数を "*size" へ書き込みます。

   デコードもしくはメモリ確保でエラーが起きると "NULL" を返します。
   *size* が "NULL" でない場合は、メモリエラーのときは "(size_t)-1" を
   、デコードでのエラーのときは "(size_t)-2" を "*size" に設定します。

   *ファイルシステムのエンコーディングとエラーハンドラ* は
   "PyConfig_Read()" が選択します。 "PyConfig" の
   "filesystem_encoding" と "filesystem_errors" メンバを参照してくださ
   い。

   C ライブラリーにバグがない限り、デコードでのエラーは起こりえません
   。

   キャラクター文字列をバイト文字列に戻すには "Py_EncodeLocale()" 関数
   を使ってください。

   参考:

     "PyUnicode_DecodeFSDefaultAndSize()" および
     "PyUnicode_DecodeLocaleAndSize()" 関数。

   Added in version 3.5.

   バージョン 3.7 で変更: この関数は、Python UTF-8 Mode ではUTF-8エン
   コーディングを利用するようになりました。

   バージョン 3.8 で変更: "PyPreConfig.legacy_windows_fs_encoding" が
   ゼロの場合、Windows では UTF-8 エンコーディングを使うようになりまし
   た。

char *Py_EncodeLocale(const wchar_t *text, size_t *error_pos)
    * 次に属します: Stable ABI (バージョン 3.7 より).*

   ワイドキャラクター文字列を *ファイルシステムのエンコーディングとエ
   ラーハンドラ* にエンコードします。エラーハンドラが surrogateescape
   エラーハンドラ なら、 U+DC80 から U+DCFF までの範囲のサロゲート文字
   は 0x80 から 0xFF までのバイトに変換されます。

   新しくメモリ確保されたバイト文字列へのポインタを返します。 このメモ
   リを解放するのには "PyMem_Free()" を使ってください。 エンコードエラ
   ーかメモリ確保エラーのときは "NULL" を返します。

   "error_pos" が "NULL" でなければ、成功した場合は "*error_pos" を
   "(size_t)-1" に、エンコードエラーの場合は無効な文字のインデックスに
   設定します。

   *ファイルシステムのエンコーディングとエラーハンドラ* は
   "PyConfig_Read()" が選択します。 "PyConfig" の
   "filesystem_encoding" と "filesystem_errors" メンバを参照してくださ
   い。

   バイト文字列をワイドキャラクター文字列に戻すには
   "Py_DecodeLocale()" 関数を使ってください。

   警告:

     LC_CTYPE ロケールを適切に設定するため、Python が事前初期化される
     前にこの関数を呼び出してはいけません。 "Py_PreInitialize()" 関数
     を参照してください。

   参考: "PyUnicode_EncodeFSDefault()" および "PyUnicode_EncodeLocale()"
       関数。

   Added in version 3.5.

   バージョン 3.7 で変更: この関数は、Python UTF-8 Mode ではUTF-8エン
   コーディングを利用するようになりました。

   バージョン 3.8 で変更: "PyPreConfig.legacy_windows_fs_encoding" が
   ゼロの場合、Windows では UTF-8 エンコーディングを使うようになりまし
   た。

FILE *Py_fopen(PyObject *path, const char *mode)

   "fopen()" と同様ですが、"path" は Python オブジェクトで、エラーの場
   合は例外を設定します。

   "path" は "str" オブジェクト、"bytes" オブジェクト、または *パス風
   オブジェクト* でなければなりません。

   成功した場合は新しいファイルポインタを返します。 エラーの場合は例外
   を設定して "NULL" を返します。

   ファイルを閉じるには "fclose()" を直接呼び出さず、"Py_fclose()" を
   使う必要があります。

   ファイル記述子は継承不可として作成されます (**PEP 446**)。

   呼び出し元には *アタッチされたスレッド状態* が必要です。

   Added in version 3.14.

int Py_fclose(FILE *file)

   "Py_fopen()" で開いたファイルを閉じます。

   成功した場合は "0" を返します。 エラーの場合は "EOF" を返し、エラー
   を示す "errno" を設定します。 どちらの場合も、その後ストリームにア
   クセスすると ("Py_fclose()" をもう一度呼び出すことも含めて)、動作は
   未定義です。

   Added in version 3.14.


システム関数
************

"sys" モジュールが提供している機能にCのコードからアクセスする関数です
。すべての関数は現在のインタプリタスレッドの "sys" モジュールの辞書に
対して動作します。この辞書は内部のスレッド状態構造体に格納されています
。

PyObject *PySys_GetAttr(PyObject *name)
    * 次に属します: Stable ABI (バージョン 3.15 より).*

   "sys" モジュールの属性 "name" を取得し、*強参照* を返します。 属性
   が存在しない場合や "sys" モジュールが見つからない場合は
   "RuntimeError" を送出し、"NULL" を返します。

   オブジェクトが存在しない場合を失敗として扱う必要がなければ、代わり
   に "PySys_GetOptionalAttr()" を使えます。

   Added in version 3.15.

PyObject *PySys_GetAttrString(const char *name)
    * 次に属します: Stable ABI (バージョン 3.15 より).*

   "PySys_GetAttr()" と同じですが、"name" は PyObject* ではなく、UTF-8
   エンコードの const char* バイト列で指定します。

   オブジェクトが存在しない場合を失敗として扱う必要がなければ、代わり
   に "PySys_GetOptionalAttrString()" を使えます。

   Added in version 3.15.

int PySys_GetOptionalAttr(PyObject *name, PyObject **result)
    * 次に属します: Stable ABI (バージョン 3.15 より).*

   オブジェクトが存在しない場合に例外を送出しない "PySys_GetAttr()" の
   変種です。

   * オブジェクトが存在する場合は、そのオブジェクトへの新しい *強参照*
     を "*result" に設定し、"1" を返します。

   * オブジェクトが存在しない場合は、"*result" を "NULL" に設定し、例
     外を設定せずに "0" を返します。

   * エラーの場合は、例外を設定し、"*result" を "NULL" にして "-1" を
     返します。

   Added in version 3.15.

int PySys_GetOptionalAttrString(const char *name, PyObject **result)
    * 次に属します: Stable ABI (バージョン 3.15 より).*

   "PySys_GetOptionalAttr()" と同じですが、"name" は PyObject* ではな
   く、UTF-8 エンコードの const char* バイト列で指定します。

   Added in version 3.15.

PyObject *PySys_GetObject(const char *name)
    *戻り値: 借用参照。** 次に属します: Stable ABI.*

   "PySys_GetAttrString()" と同様ですが、*借用参照* を返し、失敗した場
   合は例外を設定 *せずに* "NULL" を返します。

   呼び出し前に設定されていた例外を保持します。

int PySys_SetObject(const char *name, PyObject *v)
    * 次に属します: Stable ABI.*

   *v* が "NULL" で無い場合、 "sys" モジュールの *name* に *v* を設定
   します。 *v* が "NULL" なら、 sys モジュールから *name* を削除しま
   す。成功したら "0" を、エラー時は "-1" を返します。

void PySys_WriteStdout(const char *format, ...)
    * 次に属します: Stable ABI.*

   *format* で指定された出力文字列を "sys.stdout" に出力します。切り詰
   めが起こった場合を含め、例外は一切発生しません (後述)。

   *format* は、フォーマット後の出力文字列のトータルの大きさを1000バイ
   ト以下に抑えるべきです。-- 1000 バイト以降の出力文字列は切り詰めら
   れます。特に、制限のない "%s" フォーマットを使うべきではありません
   。"%.<N>s" のようにして N に10進数の値を指定し、<N> + その他のフォ
   ーマット後の最大サイズが1000を超えないように設定するべきです。同じ
   ように "%f" にも気を付ける必要があります。非常に大きい数値に対して
   、数百の数字を出力する可能性があります。

   問題が発生したり、 "sys.stdout" が設定されていなかった場合、フォー
   マット後のメッセージは本物の(Cレベルの) *stdout* に出力されます。

void PySys_WriteStderr(const char *format, ...)
    * 次に属します: Stable ABI.*

   "PySys_WriteStdout()" と同じですが、 "sys.stderr" もしくは *stderr*
   に出力します。

void PySys_FormatStdout(const char *format, ...)
    * 次に属します: Stable ABI.*

   PySys_WriteStdout() に似た関数ですが、 "PyUnicode_FromFormatV()" を
   使ってメッセージをフォーマットし、メッセージを任意の長さに切り詰め
   たりはしません。

   Added in version 3.2.

void PySys_FormatStderr(const char *format, ...)
    * 次に属します: Stable ABI.*

   "PySys_FormatStdout()" と同じですが、 "sys.stderr" もしくは
   *stderr* に出力します。

   Added in version 3.2.

PyObject *PySys_GetXOptions()
    *戻り値: 借用参照。** 次に属します: Stable ABI (バージョン 3.7 よ
   り).*

   "sys._xoptions" と同様、 "-X" オプションの現在の辞書を返します。エ
   ラーが起きると、 "NULL" が返され、例外がセットされます。

   Added in version 3.2.

int PySys_Audit(const char *event, const char *format, ...)
    * 次に属します: Stable ABI (バージョン 3.13 より).*

   有効なフックに監査イベントを通知します。 成功した場合はゼロを返し、
   失敗した場合は例外を設定して非ゼロを返します。

   文字列引数 "event" は "NULL" であってはいけません。

   フックが追加されている場合、"format" とほかの引数を使って、渡すタプ
   ルを作成します。 "N" を除き、"Py_BuildValue()" と同じ書式文字を使え
   ます。 作成した値がタプルでない場合は、1 要素のタプルに格納します。

   書式オプション "N" を使ってはいけません。 このオプションは参照を消
   費しますが、この関数への引数が消費されるかどうかを知る方法がないた
   め、使うと参照がリークする可能性があります。

   "#" 書式文字の引数は、"PY_SSIZE_T_CLEAN" の定義の有無にかかわらず、
   常に "Py_ssize_t" として扱ってください。

   "sys.audit()" は Python コードから同じ機能を提供します。

   "PySys_AuditTuple()" も参照してください。

   Added in version 3.8.

   バージョン 3.8.2 で変更: "#" 書式文字で "Py_ssize_t" が必須になりま
   した。 以前は、回避できない非推奨の警告が発生していました。

int PySys_AuditTuple(const char *event, PyObject *args)
    * 次に属します: Stable ABI (バージョン 3.13 より).*

   "PySys_Audit()" と同様ですが、引数を Python オブジェクトとして渡し
   ます。 "args" は "tuple" でなければなりません。 引数を渡さない場合
   は "NULL" でも構いません。

   Added in version 3.13.

int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)

   有効な監査フックのリストに、呼び出し可能な "hook" を追加します。 成
   功した場合はゼロを返し、失敗した場合は非ゼロを返します。 ランタイム
   が初期化済みなら、失敗時にはエラーも設定します。 この API で追加し
   たフックは、ランタイムが作成するすべてのインタープリタで呼び出され
   ます。

   *userData* ポインタはフック関数に渡されます。 フック関数は別なラン
   タイムから呼び出されるかもしれないので、このポインタは直接 Python
   の状態を参照すべきではありません。

   この関数は "Py_Initialize()" より前でも安全に呼び出せます。 ランタ
   イムの初期化後に呼び出すと、既存の監査フックに通知されます。 フック
   は "Exception" のサブクラスのエラーを送出して、通知せずにこの操作を
   中止させることがあります (それ以外のエラーは抑制されません)。

   フック関数は、イベントを発生させた Python インタープリタによって、
   常に *スレッド状態がアタッチされた* 状態で呼び出されます。

   監査の詳しい説明は **PEP 578** を参照してください。 イベントを発生
   させるランタイムと標準ライブラリの関数は 監査イベントの表 に一覧さ
   れています。 詳細は各関数のドキュメントを参照してください。

   インタープリタが初期化済みの場合、この関数は引数なしの監査イベント
   "sys.addaudithook" を発生させます。 既存のフックが "Exception" の派
   生例外を送出した場合、新しいフックは追加されず、例外はクリアされま
   す。 そのため、既存のフックをすべて制御できない限り、呼び出し側は自
   分のフックが追加されたと仮定できません。

   typedef int (*Py_AuditHookFunction)(const char *event, PyObject *args, void *userData)

      フック関数の型です。 "event" は "PySys_Audit()" または
      "PySys_AuditTuple()" に渡された C 文字列のイベント引数です。
      "args" は "PyTupleObject" であることが保証されます。 "userData"
      は "PySys_AddAuditHook()" に渡された引数です。

   Added in version 3.8.


プロセス制御
************

void Py_FatalError(const char *message)
    * 次に属します: Stable ABI.*

   致命的なエラーメッセージを表示してプロセスを終了します。 後片付けは
   一切行いません。 オブジェクトの管理情報が破損した場合など、Python
   インタープリタを使い続けると危険な状況を検出したときだけ呼び出して
   ください。 Unix では標準 C ライブラリ関数 "abort()" を呼び出し、
   "core" ファイルの生成を試みます。

   "Py_LIMITED_API" マクロが定義されていない限り、"Py_FatalError()" 関
   数は現在の関数名を自動的に記録するマクロに置き換えられます。

   バージョン 3.9 で変更: 関数名を自動的に記録するようになりました。

void Py_Exit(int status)
    * 次に属します: Stable ABI.*

   現在のプロセスを終了します。"Py_FinalizeEx()" を呼び出した後、標準C
   ライブラリ関数の "exit(status)" を呼び出します。"Py_FinalizeEx()"
   がエラーになった場合、終了ステータスは 120に設定されます。

   バージョン 3.6 で変更: 終了処理のエラーは無視されなくなりました。

int Py_AtExit(void (*func)())
    * 次に属します: Stable ABI.*

   "Py_FinalizeEx()" から呼び出される後始末処理を行う関数 (cleanup
   function) を登録します。後始末関数は引数無しで呼び出され、値を返し
   ません。最大で 32 の後始末処理関数を登録できます。登録に成功すると
   、 "Py_AtExit()" は "0" を返します;  失敗すると "-1" を返します。最
   後に登録した後始末処理関数から先に呼び出されます。各関数は高々一度
   しか呼び出されません。 Python の内部的な終了処理は後始末処理関数よ
   り以前に完了しているので、 *func* からはいかなる Python API も呼び
   出してはなりません。

   参考: "void *data" 引数を渡すには "PyUnstable_AtExit()" を参照してくだ
       さい。
