ابزارهای سیستم‌عامل

PyObject *PyOS_FSPath(PyObject *path)

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار از نسخه‌ی 3.6.

نمایش سامانه فایل‌بندی برای path را برمی‌گرداند. اگر شیء از نوع str یا bytes باشد، یک ارجاع قوی جدید برگردانده می‌شود. اگر شیء رابط os.PathLike را پیاده‌سازی کند، __fspath__() به شرط آن‌که یک شیء str یا bytes باشد، برگردانده می‌شود. در غیر این صورت، استثنای TypeError برداشته می‌شود و NULL برگردانده می‌شود.

اضافه شده در نسخه‌ی 3.6.

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

اگر پرونده‌ی ورودی/خروجی استاندارد fp با نام filename تعاملی در نظر گرفته شود، مقدار true (غیرصفر) برمی‌گرداند. این حالت برای پرونده‌هایی که isatty(fileno(fp)) در آن‌ها true است، برقرار است. اگر PyConfig.interactive غیرصفر باشد، این تابع همچنین در صورتی که اشاره‌گر filename برابر NULL باشد یا نام برابر با یکی از رشته‌های '<stdin>' یا '???' باشد، مقدار true برمی‌گرداند.

این تابع نباید پیش از مقداردهی اولیه پایتون فراخوانی شود.

void PyOS_BeforeFork()

قسمتی از ABI پایدار on platforms with fork() از نسخه‌ی 3.7.

تابعی برای آماده‌سازی برخی وضعیت‌های داخلی پیش از انشعاب فرایند. این تابع باید پیش از فراخوانی fork() یا هر تابع مشابه‌ای که از فرایند فعلی رونوشت می‌گیرد، فراخوانی شود. تنها در سیستم‌هایی که fork() در آن‌ها تعریف شده است در دسترس است.

هشدار

فراخوانی fork() در C باید فقط از نخِ «اصلی» (از مفسرِ «اصلی») انجام شود. همین موضوع برای PyOS_BeforeFork() نیز صادق است.

اضافه شده در نسخه‌ی 3.7.

void PyOS_AfterFork_Parent()

قسمتی از ABI پایدار on platforms with fork() از نسخه‌ی 3.7.

تابعی برای به‌روزرسانی برخی از وضعیت‌های داخلی پس از انشعاب فرایند. این تابع باید از فرایند والد، پس از فراخوانی fork() یا هر تابع مشابه‌ای که از فرایند فعلی رونوشت می‌گیرد، فراخوانی شود؛ صرف‌نظر از اینکه رونوشت‌گیری فرایند موفق بوده است یا خیر. تنها روی سیستم‌هایی که fork() در آن‌ها تعریف شده است در دسترس است.

هشدار

فراخوانی fork() در C باید تنها از نخ «اصلی» (از مفسر «اصلی») انجام شود. همین امر برای PyOS_AfterFork_Parent() نیز صادق است.

اضافه شده در نسخه‌ی 3.7.

void PyOS_AfterFork_Child()

قسمتی از ABI پایدار on platforms with fork() از نسخه‌ی 3.7.

تابعی برای به‌روزرسانی وضعیت داخلی مفسر پس از انشعاب یک فرایند. این تابع باید از فرایند فرزند پس از فراخوانی fork() یا هر تابع مشابه‌ای که فرایند فعلی را رونوشت می‌کند، فراخوانی شود، اگر احتمالی وجود داشته باشد که فرایند دوباره مفسر پایتون را فراخوانی کند. این تابع فقط در سیستم‌هایی که fork() در آن‌ها تعریف شده است دسترس‌پذیر است.

هشدار

فراخوانی fork() در C باید فقط از نخ «اصلی» (از مفسر «اصلی») انجام شود. همین امر برای PyOS_AfterFork_Child() نیز صادق است.

اضافه شده در نسخه‌ی 3.7.

همچنین ملاحظه نمائید

os.register_at_fork() اجازه می‌دهد توابع سفارشی پایتون را ثبت کنید تا توسط PyOS_BeforeFork()، PyOS_AfterFork_Parent() و PyOS_AfterFork_Child() فراخوانی شوند.

