Tiện ích hệ điều hành

PyObject *PyOS_FSPath(PyObject *path)

Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định kể từ phiên bản 3.6.

Trả về biểu diễn hệ thống tệp cho path. Nếu đối tượng là đối tượng str hoặc bytes thì một strong reference mới sẽ được trả về. Nếu đối tượng triển khai giao diện os.PathLike thì __fspath__() sẽ được trả về miễn là nó là đối tượng str hoặc bytes. Nếu không thì TypeError được nâng lên và NULL được trả về.

Added in version 3.6.

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

Trả về true (khác 0) nếu tệp I/O tiêu chuẩn fp có tên filename được coi là có tính tương tác. Đây là trường hợp của các tệp mà isatty(fileno(fp)) là đúng. Nếu PyConfig.interactive khác 0, hàm này cũng trả về true nếu con trỏ filename là NULL hoặc nếu tên bằng một trong các chuỗi '<stdin>' hoặc '???'.

Hàm này không được gọi trước khi Python được khởi tạo.

void PyOS_BeforeFork()

Một phần của ABI ổn định on platforms with fork() kể từ phiên bản 3.7.

Chức năng chuẩn bị một số trạng thái nội bộ trước khi phân nhánh quy trình. Điều này nên được gọi trước khi gọi fork() hoặc bất kỳ chức năng tương tự nào sao chép quy trình hiện tại. Chỉ khả dụng trên các hệ thống có xác định fork().

Cảnh báo

Cuộc gọi C fork() chỉ nên được thực hiện từ "main" thread (của "main" interpreter). Điều này cũng đúng với PyOS_BeforeFork().

Added in version 3.7.

void PyOS_AfterFork_Parent()

Một phần của ABI ổn định on platforms with fork() kể từ phiên bản 3.7.

Chức năng cập nhật một số trạng thái nội bộ sau một quá trình rẽ nhánh. Điều này phải được gọi từ quy trình gốc sau khi gọi fork() hoặc bất kỳ chức năng tương tự nào sao chép quy trình hiện tại, bất kể việc nhân bản quy trình có thành công hay không. Chỉ khả dụng trên các hệ thống có xác định fork().

Cảnh báo

Cuộc gọi C fork() chỉ nên được thực hiện từ "main" thread (của "main" interpreter). Điều này cũng đúng với PyOS_AfterFork_Parent().

Added in version 3.7.

void PyOS_AfterFork_Child()

Một phần của ABI ổn định on platforms with fork() kể từ phiên bản 3.7.

Chức năng cập nhật trạng thái trình thông dịch nội bộ sau khi phân nhánh quy trình. Điều này phải được gọi từ quy trình con sau khi gọi fork() hoặc bất kỳ chức năng tương tự nào sao chép quy trình hiện tại, nếu có bất kỳ khả năng nào quy trình sẽ gọi lại vào trình thông dịch Python. Chỉ khả dụng trên các hệ thống có xác định fork().

Cảnh báo

Cuộc gọi C fork() chỉ nên được thực hiện từ "main" thread (của "main" interpreter). Điều này cũng đúng với PyOS_AfterFork_Child().

Added in version 3.7.

Xem thêm

os.register_at_fork() cho phép đăng ký các hàm Python tùy chỉnh để được gọi bởi PyOS_BeforeFork(), PyOS_AfterFork_Parent() và PyOS_AfterFork_Child().

void PyOS_AfterFork()

Một phần của ABI ổn định on platforms with fork().

Chức năng cập nhật một số trạng thái nội bộ sau một quá trình phân nhánh; cái này sẽ được gọi trong quy trình mới nếu trình thông dịch Python sẽ tiếp tục được sử dụng. Nếu một tệp thực thi mới được tải vào quy trình mới thì không cần phải gọi hàm này.

Sắp loại bỏ từ phiên bản 3.7: Chức năng này được thay thế bởi PyOS_AfterFork_Child().

int PyOS_CheckStack()

Một phần của ABI ổn định on platforms with USE_STACKCHECK kể từ phiên bản 3.7.

