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

PyObject* PyOS_FSPath(PyObject *path)

Return value: New reference.

path のファイルシステム表現を返します。オブジェクトが str か bytes の場合は、その参照カウンタがインクリメントされます。オブジェクトが os.PathLike インタフェースを実装している場合、__fspath__() が呼び出され、その結果が str が bytes であればその値が返されます。さもなければ、TypeError が送出され、NULL が返されます。

バージョン 3.6 で追加.

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

filename という名前の標準 I/O ファイル fp が対話的 (interactive) であると考えられる場合に真 (非ゼロ) を返します。これは isatty(fileno(fp)) が真になるファイルの場合です。グローバルなフラグ Py_InteractiveFlag が真の場合には、 filename ポインタが NULL か、名前が '<stdin>' または '???' のいずれかに等しい場合にも真を返します。

void PyOS_AfterFork()

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

int PyOS_CheckStack()

インタプリタがスタック空間を使い尽くしたときに真を返します。このチェック関数には信頼性がありますが、 USE_STACKCHECK が定義されている場合 (現状では Microsoft Visual C++ コンパイラでビルドした Windows 版) にしか利用できません . USE_STACKCHECK は自動的に定義されます; 自前のコードでこの定義を変更してはなりません。

PyOS_sighandler_t PyOS_getsig(int i)

シグナル i に対する現在のシグナルハンドラを返します。この関数は sigaction() または signal() のいずれかに対する薄いラッパです。 sigaction() や signal() を直接呼び出してはなりません! PyOS_sighandler_t は void (*)(int) の typedef による別名です。

PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)

シグナル i に対する現在のシグナルハンドラを h に設定します; 以前のシグナルハンドラを返します。この関数は sigaction() または signal() のいずれかに対する薄いラッパーです。 sigaction() や signal() を直接呼び出してはなりません! PyOS_sighandler_t は void (*)(int) の typedef による別名です。

wchar_t* Py_DecodeLocale(const char* arg, size_t *size)

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

エンコーディング（優先度の高い順から）:

• UTF-8 macOS またはAndroid

• ASCII if the LC_CTYPE locale is "C", nl_langinfo(CODESET) returns the ASCII encoding (or an alias), and mbstowcs() and wcstombs() functions use the ISO-8859-1 encoding.

• 現在のロケールエンコーディング (LC_CTYPE ロケール)

Return a pointer to a newly allocated wide character string, use PyMem_RawFree() to free the memory. If size is not NULL, write the number of wide characters excluding the null character into *size.

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

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

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

参考

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

バージョン 3.5 で追加.

char* Py_EncodeLocale(const wchar_t *text, size_t *error_pos)

surrogateescape エラーハンドラ を使って、ワイドキャラクター文字列をロケールエンコーディングにエンコードします: U+DC80 から U+DCFF までの範囲のサロゲート文字は 0x80 から 0xFF までのバイトに変換されます。

エンコーディング（優先度の高い順から）:

• UTF-8 macOS またはAndroid

• ASCII if the LC_CTYPE locale is "C", nl_langinfo(CODESET) returns the ASCII encoding (or an alias), and mbstowcs() and wcstombs() functions uses the ISO-8859-1 encoding.

• 現在のロケールエンコーディング

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

error_pos が NULL でない場合 *error_pos はエンコードエラーの不正な文字のインデックスに設定され、それ以外の場合は (size_t)-1 に設定されます。

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

参考

PyUnicode_EncodeFSDefault() および PyUnicode_EncodeLocale() 関数。

バージョン 3.5 で追加.

システム関数

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

PyObject *PySys_GetObject(const char *name)

Return value: Borrowed reference.

sys モジュールの name オブジェクトを返すか、存在しなければ例外を設定せずに NULL を返します。

int PySys_SetObject(const char *name, PyObject *v)

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

void PySys_ResetWarnOptions()

sys.warnoptions を、空リストにリセットします。

void PySys_AddWarnOption(wchar_t *s)

sys.warnoptions に s を追加します。

void PySys_AddWarnOptionUnicode(PyObject *unicode)

sys.warnoptions に unicode を追加します。

void PySys_SetPath(wchar_t *path)

sys.path を path に含まれるパスの、リストオブジェクトに設定します。 path はプラットフォームの検索パスデリミタ(Unixでは :, Windows では ;) で区切られたパスのリストでなければなりません。

void PySys_WriteStdout(const char *format, ...)

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

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

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

void PySys_WriteStderr(const char *format, ...)

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

void PySys_FormatStdout(const char *format, ...)

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

バージョン 3.2 で追加.

void PySys_FormatStderr(const char *format, ...)

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

バージョン 3.2 で追加.

void PySys_AddXOption(const wchar_t *s)

s を -X オプションの集合として構文解析し、 PySys_GetXOptions() が返す現在のオプションマッピングに追加します。

バージョン 3.2 で追加.

PyObject *PySys_GetXOptions()

Return value: Borrowed reference.

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

バージョン 3.2 で追加.

プロセス制御

void Py_FatalError(const char *message)

致命的エラーメッセージ (fatal error message) を出力してプロセスを強制終了 (kill) します。後始末処理は行われません。この関数は、Python インタプリタを使い続けるのが危険であるような状況が検出されたとき; 例えば、オブジェクト管理が崩壊していると思われるときにのみ、呼び出されるようにしなければなりません。Unixでは、標準 C ライブラリ関数 abort() を呼び出して core を生成しようと試みます。

void Py_Exit(int status)

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

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

int Py_AtExit(void (*func)())

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