void PyOS_AfterFork()

قسمتی از ABI پایدار on platforms with fork().

تابعی برای به‌روزرسانی برخی از وضعیت‌های داخلی پس از انشعاب فرایند؛ اگر قرار باشد مفسر پایتون همچنان استفاده شود، این تابع باید در فرایند جدید فراخوانی شود. اگر یک پرونده اجرایی جدید در فرایند جدید بارگذاری شود، نیازی به فراخوانی این تابع نیست.

منسوخ شده از نسخه‌ی 3.7: این تابع توسط PyOS_AfterFork_Child() جایگزین شده است.

int PyOS_CheckStack()

قسمتی از ABI پایدار on platforms with USE_STACKCHECK از نسخه‌ی 3.7.

وقتی فضای پشته‌ی مفسر تمام شود، مقدار true را برمی‌گرداند. این یک بررسی قابل اعتماد است، اما تنها زمانی در دسترس است که USE_STACKCHECK تعریف شده باشد (در حال حاضر در نسخه‌هایی از ویندوز که از کامپایلر Microsoft Visual C++ استفاده می‌کنند). USE_STACKCHECK به‌صورت خودکار تعریف می‌شود؛ شما هرگز نباید این تعریف را در کد خودتان تغییر دهید.

typedef void (*PyOS_sighandler_t)(int)

قسمتی از ABI پایدار.

PyOS_sighandler_t PyOS_getsig(int i)

قسمتی از ABI پایدار.

هندلر فعلی سیگنال i را برمی‌گرداند. این تابع پوششی نازک حول sigaction() یا signal() است. این توابع را مستقیماً فراخوانی نکنید!

PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)

قسمتی از ABI پایدار.

هندلر سیگنال مربوط به سیگنال i را به h تنظیم می‌کند؛ هندلر سیگنال قدیمی را برمی‌گرداند. این تابع یک پوشش نازک حول sigaction() یا signal() است. آن توابع را مستقیماً فراخوانی نکنید!

int PyOS_InterruptOccurred(void)

قسمتی از ABI پایدار.

بررسی می‌کند که آیا سیگنال SIGINT دریافت شده است یا خیر.

اگر سیگنال SIGINT رخ داده باشد، 1 را برمی‌گرداند و پرچم سیگنال را پاک می‌کند؛ در غیر این صورت 0.

در بیشتر موارد، بهتر است به‌جای این تابع از PyErr_CheckSignals() استفاده کنید. PyErr_CheckSignals() هندلرهای مناسب سیگنال را برای همه‌ی سیگنال‌های در انتظار فراخوانی می‌کند و به کد پایتون اجازه می‌دهد سیگنال را به‌درستی مدیریت کند. این تابع فقط SIGINT را تشخیص می‌دهد و هیچ‌یک از هندلرهای سیگنال پایتون را فراخوانی نمی‌کند.

این تابع نسبت به سیگنال‌های نا‌همگام ایمن (async-signal-safe) است و نمی‌تواند شکست بخورد. فراخوان‌کننده باید یک attached thread state را در اختیار داشته باشد.

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

قسمتی از ABI پایدار از نسخه‌ی 3.7.

هشدار

این تابع نباید مستقیماً فراخوانی شود: از API PyConfig به همراه تابع PyConfig_SetBytesString() استفاده کنید که تضمین می‌کند پایتون از پیش مقداردهی اولیه شده است.

این تابع نباید پیش از پیش‌مقداردهی اولیه پایتون و پیش از پیکربندی درست locale مربوط به LC_CTYPE فراخوانی شود: تابع Py_PreInitialize() را ببینید.

یک رشته بایتی را از کدگذاری و هندلر خطای سامانه فایل‌بندی کدگشایی می‌کند. اگر هندلر خطا هندلر خطای surrogateescape باشد، بایت‌های کدگشایی‌ناپذیر به‌عنوان نویسه‌هایی در بازه U+DC80..U+DCFF کدگشایی می‌شوند؛ و اگر بتوان دنباله‌ای از بایت‌ها را به‌عنوان یک نویسه جانشین کدگشایی کرد، بایت‌ها به‌جای کدگشایی‌شدن، با استفاده از هندلر خطای surrogateescape خنثی می‌شوند.