Trả về true khi trình thông dịch hết dung lượng ngăn xếp. Đây là một cách kiểm tra đáng tin cậy nhưng chỉ khả dụng khi USE_STACKCHECK được xác định (hiện có trên một số phiên bản Windows nhất định sử dụng trình biên dịch Microsoft Visual C++). USE_STACKCHECK sẽ được xác định tự động; bạn không bao giờ nên thay đổi định nghĩa trong mã của riêng bạn.

typedef void (*PyOS_sighandler_t)(int)

Một phần của ABI ổn định.

PyOS_sighandler_t PyOS_getsig(int i)

Một phần của ABI ổn định.

Trả về bộ xử lý tín hiệu hiện tại cho tín hiệu i. Đây là một lớp bọc mỏng xung quanh sigaction() hoặc signal(). Đừng gọi trực tiếp các chức năng đó!

PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)

Một phần của ABI ổn định.

Đặt bộ xử lý tín hiệu cho tín hiệu i thành h; trả lại bộ xử lý tín hiệu cũ. Đây là một lớp bọc mỏng xung quanh sigaction() hoặc signal(). Đừng gọi trực tiếp các chức năng đó!

int PyOS_InterruptOccurred(void)

Một phần của ABI ổn định.

Kiểm tra xem tín hiệu SIGINT đã được nhận chưa.

Trả về 1 nếu xảy ra SIGINT và xóa cờ tín hiệu hoặc 0 nếu ngược lại.

Trong hầu hết các trường hợp, bạn nên ưu tiên PyErr_CheckSignals() hơn chức năng này. PyErr_CheckSignals() gọi các trình xử lý tín hiệu thích hợp cho tất cả các tín hiệu đang chờ xử lý, cho phép mã Python xử lý tín hiệu đúng cách. Hàm này chỉ phát hiện SIGINT và không gọi bất kỳ trình xử lý tín hiệu Python nào.

Chức năng này không đồng bộ-tín hiệu-an toàn và chức năng này không thể bị lỗi. Người gọi phải giữ attached thread state.

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

Một phần của ABI ổn định kể từ phiên bản 3.7.

Cảnh báo

Không nên gọi trực tiếp hàm này: sử dụng PyConfig API với hàm PyConfig_SetBytesString() để đảm bảo rằng Python is preinitialized.

Hàm này không được gọi trước Python is preinitialized và để ngôn ngữ LC_CTYPE được cấu hình đúng cách: xem hàm Py_PreInitialize().

Giải mã một chuỗi byte từ filesystem encoding and error handler. Nếu trình xử lý lỗi là surrogateescape error handler, các byte không thể giải mã được sẽ được giải mã thành các ký tự trong phạm vi U+DC80..U+DCFF; và nếu một chuỗi byte có thể được giải mã dưới dạng ký tự thay thế thì các byte sẽ được thoát bằng cách sử dụng trình xử lý lỗi thay thế thay vì giải mã chúng.

Trả về con trỏ tới chuỗi ký tự rộng mới được phân bổ, sử dụng PyMem_RawFree() để giải phóng bộ nhớ. Nếu kích thước không phải là NULL thì ghi số ký tự rộng không bao gồm ký tự null vào *size

Trả về NULL khi xảy ra lỗi giải mã hoặc lỗi cấp phát bộ nhớ. Nếu size không phải là NULL, *size được đặt thành (size_t)-1 do lỗi bộ nhớ hoặc được đặt thành (size_t)-2 do lỗi giải mã.

Zz000zz được chọn bởi PyConfig_Read(): xem các thành viên filesystem_encoding và filesystem_errors của PyConfig.

Lỗi giải mã sẽ không bao giờ xảy ra, trừ khi có lỗi trong thư viện C.

Sử dụng hàm Py_EncodeLocale() để mã hóa chuỗi ký tự trở lại chuỗi byte.

Xem thêm

Các chức năng PyUnicode_DecodeFSDefaultAndSize() và PyUnicode_DecodeLocaleAndSize().

Added in version 3.5.

Thay đổi trong phiên bản 3.7: Hàm hiện sử dụng mã hóa UTF-8 trong Python UTF-8 Mode.

