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

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

Decode a byte string from the filesystem encoding with the surrogateescape error handler.

Undecodable bytes are decoded as characters in range U+DC80..U+DCFF. If a byte sequence can be decoded as a surrogate character, escape the bytes using the surrogateescape error handler instead of decoding them.

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

On memory allocation failure, set *size to (size_t)-1 and return NULL.

On decode error, set *size to (size_t)-2 and return NULL. Decoding errors should never happen, unless there is a bug in the C library.

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

キャラクター文字列をバイト文字列に戻すには 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 より).

Encode a wide character string to the filesystem encoding with the surrogateescape error handler. Surrogate characters in the range U+DC80..U+DCFF are encoded to bytes 0x80..0xFF.

Return a pointer to a newly allocated byte string, use PyMem_Free() to free the memory.

On memory allocation failure, set *error_pos to (size_t)-1 and return NULL.

On encoding error, set *error_pos to the index of the first unencodable character and return NULL.

ファイルシステムのエンコーディングとエラーハンドラ は 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 の状態を参照すべきではありません。

This function is safe to call before Py_Initialize(). When called after runtime initialization, existing audit hooks are notified and may silently abort the operation by raising an error subclassed from RuntimeError (other errors will not be silenced).

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

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

If the interpreter is initialized, this function raises an auditing event sys.addaudithook with no arguments. If any existing hooks raise an exception derived from RuntimeError, the new hook will not be added and the exception is cleared. As a result, callers cannot assume that their hook has been added unless they control all existing hooks.

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.

バージョン 3.8.1 で変更: Exceptions derived from Exception but not RuntimeError are no longer suppressed.

プロセス制御

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