یک اشاره‌گر به رشته نویسه پهنِ تازه تخصیص‌یافته برمی‌گرداند؛ برای آزاد کردن حافظه از PyMem_RawFree() استفاده کنید. اگر size برابر NULL نباشد، تعداد نویسه‌های پهن را بدون احتساب نویسه تهی در *size می‌نویسد.

در صورت خطای کدگشایی یا خطای تخصیص حافظه، NULL را برمی‌گرداند. اگر size برابر NULL نباشد، *size در خطای حافظه به (size_t)-1 و در خطای کدگشایی به (size_t)-2 تنظیم می‌شود.

filesystem encoding and error handler توسط PyConfig_Read() انتخاب می‌شوند: به اعضای filesystem_encoding و filesystem_errors از PyConfig مراجعه کنید.

خطاهای کدگشایی هرگز نباید رخ دهند، مگر اینکه اشکالی در کتابخانه C وجود داشته باشد.

برای کدگذاری رشته‌ی نویسه‌ها و بازگرداندن آن به یک رشته بایتی، از تابع Py_EncodeLocale() استفاده کنید.

همچنین ملاحظه نمائید

توابع PyUnicode_DecodeFSDefaultAndSize() و PyUnicode_DecodeLocaleAndSize().

اضافه شده در نسخه‌ی 3.5.

تغییر یافته در نسخه‌ی 3.7: این تابع اکنون در حالت UTF-8 پایتون از کدگذاری UTF-8 استفاده می‌کند.

تغییر یافته در نسخه‌ی 3.8: اگر PyPreConfig.legacy_windows_fs_encoding صفر باشد، این تابع اکنون در ویندوز از کدگذاری UTF-8 استفاده می‌کند؛

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

قسمتی از ABI پایدار از نسخه‌ی 3.7.

یک رشته‌ی نویسه پهن را با کدگذاری سامانه فایل‌بندی و هندلر خطا کدگذاری می‌کند. اگر هندلر خطا هندلر خطای surrogateescape باشد، نویسه‌های جانشین در بازه‌ی U+DC80..U+DCFF به بایت‌های 0x80..0xFF تبدیل می‌شوند.

یک اشاره‌گر به رشته بایتی تازه تخصیص‌یافته را برمی‌گرداند؛ برای آزاد کردن حافظه از PyMem_Free() استفاده کنید. در صورت خطای کدگذاری یا خطای تخصیص حافظه، NULL برمی‌گرداند.

اگر error_pos برابر NULL نباشد، *error_pos در صورت موفقیت به (size_t)-1 و در صورت وقوع خطای کدگذاری به اندیس نویسه نامعتبر تنظیم می‌شود.

filesystem encoding and error handler توسط PyConfig_Read() انتخاب می‌شوند: به اعضای filesystem_encoding و filesystem_errors از PyConfig مراجعه کنید.

از تابع Py_DecodeLocale() برای کدگشایی رشته بایتی و بازگرداندن آن به یک رشته نویسه پهن استفاده کنید.

هشدار

این تابع نباید پیش از پیش‌مقداردهی اولیه پایتون و پیش از پیکربندی درست locale مربوط به LC_CTYPE فراخوانی شود: تابع Py_PreInitialize() را ببینید.

همچنین ملاحظه نمائید

توابع PyUnicode_EncodeFSDefault() و PyUnicode_EncodeLocale().

اضافه شده در نسخه‌ی 3.5.

تغییر یافته در نسخه‌ی 3.7: این تابع اکنون در حالت UTF-8 پایتون از کدگذاری UTF-8 استفاده می‌کند.

تغییر یافته در نسخه‌ی 3.8: اگر PyPreConfig.legacy_windows_fs_encoding صفر باشد، این تابع اکنون در ویندوز از کدگذاری UTF-8 استفاده می‌کند.

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

مشابه fopen() است، اما path یک شیء پایتون است و در صورت خطا یک استثنا تنظیم می‌شود.