Thay đổi trong phiên bản 3.8: Hàm hiện sử dụng mã hóa UTF-8 trên Windows nếu PyPreConfig.legacy_windows_fs_encoding bằng 0;

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

Một phần của ABI ổn định kể từ phiên bản 3.7.

Mã hóa chuỗi ký tự rộng thành filesystem encoding and error handler. Nếu trình xử lý lỗi là surrogateescape error handler, các ký tự thay thế trong phạm vi U+DC80..U+DCFF được chuyển đổi thành byte 0x80..0xFF.

Trả về con trỏ tới chuỗi byte mới được phân bổ, sử dụng PyMem_Free() để giải phóng bộ nhớ. Trả về NULL về lỗi mã hóa hoặc lỗi cấp phát bộ nhớ.

Nếu error_pos không phải là NULL, *error_pos được đặt thành (size_t)-1 nếu thành công hoặc được đặt thành chỉ mục của ký tự không hợp lệ khi xảy ra lỗi mã hóa.

Zz000zz được chọn bởi PyConfig_Read(): xem các thành viên filesystem_encoding và filesystem_errors của PyConfig.

Sử dụng hàm Py_DecodeLocale() để giải mã chuỗi byte trở lại chuỗi ký tự rộng.

Cảnh báo

Hàm này không được gọi trước Python is preinitialized và để ngôn ngữ LC_CTYPE được cấu hình đúng cách: xem hàm Py_PreInitialize().

Xem thêm

Các chức năng PyUnicode_EncodeFSDefault() và PyUnicode_EncodeLocale().

Added in version 3.5.

Thay đổi trong phiên bản 3.7: Hàm hiện sử dụng mã hóa UTF-8 trong Python UTF-8 Mode.

Thay đổi trong phiên bản 3.8: Hàm hiện sử dụng mã hóa UTF-8 trên Windows nếu PyPreConfig.legacy_windows_fs_encoding bằng 0.

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

Tương tự như fopen(), nhưng path là một đối tượng Python và một ngoại lệ được đặt do lỗi.

path phải là đối tượng str, đối tượng bytes hoặc path-like object.

Khi thành công, trả về con trỏ tệp mới. Nếu có lỗi, hãy đặt ngoại lệ và trả về NULL.

Tệp phải được đóng bằng Py_fclose() thay vì gọi trực tiếp fclose().

Bộ mô tả tệp được tạo không thể kế thừa (PEP 446).

Người gọi phải có attached thread state.

Added in version 3.14.

int Py_fclose(FILE *file)

Đóng file đã được mở bởi Py_fopen().

Nếu thành công, hãy trả về 0. Khi có lỗi, trả về EOF và errno được đặt để báo lỗi. Trong cả hai trường hợp, bất kỳ quyền truy cập nào khác (bao gồm cả lệnh gọi khác tới Py_fclose()) vào luồng đều dẫn đến hành vi không xác định.

Added in version 3.14.

Chức năng hệ thống

Đây là các hàm tiện ích giúp mã C có thể truy cập chức năng từ mô-đun sys. Tất cả đều hoạt động với lệnh sys của mô-đun trình thông dịch hiện tại, được chứa trong cấu trúc trạng thái luồng bên trong.

PyObject *PySys_GetObject(const char *name)

Giá trị trả về: Tham chiếu mượn. Một phần của ABI ổn định.

Trả về đối tượng name từ mô-đun sys hoặc NULL nếu nó không tồn tại mà không đặt ngoại lệ.

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

Một phần của ABI ổn định.

Đặt name trong mô-đun sys thành v trừ khi v là NULL, trong trường hợp đó name bị xóa khỏi mô-đun sys. Trả về 0 nếu thành công, -1 nếu có lỗi.

void PySys_ResetWarnOptions()

Một phần của ABI ổn định.

Đặt lại sys.warnoptions về danh sách trống. Hàm này có thể được gọi trước Py_Initialize().

Không được dùng nữa kể từ phiên bản 3.13, sẽ bị xóa trong phiên bản 3.15: Thay vào đó hãy xóa sys.warnoptions và warnings.filters.

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

