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

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() を参照してください。