path باید یک شیء str، یک شیء bytes یا یک شیء شبه‌مسیر باشد.

در صورت موفقیت، اشاره‌گر جدید پرونده را برمی‌گرداند. در صورت خطا، یک استثنا تنظیم کرده و NULL را برمی‌گرداند.

پرونده باید توسط Py_fclose() بسته شود، نه با فراخوانی مستقیم fclose().

توصیف‌گر پرونده به‌صورت غیرقابل ارث‌بری ایجاد می‌شود (PEP 446).

فراخواننده باید attached thread state داشته باشد.

اضافه شده در نسخه‌ی 3.14.

int Py_fclose(FILE *file)

بستن پرونده‌ای که با Py_fopen() باز شده است.

در صورت موفقیت، 0 را برمی‌گرداند. در صورت خطا، EOF را برمی‌گرداند و errno برای نشان دادن خطا تنظیم می‌شود. در هر دو حالت، هر دسترسی بعدی (از جمله فراخوانی مجدد Py_fclose()) به جریان، منجر به رفتار تعریف‌نشده می‌شود.

اضافه شده در نسخه‌ی 3.14.

توابع سیستمی

این‌ها توابع کاربردی هستند که کارکردهای ماژول sys را برای کد C در دسترس قرار می‌دهند. همه‌ی آن‌ها با دیکشنری ماژول sys مربوط به نخ فعلی مفسر کار می‌کنند که در ساختار وضعیت داخلی نخ قرار دارد.

PyObject *PySys_GetObject(const char *name)

مقدار بازگشتی: مرجع امانتی. قسمتی از ABI پایدار.

شیء name را از ماژول sys بازمی‌گرداند، یا اگر وجود نداشته باشد NULL را برمی‌گرداند، بدون تنظیم استثنا.

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

قسمتی از ABI پایدار.

name را در ماژول sys برابر v قرار می‌دهد، مگر اینکه v NULL باشد که در این صورت name از ماژول sys حذف می‌شود. در صورت موفقیت 0 و در صورت خطا -1 برمی‌گرداند.

void PySys_ResetWarnOptions()

قسمتی از ABI پایدار.

بازنشانی sys.warnoptions به یک فهرست خالی. این تابع می‌تواند پیش از Py_Initialize() فراخوانی شود.

منسوخ شده از نسخه‌ی 3.13, در نسخه‌ی 3.15 حذف خواهد شد: به جای آن، sys.warnoptions و warnings.filters را پاک کنید.

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

قسمتی از ABI پایدار.

رشته خروجی توصیف‌شده توسط format را در sys.stdout می‌نویسد. هیچ استثنایی به‌وجود نمی‌آید، حتی اگر اسلایس رخ دهد (در ادامه ببینید).

format باید اندازه‌ی کل رشته‌ی خروجی قالب‌بندی‌شده را به ۱۰۰۰ بایت یا کمتر محدود کند -- پس از ۱۰۰۰ بایت، رشته‌ی خروجی بریده می‌شود. به‌طور خاص، این بدان معناست که نباید هیچ قالب "%s" بدون محدودیت وجود داشته باشد؛ این قالب‌ها باید با استفاده از "%.<N>s" محدود شوند که در آن <N> عددی دهدهی است که به‌گونه‌ای محاسبه می‌شود که <N> به‌علاوه‌ی حداکثر اندازه‌ی سایر متن‌های قالب‌بندی‌شده از ۱۰۰۰ بایت بیشتر نشود. همچنین مراقب "%f" باشید که می‌تواند برای اعداد بسیار بزرگ صدها رقم چاپ کند.

اگر مشکلی رخ دهد یا sys.stdout تنظیم نشده باشد، پیام قالب‌بندی‌شده به stdout واقعی (در سطح C) نوشته می‌شود.

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

قسمتی از ABI پایدار.

مانند PySys_WriteStdout() است، اما به جای آن به sys.stderr یا stderr می‌نویسد.

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

قسمتی از ABI پایدار.

تابعی مشابه PySys_WriteStdout() است، اما پیام را با استفاده از PyUnicode_FromFormatV() قالب‌بندی می‌کند و پیام را به طولی دلخواه کوتاه نمی‌کند.