Một phần của ABI ổn định.

Viết chuỗi đầu ra được mô tả bởi format vào sys.stdout. Không có trường hợp ngoại lệ nào được đưa ra, ngay cả khi xảy ra hiện tượng cắt bớt (xem bên dưới).

format phải giới hạn tổng kích thước của chuỗi đầu ra được định dạng ở mức 1000 byte trở xuống -- sau 1000 byte, chuỗi đầu ra sẽ bị cắt bớt. Đặc biệt, điều này có nghĩa là sẽ không có định dạng "%s" không hạn chế nào xảy ra; những điều này nên được giới hạn bằng cách sử dụng "%.<N>s" trong đó <N> là số thập phân được tính sao cho <N> cộng với kích thước tối đa của văn bản được định dạng khác không vượt quá 1000 byte. Ngoài ra, hãy chú ý đến "%f", có thể in hàng trăm chữ số cho những số rất lớn.

Nếu xảy ra sự cố hoặc sys.stdout không được đặt, thông báo được định dạng sẽ được ghi vào stdout thực (cấp C).

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

Một phần của ABI ổn định.

Như PySys_WriteStdout(), nhưng thay vào đó hãy viết vào sys.stderr hoặc stderr.

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

Một phần của ABI ổn định.

Chức năng tương tự như PySys_WriteStdout() nhưng định dạng tin nhắn bằng PyUnicode_FromFormatV() và không cắt bớt tin nhắn theo độ dài tùy ý.

Added in version 3.2.

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

Một phần của ABI ổn định.

Như PySys_FormatStdout(), nhưng thay vào đó hãy viết vào sys.stderr hoặc stderr.

Added in version 3.2.

PyObject *PySys_GetXOptions()

Giá trị trả về: Tham chiếu mượn. Một phần của ABI ổn định kể từ phiên bản 3.7.

Trả về từ điển hiện tại của các tùy chọn -X, tương tự như sys._xoptions. Nếu có lỗi, NULL được trả về và một ngoại lệ được đặt.

Added in version 3.2.

int PySys_Audit(const char *event, const char *format, ...)

Một phần của ABI ổn định kể từ phiên bản 3.13.

Đưa ra một sự kiện kiểm tra với bất kỳ hook hoạt động nào. Trả về số 0 nếu thành công và khác 0 với ngoại lệ được đặt là thất bại.

Đối số chuỗi event không được là NULL.

Nếu bất kỳ hook nào đã được thêm vào, format và các đối số khác sẽ được sử dụng để tạo một bộ dữ liệu cần chuyển. Ngoài N, các ký tự định dạng tương tự như được sử dụng trong Py_BuildValue() đều có sẵn. Nếu giá trị được xây dựng không phải là một bộ dữ liệu, nó sẽ được thêm vào một bộ dữ liệu một phần tử.

Không được sử dụng tùy chọn định dạng N. Nó sử dụng một tham chiếu, nhưng vì không có cách nào để biết liệu các đối số của hàm này có được sử dụng hay không nên việc sử dụng nó có thể gây rò rỉ tham chiếu.

Lưu ý rằng các ký tự định dạng # phải luôn được coi là Py_ssize_t, bất kể PY_SSIZE_T_CLEAN có được xác định hay không.

sys.audit() thực hiện chức năng tương tự từ mã Python.

Xem thêm PySys_AuditTuple().

Added in version 3.8.

Thay đổi trong phiên bản 3.8.2: Yêu cầu Py_ssize_t cho các ký tự định dạng #. Trước đó, một cảnh báo không thể tránh khỏi về việc ngừng sử dụng đã được đưa ra.

int PySys_AuditTuple(const char *event, PyObject *args)

Một phần của ABI ổn định kể từ phiên bản 3.13.

Tương tự như PySys_Audit(), nhưng truyền đối số dưới dạng đối tượng Python. args phải là tuple. Để không có đối số, args có thể là NULL.

Added in version 3.13.

int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)