اضافه شده در نسخه‌ی 3.2.

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

قسمتی از ABI پایدار.

مانند PySys_FormatStdout()، اما به‌جای آن به sys.stderr یا stderr می‌نویسد.

اضافه شده در نسخه‌ی 3.2.

PyObject *PySys_GetXOptions()

مقدار بازگشتی: مرجع امانتی. قسمتی از ABI پایدار از نسخه‌ی 3.7.

دیکشنری فعلی گزینه‌های -X را برمی‌گرداند، مشابه sys._xoptions. در صورت خطا، NULL برگردانده می‌شود و یک استثنا تنظیم می‌شود.

اضافه شده در نسخه‌ی 3.2.

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

قسمتی از ABI پایدار از نسخه‌ی 3.13.

یک رویداد حسابرسی را همراه با هر قلاب فعال برپ می‌کند. در صورت موفقیت صفر و در صورت شکست مقدار غیرصفر به همراه استثنای تنظیم‌شده برمی‌گرداند.

آرگومان رشته‌ای event نباید NULL باشد.

اگر قلابی افزوده شده باشد، از format و سایر آرگومان‌ها برای ساخت تاپلی که پاس داده شود استفاده خواهد شد. به جز N، همان نویسه‌های قالب که در Py_BuildValue() استفاده می‌شوند، در دسترس هستند. اگر مقدار ساخته‌شده یک تاپل نباشد، به یک تاپل تک‌عنصری افزوده خواهد شد.

از گزینه‌ی قالب N نباید استفاده شود. این گزینه یک ارجاع را مصرف می‌کند، اما از آنجا که هیچ راهی برای دانستن اینکه آیا آرگومان‌های این تابع مصرف خواهند شد یا خیر وجود ندارد، استفاده از آن ممکن است باعث نشت ارجاع شود.

توجه داشته باشید که نویسه‌های قالب # همیشه باید به‌عنوان Py_ssize_t در نظر گرفته شوند، صرف‌نظر از اینکه PY_SSIZE_T_CLEAN تعریف‌شده باشد یا خیر.

sys.audit() همین کار را از درون کد پایتون انجام می‌دهد.

همچنین PySys_AuditTuple() را ببینید.

اضافه شده در نسخه‌ی 3.8.

تغییر یافته در نسخه‌ی 3.8.2: نویسه‌های قالب # به Py_ssize_t نیاز دارند. پیش‌تر، یک هشدار منسوخ‌شدگی اجتناب‌ناپذیر اکسپورت می‌شد.

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

قسمتی از ABI پایدار از نسخه‌ی 3.13.

مشابه PySys_Audit() است، اما آرگومان‌ها را به‌صورت یک شیء پایتون می‌گذرد. args باید یک tuple باشد. برای عدم گذراندن آرگومان، args می‌تواند NULL باشد.

اضافه شده در نسخه‌ی 3.13.

int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)

فراخوانی‌پذیر hook را به فهرست قلاب‌های حسابرسی فعال الحاق می‌کند. در صورت موفقیت صفر و در صورت شکست مقدار غیرصفر برمی‌گرداند. اگر ران‌تایم مقداردهی اولیه شده باشد، در صورت شکست خطایی نیز تنظیم می‌کند. قلاب‌هایی که از طریق این API افزوده می‌شوند، برای تمام مفسرهای ایجادشده توسط ران‌تایم فراخوانی می‌شوند.

اشاره‌گر userData به تابع قلاب پاس داده می‌شود. از آنجا که توابع قلاب ممکن است از ران‌تایم‌های مختلف فراخوانی شوند، این اشاره‌گر نباید مستقیماً به وضعیت پایتون اشاره کند.

فراخوانی این تابع پیش از Py_Initialize() ایمن است. هنگامی که پس از مقداردهی اولیه ران‌تایم فراخوانی شود، قلاب‌های حسابرسی موجود مطلع می‌شوند و ممکن است عملیات را با ایجاد خطایی که زیرکلاسی از Exception است، به‌صورت بی‌صدا لغو کنند (خطاهای دیگر سرکوب نخواهند شد).