Thêm hook có thể gọi được vào danh sách các hook kiểm tra đang hoạt động. Trả về số 0 nếu thành công và khác 0 nếu thất bại. Nếu thời gian chạy đã được khởi tạo, hãy đặt lỗi do lỗi. Các hook được thêm thông qua API này được gọi cho tất cả các trình thông dịch được tạo bởi thời gian chạy.

Con trỏ userData được truyền vào hàm hook. Vì các hàm hook có thể được gọi từ các thời gian chạy khác nhau nên con trỏ này không được tham chiếu trực tiếp đến trạng thái Python.

Chức năng này an toàn để gọi trước Py_Initialize(). Khi được gọi sau khi khởi tạo thời gian chạy, các móc kiểm tra hiện có sẽ được thông báo và có thể âm thầm hủy bỏ thao tác bằng cách đưa ra lỗi được phân lớp từ Exception (các lỗi khác sẽ không bị tắt tiếng).

Hàm hook luôn được gọi bằng attached thread state bởi trình thông dịch Python đã phát sinh sự kiện.

Xem PEP 578 để biết mô tả chi tiết về kiểm tra. Các hàm trong thời gian chạy và thư viện chuẩn tạo ra các sự kiện được liệt kê trong audit events table. Chi tiết có trong tài liệu của từng chức năng.

Nếu trình thông dịch được khởi tạo, hàm này sẽ tạo ra một sự kiện kiểm tra sys.addaudithook mà không có đối số. Nếu bất kỳ hook hiện có nào đưa ra một ngoại lệ bắt nguồn từ Exception, hook mới sẽ không được thêm vào và ngoại lệ sẽ bị xóa. Kết quả là người gọi không thể cho rằng hook của họ đã được thêm vào trừ khi họ kiểm soát tất cả các hook hiện có.

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

Loại hàm hook. event là đối số sự kiện chuỗi C được truyền cho PySys_Audit() hoặc PySys_AuditTuple(). args được đảm bảo là PyTupleObject. userData là đối số được truyền cho PySys_AddAuditHook().

Added in version 3.8.

Kiểm soát quá trình

void Py_FatalError(const char *message)

Một phần của ABI ổn định.

In một thông báo lỗi nghiêm trọng và hủy quá trình. Không có việc dọn dẹp nào được thực hiện. Hàm này chỉ nên được gọi khi phát hiện thấy một điều kiện có thể gây nguy hiểm cho việc tiếp tục sử dụng trình thông dịch Python; ví dụ: khi quản trị đối tượng có vẻ bị hỏng. Trên Unix, hàm thư viện C tiêu chuẩn abort() được gọi sẽ cố gắng tạo tệp core.

Hàm Py_FatalError() được thay thế bằng macro tự động ghi tên của hàm hiện tại, trừ khi macro Py_LIMITED_API được xác định.

Thay đổi trong phiên bản 3.9: Đăng nhập tên chức năng tự động.

void Py_Exit(int status)

Một phần của ABI ổn định.

Thoát khỏi quá trình hiện tại. Điều này gọi Py_FinalizeEx() và sau đó gọi hàm thư viện C tiêu chuẩn exit(status). Nếu Py_FinalizeEx() báo lỗi, trạng thái thoát được đặt thành 120.

Thay đổi trong phiên bản 3.6: Lỗi từ quá trình hoàn thiện không còn bị bỏ qua.

int Py_AtExit(void (*func)())

Một phần của ABI ổn định.

Đăng ký chức năng dọn dẹp để Py_FinalizeEx() gọi. Hàm dọn dẹp sẽ được gọi mà không có đối số và không trả về giá trị nào. Có thể đăng ký tối đa 32 chức năng dọn dẹp. Khi đăng ký thành công, Py_AtExit() trả về 0; nếu thất bại, nó trả về -1. Chức năng dọn dẹp được đăng ký cuối cùng sẽ được gọi đầu tiên. Mỗi chức năng dọn dẹp sẽ được gọi tối đa một lần. Vì quá trình hoàn thiện nội bộ của Python sẽ hoàn tất trước chức năng dọn dẹp nên func sẽ không gọi API Python nào.

Xem thêm

PyUnstable_AtExit() để truyền đối số void *data.