تابع قلاب همیشه با یک وضعیت نخ پیوست‌شده توسط مفسر پایتونی که رویداد را ایجاد کرده است، فراخوانی می‌شود.

برای شرح مفصل حسابرسی به PEP 578 مراجعه کنید. توابعی در ران‌تایم و کتابخانه استاندارد که رویداد ایجاد می‌کنند در جدول رویدادهای حسابرسی فهرست شده‌اند. جزئیات در مستندات هر تابع آمده است.

اگر مفسر راه‌اندازی‌شده باشد، این تابع رویداد حسابرسی sys.addaudithook را بدون هیچ آرگومانی ایجاد می‌کند. اگر هر یک از قلاب‌های موجود استثنایی مشتق‌شده از Exception ایجاد کند، قلاب جدید اضافه نخواهد شد و استثنا پاک می‌شود. در نتیجه، فراخوانندگان نمی‌توانند فرض کنند که قلاب‌شان اضافه شده است، مگر آنکه کنترل تمام قلاب‌های موجود را در دست داشته باشند.

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

نوع تابع قلاب. event آرگومان رویداد از نوع رشته‌ی C است که به PySys_Audit() یا PySys_AuditTuple() ارسال می‌شود. تضمین می‌شود که args یک PyTupleObject باشد. userData آرگومانی است که به PySys_AddAuditHook() ارسال می‌شود.

اضافه شده در نسخه‌ی 3.8.

کنترل فرایند

void Py_FatalError(const char *message)

قسمتی از ABI پایدار.

یک پیام خطای مهلک چاپ می‌کند و فرایند را می‌کشد. هیچ پاک‌سازی انجام نمی‌شود. این تابع تنها زمانی باید فراخوانی شود که شرایطی تشخیص داده شود که ادامه استفاده از مفسر پایتون را خطرناک سازد؛ برای مثال، زمانی که به نظر می‌رسد مدیریت شیء دچار خرابی شده باشد. در یونیکس، تابع abort() از کتابخانه استاندارد C فراخوانی می‌شود که سعی خواهد کرد یک پرونده core تولید کند.

تابع Py_FatalError() با ماکرویی جایگزین می‌شود که نام تابع فعلی را به‌طور خودکار ثبت می‌کند، مگر آنکه ماکروی Py_LIMITED_API تعریف شده باشد.

تغییر یافته در نسخه‌ی 3.9: نام تابع را به‌طور خودکار ثبت می‌کند.

void Py_Exit(int status)

قسمتی از ABI پایدار.

از فرایند فعلی خارج می‌شود. این تابع Py_FinalizeEx() را فراخوانی می‌کند و سپس تابع exit(status) کتابخانه‌ی استاندارد C را فراخوانی می‌کند. اگر Py_FinalizeEx() خطا را نشان دهد، وضعیت خروج به ۱۲۰ تنظیم می‌شود.

تغییر یافته در نسخه‌ی 3.6: خطاهای ناشی از نهایی‌سازی دیگر نادیده گرفته نمی‌شوند.

int Py_AtExit(void (*func)())

قسمتی از ABI پایدار.

یک تابع پاک‌سازی ثبت کنید تا توسط Py_FinalizeEx() فراخوانی شود. تابع پاک‌سازی بدون هیچ آرگومانی فراخوانی می‌شود و نباید مقداری برگرداند. حداکثر ۳۲ تابع پاک‌سازی را می‌توان ثبت کرد. وقتی ثبت با موفقیت انجام شود، Py_AtExit() مقدار 0 را برمی‌گرداند؛ در صورت شکست، مقدار -1 را برمی‌گرداند. آخرین تابع پاک‌سازی ثبت‌شده، نخست فراخوانی می‌شود. هر تابع پاک‌سازی حداکثر یک‌بار فراخوانی خواهد شد. از آنجا که نهایی‌سازی داخلی پایتون پیش از تابع پاک‌سازی کامل شده خواهد بود، func نباید هیچ‌یک از APIهای پایتون را فراخوانی کند.

همچنین ملاحظه نمائید

PyUnstable_AtExit() برای گذراندن آرگومان void *data.