os --- رابط‌های متفرقه سیستم‌عامل

کد منبع: Lib/os.py

این ماژول یک روش قابل‌حمل برای استفاده از قابلیت‌های وابسته به سیستم‌عامل فراهم می‌کند. اگر فقط می‌خواهید یک پرونده را بخوانید یا بنویسید، open() را ببینید، اگر می‌خواهید مسیرها را دستکاری کنید، ماژول os.path را ببینید، و اگر می‌خواهید تمام سطرهای همه پرونده‌های خط فرمان را بخوانید، ماژول fileinput را ببینید. برای ایجاد پرونده‌ها و پوشه‌های موقت ماژول tempfile را ببینید، و برای مدیریت پرونده‌ها و پوشه‌ها در سطح بالا ماژول shutil را ببینید.

نکاتی درباره‌ی دسترس‌پذیری این توابع:

  • طراحی همه ماژول‌های توکار وابسته به سیستم‌عامل پایتون به‌گونه‌ای است که تا زمانی که عملکرد یکسانی در دسترس باشد، از رابط یکسانی استفاده می‌کنند؛ برای مثال، تابع os.stat(path) اطلاعات stat درباره path را در قالب یکسانی برمی‌گرداند (که اتفاقاً از رابط POSIX سرچشمه گرفته است).

  • افزونه‌های مختص یک سیستم‌عامل خاص نیز از طریق ماژول os در دسترس هستند، اما استفاده از آن‌ها البته تهدیدی برای قابلیت حمل محسوب می‌شود.

  • همه‌ی توابعی که مسیر یا نام پرونده را می‌پذیرند، هم اشیاء bytes و هم اشیاء رشته را می‌پذیرند و اگر مسیر یا نام پرونده‌ای برگردانده شود، نتیجه شیءای از همان نوع خواهد بود.

  • در VxWorks، از os.popen، os.fork، os.execv و os.spawn*p* پشتیبانی نمی‌شود.

  • در سکوهای WebAssembly، اندروید و iOS، بخش‌های بزرگی از ماژول os در دسترس نیستند یا رفتار متفاوتی دارند. APIهای مربوط به فرایندها (برای مثال fork()، execve()) و منابع (برای مثال nice()) در دسترس نیستند. موارد دیگر مانند getuid() و getpid() یا شبیه‌سازی می‌شوند یا استاب هستند. سکوهای WebAssembly همچنین پشتیبانی از سیگنال‌ها (برای مثال kill()، wait()) را ندارند.

توجه

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

exception os.error

نام مستعاری برای استثنای توکار OSError.

os.name

نام ماژول ایمپورت‌شده وابسته به سیستم‌عامل. نام‌های زیر در حال حاضر ثبت شده‌اند: 'posix'، 'nt'، 'java'.

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

sys.platform دانه‌بندی ریزتری دارد. os.uname() اطلاعات نسخه‌ی وابسته به سیستم را ارائه می‌دهد.

ماژول platform بررسی‌های دقیقی برای هویت سیستم ارائه می‌دهد.

نام پرونده‌ها، آرگومان‌های خط فرمان و متغیرهای محیطی

در پایتون، نام پرونده‌ها، آرگومان‌های خط فرمان و متغیرهای محیطی با استفاده از نوع رشته نمایش داده می‌شوند. در برخی سیستم‌ها، کدگشایی این رشته‌ها به بایت‌ها و از بایت‌ها پیش از انتقال آن‌ها به سیستم‌عامل ضروری است. پایتون برای انجام این تبدیل از filesystem encoding and error handler استفاده می‌کند (به sys.getfilesystemencoding() مراجعه کنید).

کدگذاری و مدیریت خطای سامانه فایل‌بندی در هنگام راه‌اندازی پایتون توسط تابع PyConfig_Read() پیکربندی می‌شوند: اعضای filesystem_encoding و filesystem_errors از PyConfig را ببینید.

تغییر یافته در نسخه‌ی 3.1: در برخی سیستم‌ها، تبدیل با استفاده از کدگذاری سامانه فایل‌بندی ممکن است شکست بخورد. در این صورت، پایتون از هندلر خطای کدگذاری surrogateescape استفاده می‌کند، به این معنا که بایت‌های غیرقابل کدگشایی در کدگشایی با یک نویسه یونیکد U+DCxx جایگزین می‌شوند و این نویسه‌ها دوباره در کدگذاری به بایت اصلی تبدیل می‌شوند.

کدگذاری سامانه فایل‌بندی باید تضمین کند که کدگشایی تمام بایت‌های کمتر از ۱۲۸ با موفقیت انجام می‌شود. اگر کدگذاری سامانه فایل‌بندی نتواند این تضمین را فراهم کند، توابع API می‌توانند UnicodeError را پرتاب کنند.

همچنین locale encoding را ببینید.

حالت UTF-8 پایتون

اضافه شده در نسخه‌ی 3.7: برای جزئیات بیشتر به PEP 540 مراجعه کنید.

حالت UTF-8 پایتون، locale encoding را نادیده می‌گیرد و استفاده از کدگذاری UTF-8 را اجباری می‌کند:

  • از UTF-8 به‌عنوان کدگذاری سامانه فایل‌بندی استفاده کنید.

  • sys.getfilesystemencoding() 'utf-8' را برمی‌گرداند.

  • locale.getpreferredencoding() 'utf-8' را بازمی‌گرداند (آرگومان do_setlocale هیچ تأثیری ندارد).

  • sys.stdin، sys.stdout و sys.stderr همگی برای کدگذاری متن خود از UTF-8 استفاده می‌کنند، با فعال بودن surrogateescape به‌عنوان هندلر خطا برای sys.stdin و sys.stdout (sys.stderr همچنان از backslashreplace استفاده می‌کند، همان‌طور که در حالت پیش‌فرض آگاه از locale نیز استفاده می‌کند)

  • در یونیکس، os.device_encoding() به‌جای کدگذاری دستگاه، 'utf-8' را برمی‌گرداند.

توجه داشته باشید که تنظیمات جریان استاندارد در حالت UTF-8 را می‌توان با PYTHONIOENCODING بازنویسی کرد (درست همان‌طور که در حالت پیش‌فرض آگاه از locale نیز امکان‌پذیر است).

در نتیجه تغییرات در آن APIهای سطح پایین‌تر، سایر APIهای سطح بالاتر نیز رفتارهای پیش‌فرض متفاوتی نشان می‌دهند:

  • آرگومان‌های خط فرمان، متغیرهای محیطی و نام پرونده‌ها با استفاده از کدگذاری UTF-8 به متن کدگشایی می‌شوند.

  • os.fsdecode() و os.fsencode() از کدگذاری UTF-8 استفاده می‌کنند.

  • open()، io.open() و codecs.open() به‌طور پیش‌فرض از کدگذاری UTF-8 استفاده می‌کنند. با این حال، آن‌ها همچنان به‌طور پیش‌فرض از هندلر خطای سخت‌گیرانه (strict) استفاده می‌کنند، به‌طوری که تلاش برای باز کردن یک پرونده دودویی در حالت متنی احتمالاً به‌جای تولید داده‌های بی‌معنی، منجر به پرتاب استثنایی می‌شود.

اگر locale LC_CTYPE در زمان راه‌اندازی پایتون C یا POSIX باشد، حالت UTF-8 پایتون فعال می‌شود (به تابع PyConfig_Read() مراجعه کنید).

می‌توان آن را با استفاده از گزینه‌ی خط فرمان -X utf8 و متغیر محیطی PYTHONUTF8 فعال یا غیرفعال کرد.

اگر متغیر محیطی PYTHONUTF8 اصلاً تنظیم نشده باشد، مفسر به‌طور پیش‌فرض از تنظیمات محیط locale فعلی استفاده می‌کند، مگر اینکه محیط locale فعلی به‌عنوان یک محیط locale قدیمی مبتنی بر ASCII شناسایی شود (همان‌طور که برای PYTHONCOERCECLOCALE توضیح داده شده است) و اجبار محیط locale (locale coercion) غیرفعال باشد یا با شکست مواجه شود. در این‌گونه محیط‌های locale قدیمی، مفسر به‌طور پیش‌فرض حالت UTF-8 را فعال می‌کند، مگر اینکه صریحاً دستور داده شود که این کار انجام نشود.

حالت UTF-8 پایتون فقط در زمان راه‌اندازی پایتون می‌تواند فعال شود. مقدار آن را می‌توان از sys.flags.utf8_mode خواند.

همچنین حالت UTF-8 در ویندوز و filesystem encoding and error handler را ببینید.

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

PEP 686

پایتون 3.15 حالت UTF-8 پایتون را پیش‌فرض خواهد کرد.

پارامترهای فرایند

این توابع و آیتم‌های داده، اطلاعات را فراهم می‌کنند و روی فرایند و کاربر جاری عمل می‌کنند.

os.ctermid()

نام پرونده متناظر با پایانه کنترل‌کننده فرایند را برمی‌گرداند.

دسترس‌پذیری: Unix, not WASI.

os.environ

یک شیء mapping که در آن کلیدها و مقادیر، رشته‌هایی هستند که محیط فرایند را نشان می‌دهند. برای مثال، environ['HOME'] مسیرنام پوشه‌ی خانگی شما است (در برخی سکوها) و معادل getenv("HOME") در C است.

این نگاشت در اولین باری که ماژول os ایمپورت می‌شود، ثبت می‌شود؛ معمولاً در هنگام راه‌اندازی پایتون به‌عنوان بخشی از پردازش site.py. تغییرات اعمال‌شده در محیط پس از این زمان، در os.environ منعکس نمی‌شوند، مگر تغییراتی که با تغییر مستقیم os.environ ایجاد شده باشند.

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

در یونیکس، برای کلیدها و مقادیر از sys.getfilesystemencoding() و هندلر خطای 'surrogateescape' استفاده می‌شود. اگر بخواهید از کدگذاری متفاوتی استفاده کنید، از environb استفاده کنید.

در ویندوز، کلیدها به حروف بزرگ تبدیل می‌شوند. این قاعده هنگام دریافت، تنظیم یا حذف یک آیتم نیز اعمال می‌شود. برای مثال، environ['monty'] = 'python' کلید 'MONTY' را به مقدار 'python' نگاشت می‌کند.

توجه

فراخوانی مستقیم putenv() باعث تغییر os.environ نمی‌شود، بنابراین بهتر است os.environ را تغییر دهید.

توجه

در برخی از سکوها، از جمله FreeBSD و macOS، تنظیم environ ممکن است موجب نشتی حافظه شود. برای putenv() به مستندات سیستم مراجعه کنید.

شما می‌توانید آیتم‌های این نگاشت را حذف کنید تا متغیرهای محیطی از حالت تنظیم خارج شوند. unsetenv() به‌طور خودکار هنگامی که آیتمی از os.environ حذف شود، و هنگامی که یکی از متدهای pop() یا clear() فراخوانی شود، فراخوانی می‌شود.

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

تابع os.reload_environ().

تغییر یافته در نسخه‌ی 3.9: به‌روزرسانی شد تا از عملگرهای ادغام (|) و به‌روزرسانی (|=) در PEP 584 پشتیبانی کند.

os.environb

نسخه‌ی بایتی environ: یک شیء mapping که در آن هم کلیدها و هم مقدارها، اشیای bytes نشان‌دهنده‌ی محیط فرایند هستند. environ و environb همگام هستند (تغییر دادن environb، environ را به‌روزرسانی می‌کند و بالعکس).

environb تنها در صورتی در دسترس است که supports_bytes_environ برابر True باشد.

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

تغییر یافته در نسخه‌ی 3.9: به‌روزرسانی شد تا از عملگرهای ادغام (|) و به‌روزرسانی (|=) در PEP 584 پشتیبانی کند.

os.reload_environ()

نگاشت‌های os.environ و os.environb نهانگاهی از متغیرهای محیطی در زمان شروع پایتون هستند. به همین دلیل، تغییرات محیط فرایند جاری، اگر خارج از پایتون یا توسط os.putenv() یا os.unsetenv() انجام شده باشند، منعکس نمی‌شوند. برای به‌روزرسانی os.environ و os.environb با هرگونه تغییر از این دست در محیط فرایند جاری، از os.reload_environ() استفاده کنید.

هشدار

این تابع نخ‌ایمن نیست. فراخوانی آن در حالی که محیط در نخ دیگری در حال تغییر است، رفتاری تعریف‌نشده است. خواندن از os.environ یا os.environb، یا فراخوانی os.getenv() در حین بارگذاری مجدد، ممکن است نتیجه‌ای خالی برگرداند.

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

os.chdir(path)
os.fchdir(fd)
os.getcwd()

این توابع در پرونده‌ها و پوشه‌ها توضیح داده شده‌اند.

os.fsencode(filename)

filename مسیرمانند (path-like) را به filesystem encoding and error handler کدگذاری می‌کند؛ bytes را بدون تغییر بازمی‌گرداند.

fsdecode() تابع معکوس است.

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

تغییر یافته در نسخه‌ی 3.6: پشتیبانی برای پذیرش اشیایی که رابط os.PathLike را پیاده‌سازی می‌کنند، افزوده شد.

os.fsdecode(filename)

کدگشایی path-like filename از filesystem encoding and error handler؛ بازگرداندن str بدون تغییر.

fsencode() تابع معکوس است.

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

تغییر یافته در نسخه‌ی 3.6: پشتیبانی برای پذیرش اشیایی که رابط os.PathLike را پیاده‌سازی می‌کنند، افزوده شد.

os.fspath(path)

بازنمایی مسیر در سامانه فایل‌بندی را برمی‌گرداند.

اگر str یا bytes ارسال شود، بدون تغییر بازگردانده می‌شود. در غیر این صورت __fspath__() فراخوانی می‌شود و مقدار آن بازگردانده می‌شود، مشروط بر اینکه یک شیء str یا bytes باشد. در تمام حالت‌های دیگر، TypeError پرتاب می‌شود.

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

class os.PathLike

یک کلاس پایه انتزاعی برای اشیایی که مسیر پرونده سیستم را نشان می‌دهند، مانند pathlib.PurePath.

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

abstractmethod __fspath__()

نمایش مسیر سامانه فایل‌بندی شیء را برمی‌گرداند.

این متد باید فقط یک شیء str یا bytes برگرداند، با ترجیح برای str.

os.getenv(key, default=None)

مقدار متغیر محیطی key را در صورت وجود به‌صورت یک رشته برمی‌گرداند، یا اگر وجود نداشته باشد، default را برمی‌گرداند. key یک رشته است. توجه داشته باشید که از آنجا که getenv() از os.environ استفاده می‌کند، نگاشت getenv() نیز به‌طور مشابه در زمان ایمپورت ثبت می‌شود و ممکن است این تابع تغییرات بعدی محیط را منعکس نکند.

در یونیکس، کلیدها و مقدارها با استفاده از sys.getfilesystemencoding() و هندلر خطای 'surrogateescape' کدگشایی می‌شوند. اگر می‌خواهید از کدگذاری دیگری استفاده کنید، از os.getenvb() استفاده کنید.

دسترس‌پذیری: Unix, Windows.

os.getenvb(key, default=None)

اگر متغیر محیطی key وجود داشته باشد، مقدار آن را به‌صورت بایت برمی‌گرداند؛ در غیر این صورت default را برمی‌گرداند. key باید بایت باشد. توجه داشته باشید که از آن‌جا که getenvb() از os.environb استفاده می‌کند، نگاشت getenvb() نیز به‌طور مشابه در زمان ایمپورت ثبت می‌شود و ممکن است این تابع تغییرات آینده محیط را منعکس نکند.

getenvb() تنها در صورتی در دسترس است که supports_bytes_environ برابر True باشد.

دسترس‌پذیری: Unix.

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

os.get_exec_path(env=None)

فهرست پوشه‌هایی را برمی‌گرداند که هنگام راه‌اندازی یک فرایند، مشابه پوسته، برای یافتن یک پرونده اجرایی با نام مشخص جست‌وجو می‌شوند. env، در صورت تعیین شدن، باید یک دیکشنری متغیرهای محیطی باشد تا PATH در آن جست‌وجو شود. به‌طور پیش‌فرض، وقتی env برابر None باشد، از environ استفاده می‌شود.

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

os.getegid()

شناسه گروه مؤثر فرایند جاری را برمی‌گرداند. این با بیت «set id» روی پرونده‌ای که در فرایند جاری اجرا می‌شود، متناظر است.

دسترس‌پذیری: Unix, not WASI.

os.geteuid()

شناسه کاربر مؤثر فرایند جاری را برمی‌گرداند.

دسترس‌پذیری: Unix, not WASI.

os.getgid()

شناسه گروه واقعی فرآیند جاری را برمی‌گرداند.

دسترس‌پذیری: Unix.

این تابع در WASI یک تابع stub است؛ برای اطلاعات بیشتر سکوهای WebAssembly را ببینید.

os.getgrouplist(user, group, /)

فهرست شناسه‌های گروه را برمی‌گرداند که user به آن‌ها تعلق دارد. اگر group در فهرست نباشد، به فهرست افزوده می‌شود؛ معمولاً group به‌عنوان فیلد شناسه‌ی گروه از رکورد گذرواژه برای user مشخص می‌شود، زیرا در غیر این صورت ممکن است آن شناسه‌ی گروه حذف شود.

دسترس‌پذیری: Unix, not WASI.

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

os.getgroups()

فهرستی از شناسه‌های گروه تکمیلی مرتبط با فرایند جاری را برمی‌گرداند.

دسترس‌پذیری: Unix, not WASI.

توجه

در macOS، رفتار getgroups() تا حدی با سایر پلتفرم‌های Unix متفاوت است. اگر مفسر Python با هدف استقرار (deployment target) 10.5 یا قدیمی‌تر ساخته شده باشد، getgroups() فهرست شناسه‌های گروه مؤثر مرتبط با فرایند کاربر جاری را برمی‌گرداند؛ این فهرست به تعداد ورودی‌های تعریف‌شده توسط سیستم محدود است، که معمولاً ۱۶ است، و در صورت داشتن امتیازات کافی ممکن است توسط فراخوانی‌های setgroups() تغییر کند. اگر با هدف استقرار بزرگ‌تر از 10.5 ساخته شده باشد، getgroups() فهرست دسترسی گروه جاری برای کاربر مرتبط با شناسه کاربر مؤثر فرایند را برمی‌گرداند؛ فهرست دسترسی گروه ممکن است در طول عمر فرایند تغییر کند، تحت تأثیر فراخوانی‌های setgroups() قرار نمی‌گیرد، و طول آن به ۱۶ محدود نیست. می‌توان مقدار هدف استقرار، MACOSX_DEPLOYMENT_TARGET، را با sysconfig.get_config_var() به دست آورد.

os.getlogin()

نام کاربر واردشده به پایانه کنترل‌کننده فرایند را برمی‌گرداند. در بیشتر موارد، استفاده از getpass.getuser() مفیدتر است، زیرا این تابع متغیرهای محیطی LOGNAME یا USERNAME را بررسی می‌کند تا مشخص کند کاربر کیست، و به‌عنوان جایگزین، برای دریافت نام ورود شناسه کاربر واقعی فعلی از pwd.getpwuid(os.getuid())[0] استفاده می‌کند.

دسترس‌پذیری: Unix, Windows, not WASI.

os.getpgid(pid)

شناسه گروه فرایند برای فرایندی با شناسه فرایند pid را برمی‌گرداند. اگر pid برابر ۰ باشد، شناسه گروه فرایند برای فرایند جاری برگردانده می‌شود.

دسترس‌پذیری: Unix, not WASI.

os.getpgrp()

شناسه‌ی گروه فرایند جاری را برمی‌گرداند.

دسترس‌پذیری: Unix, not WASI.

os.getpid()

شناسه‌ی فرایند جاری را برمی‌گرداند.

این تابع در WASI یک تابع stub است؛ برای اطلاعات بیشتر سکوهای WebAssembly را ببینید.

os.getppid()

شناسه‌ی فرایند والد را برمی‌گرداند. هنگامی که فرایند والد خارج شده باشد، در یونیکس شناسه‌ی بازگشتی، شناسه‌ی فرایند init (۱) است؛ در ویندوز همچنان همان شناسه است، که ممکن است پیش‌تر توسط فرایند دیگری دوباره استفاده شده باشد.

دسترس‌پذیری: Unix, Windows, not WASI.

تغییر یافته در نسخه‌ی 3.2: پشتیبانی از ویندوز اضافه شد.

os.getpriority(which, who)

اولویت زمان‌بندی برنامه را دریافت می‌کند. مقدار which یکی از PRIO_PROCESS، PRIO_PGRP یا PRIO_USER است، و who نسبت به which تفسیر می‌شود (شناسه فرایند برای PRIO_PROCESS، شناسه گروه فرایند برای PRIO_PGRP، و شناسه کاربر برای PRIO_USER). مقدار صفر برای who (به‌ترتیب) بیانگر فرایند فراخوان، گروه فرایندِ فرایند فراخوان، یا شناسه کاربر واقعی فرایند فراخوان است.

دسترس‌پذیری: Unix, not WASI.

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

os.PRIO_PROCESS
os.PRIO_PGRP
os.PRIO_USER

پارامترهای توابع getpriority() و setpriority().

دسترس‌پذیری: Unix, not WASI.

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

os.PRIO_DARWIN_THREAD
os.PRIO_DARWIN_PROCESS
os.PRIO_DARWIN_BG
os.PRIO_DARWIN_NONUI

پارامترهای توابع getpriority() و setpriority().

دسترس‌پذیری: macOS

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

os.getresuid()

یک تاپل (ruid, euid, suid) برمی‌گرداند که نشان‌دهنده‌ی شناسه‌های کاربری واقعی، مؤثر و ذخیره‌شده‌ی فرایند جاری است.

دسترس‌پذیری: Unix, not WASI, not macOS, not iOS.

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

os.getresgid()

یک تاپل شامل (rgid, egid, sgid) برمی‌گرداند که شناسه‌های گروه واقعی، مؤثر و ذخیره‌شده‌ی فرایند جاری را نشان می‌دهد.

دسترس‌پذیری: Unix, not WASI, not macOS, not iOS.

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

os.getuid()

شناسه کاربری واقعی فرایند جاری را برمی‌گرداند.

دسترس‌پذیری: Unix.

این تابع در WASI یک تابع stub است؛ برای اطلاعات بیشتر سکوهای WebAssembly را ببینید.

os.initgroups(username, gid, /)

برای مقداردهی اولیه‌ی فهرست دسترسی گروه با همه‌ی گروه‌هایی که نام کاربری مشخص‌شده عضو آن‌ها است، به‌علاوه‌ی شناسه‌ی گروه مشخص‌شده، فراخوانی سیستمی initgroups() را انجام دهید.

دسترس‌پذیری: Unix, not WASI, not Android.

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

os.putenv(key, value, /)

متغیر محیطی به نام key را به رشته‌ی value تنظیم می‌کند. چنین تغییراتی در محیط بر زیرفرایندهایی که با os.system()، popen() یا fork() و execv() شروع شده‌اند، تأثیر می‌گذارند.

انتساب‌ها به آیتم‌های os.environ به‌طور خودکار به فراخوانی‌های متناظر putenv() تبدیل می‌شوند؛ با این حال، فراخوانی‌های putenv() باعث به‌روزرسانی os.environ نمی‌شوند، بنابراین در واقع بهتر است به آیتم‌های os.environ انتساب دهید. این موضوع همچنین در مورد getenv() و getenvb() صدق می‌کند، که به‌ترتیب در پیاده‌سازی‌های خود از os.environ و os.environb استفاده می‌کنند.

همچنین تابع os.reload_environ() را ببینید.

توجه

در برخی از سکوها، از جمله FreeBSD و macOS، تنظیم environ ممکن است باعث نشت حافظه شود. برای putenv() به مستندات سیستم مراجعه کنید.

یک رویداد حسابرسی os.putenv را با آرگومان‌های key و value پرتاب می‌کند.

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

os.setegid(egid, /)

شناسه گروه مؤثر فرایند جاری را تنظیم می‌کند.

دسترس‌پذیری: Unix, not WASI, not Android.

os.seteuid(euid, /)

شناسه کاربر مؤثر فرایند جاری را تنظیم می‌کند.

دسترس‌پذیری: Unix, not WASI, not Android.

os.setgid(gid, /)

شناسه گروه فرایند جاری را تنظیم می‌کند.

دسترس‌پذیری: Unix, not WASI, not Android.

os.setgroups(groups, /)

فهرست شناسه‌های گروه تکمیلی مرتبط با فرایند جاری را روی groups تنظیم کنید. groups باید یک دنباله باشد، و هر عنصر باید یک عدد صحیح باشد که یک گروه را مشخص می‌کند. این عملیات معمولاً فقط برای ابرکاربر در دسترس است.

دسترس‌پذیری: Unix, not WASI.

توجه

در macOS، طول groups نباید از حداکثر تعداد تعریف‌شده توسط سیستم برای شناسه‌های گروه مؤثر بیشتر شود، که معمولاً ۱۶ است. مستندات getgroups() را برای مواردی ببینید که ممکن است همان فهرست گروهی را که با فراخوانی setgroups() تنظیم شده است برنگرداند.

os.setns(fd, nstype=0)

نخ جاری را دوباره با یک فضای نام لینوکس مرتبط می‌کند. برای جزئیات بیشتر، صفحه‌های راهنمای setns(2) و namespaces(7) را ببینید.

اگر fd به یک پیوند /proc/pid/ns/ اشاره کند، setns() نخ فراخوان را دوباره به فضای نام مرتبط با آن پیوند متصل می‌کند، و می‌توان nstype را روی یکی از ثابت‌های CLONE_NEW* تنظیم کرد تا محدودیت‌هایی بر عملیات اعمال شود (0 به معنای بدون محدودیت است).

از لینوکس 5.8 به بعد، fd ممکن است به یک توصیف‌گر پرونده PID اشاره داشته باشد که از pidfd_open() به‌دست‌آمده است. در این حالت، setns() نخ فراخواننده را دوباره به یک یا چند مورد از همان فضای نام های نخ مورد اشاره توسط fd مرتبط می‌کند. این کار مشمول هرگونه محدودیتی است که توسط nstype اعمال می‌شود؛ nstype یک نقاب بیتی ترکیبی از یک یا چند مورد از ثابت‌های CLONE_NEW* است، برای مثال setns(fd, os.CLONE_NEWUTS | os.CLONE_NEWPID). عضویت‌های فراخواننده در فضای نام های مشخص‌نشده بدون تغییر باقی می‌مانند.

fd می‌تواند هر شیءای باشد که متد fileno() دارد، یا یک توصیف‌گر پرونده خام.

این مثال نخ را دوباره به فضای نام شبکه‌ی فرایند init متصل می‌کند:

fd = os.open("/proc/1/ns/net", os.O_RDONLY)
os.setns(fd, os.CLONE_NEWNET)
os.close(fd)

دسترس‌پذیری: Linux >= 3.0 with glibc >= 2.14.

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

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

تابع unshare().

os.setpgrp()

فراخوانی سیستمی setpgrp() یا setpgrp(0, 0) را، بسته به این‌که کدام نسخه پیاده‌سازی شده است (در صورت وجود)، انجام می‌دهد. برای معنای آن به راهنمای یونیکس مراجعه کنید.

دسترس‌پذیری: Unix, not WASI.

os.setpgid(pid, pgrp, /)

فراخوانی سیستمی setpgid() را برای تنظیم شناسه‌ی گروه فرایندِ فرایند با شناسه‌ی pid به گروه فرایند با شناسه‌ی pgrp انجام دهید. برای معنای آن به راهنمای Unix مراجعه کنید.

دسترس‌پذیری: Unix, not WASI.

os.setpriority(which, who, priority)

اولویت زمان‌بندی برنامه را تنظیم می‌کند. مقدار which یکی از PRIO_PROCESS، PRIO_PGRP، یا PRIO_USER است، و who نسبت به which تفسیر می‌شود (شناسه‌ی فرایند برای PRIO_PROCESS، شناسه‌ی گروه فرایند برای PRIO_PGRP، و شناسه‌ی کاربر برای PRIO_USER). مقدار صفر برای who (به‌ترتیب) نشان‌دهنده‌ی فرایند فراخوان، گروه فرایندِ فرایند فراخوان، یا شناسه‌ی کاربر واقعیِ فرایند فراخوان است. priority مقداری در بازه‌ی -۲۰ تا ۱۹ است. اولویت پیش‌فرض ۰ است؛ اولویت‌های پایین‌تر باعث زمان‌بندی مطلوب‌تر می‌شوند.

دسترس‌پذیری: Unix, not WASI.

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

os.setregid(rgid, egid, /)

شناسه‌های گروه واقعی و مؤثر فرایند جاری را تنظیم می‌کند.

دسترس‌پذیری: Unix, not WASI, not Android.

os.setresgid(rgid, egid, sgid, /)

شناسه‌های گروه واقعی، مؤثر و ذخیره‌شده‌ی فرایند جاری را تنظیم می‌کند.

دسترس‌پذیری: Unix, not WASI, not Android, not macOS, not iOS.

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

os.setresuid(ruid, euid, suid, /)

شناسه‌های کاربری واقعی، مؤثر و ذخیره‌شده‌ی فرایند جاری را تنظیم می‌کند.

دسترس‌پذیری: Unix, not WASI, not Android, not macOS, not iOS.

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

os.setreuid(ruid, euid, /)

شناسه‌های کاربری واقعی و مؤثر فرایند جاری را تنظیم می‌کند.

دسترس‌پذیری: Unix, not WASI, not Android.

os.getsid(pid, /)

فراخوانی سیستمی getsid() را انجام دهید. برای معنا به راهنمای Unix مراجعه کنید.

دسترس‌پذیری: Unix, not WASI.

os.setsid()

فراخوانی سیستمی setsid() را انجام دهید. برای معنای آن به راهنمای یونیکس مراجعه کنید.

دسترس‌پذیری: Unix, not WASI.

os.setuid(uid, /)

شناسه کاربری فرآیند جاری را تنظیم می‌کند.

دسترس‌پذیری: Unix, not WASI, not Android.

os.strerror(code, /)

پیام خطای متناظر با کد خطای موجود در code را برمی‌گرداند. در سکوهایی که strerror() هنگام دریافت یک شماره خطای ناشناخته NULL برمی‌گرداند، ValueError پرتاب می‌شود.

os.supports_bytes_environ

اگر نوع سیستم‌عامل بومی محیط، بایت باشد، True است (برای مثال، در ویندوز False است).

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

os.umask(mask, /)

umask عددی جاری را تنظیم کنید و umask پیشین را برگردانید

این تابع در WASI یک تابع stub است؛ برای اطلاعات بیشتر سکوهای WebAssembly را ببینید.

os.uname()

اطلاعات شناسایی‌کننده سیستم‌عامل جاری را برمی‌گرداند. مقدار بازگشتی یک uname_result است.

در macOS، iOS و Android، این نام و نسخه‌ی هسته را برمی‌گرداند (یعنی در macOS و iOS 'Darwin'؛ در Android 'Linux'). برای دریافت نام و نسخه‌ی سیستم‌عامل قابل‌مشاهده برای کاربر در iOS و Android می‌توان از platform.uname() استفاده کرد.

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

sys.platform که دانه‌بندی دقیق‌تری دارد.

ماژول platform بررسی‌های دقیقی برای هویت سیستم ارائه می‌دهد.

دسترس‌پذیری: Unix.

تغییر یافته در نسخه‌ی 3.3: نوع برگشتی از یک تاپل به یک شیء تاپل‌مانند با ویژگی‌های نام‌دار تغییر کرد.

class os.uname_result

نام و اطلاعات درباره‌ی سیستم که توسط os.uname() بازگردانده می‌شود. این ویژگی‌ها با اعضای توصیف‌شده در uname(2) مطابقت دارند.

برای سازگاری با نسخه‌های پیشین، این شیء نیز پیمایش‌پذیر است و مانند یک تاپل پنج‌عضوی شامل sysname، nodename، release، version و machine به همین ترتیب رفتار می‌کند.

sysname

نام سیستم‌عامل.

nodename

نام ماشین در شبکه. برخی سیستم‌ها nodename را به ۸ نویسه یا به کامپوننت ابتدایی کوتاه می‌کنند؛ راه بهتر برای دریافت نام میزبان socket.gethostname() یا حتی socket.gethostbyaddr(socket.gethostname()) است.

release

نسخه‌ی سیستم‌عامل.

version

نسخه‌ی سیستم‌عامل.

machine

شناسه‌ی سخت‌افزار.

os.unsetenv(key, /)

متغیر محیطی با نام key را حذف (unset) می‌کند. چنین تغییراتی در محیط، بر زیرفرایندهای راه‌اندازی‌شده با os.system()، popen() یا fork() و execv() تأثیر می‌گذارد.

حذف آیتم‌ها از os.environ به‌طور خودکار به یک فراخوانی متناظر از unsetenv() تبدیل می‌شود؛ با این حال، فراخوانی‌های unsetenv()، os.environ را به‌روزرسانی نمی‌کنند، بنابراین در واقع بهتر است آیتم‌های os.environ را حذف کنید.

همچنین تابع os.reload_environ() را ببینید.

یک رویداد حسابرسی os.unsetenv را با آرگومان key پرتاب می‌کند.

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

os.unshare(flags)

بخش‌هایی از زمینه اجرای فرایند را جدا می‌کند و آن‌ها را به یک فضای نام تازه ایجادشده منتقل می‌کند. برای جزئیات بیشتر، صفحه راهنمای unshare(2) را ببینید. آرگومان flags یک نقاب بیتی است که صفر یا چند مورد از ثابت‌های CLONE_* را ترکیب می‌کند و مشخص می‌کند کدام بخش‌های زمینه اجرا باید از ارتباطات موجود خود جدا شوند و به یک فضای نام جدید منتقل شوند. اگر آرگومان flags برابر 0 باشد، هیچ تغییری در زمینه اجرای فرایند فراخوان ایجاد نمی‌شود.

دسترس‌پذیری: Linux >= 2.6.16.

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

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

تابع setns().

پرچم‌های تابع unshare()، اگر پیاده‌سازی از آن‌ها پشتیبانی کند. برای تأثیر دقیق و دسترس‌پذیری آن‌ها، به unshare(2) در راهنمای لینوکس مراجعه کنید.

os.CLONE_FILES
os.CLONE_FS
os.CLONE_NEWCGROUP
os.CLONE_NEWIPC
os.CLONE_NEWNET
os.CLONE_NEWNS
os.CLONE_NEWPID
os.CLONE_NEWTIME
os.CLONE_NEWUSER
os.CLONE_NEWUTS
os.CLONE_SIGHAND
os.CLONE_SYSVSEM
os.CLONE_THREAD
os.CLONE_VM

ایجاد شیء پرونده

این توابع اشیای پرونده جدیدی ایجاد می‌کنند. (همچنین برای باز کردن توصیف‌گرهای پرونده open() را ببینید.)

os.fdopen(fd, *args, **kwargs)

یک شیء پرونده باز متصل به توصیف‌گر پرونده fd را برمی‌گرداند. این یک نام مستعار از تابع توکار open() است و همان آرگومان‌ها را می‌پذیرد. تنها تفاوت این است که اولین آرگومان fdopen() باید همیشه یک عدد صحیح باشد.

عملیات توصیف‌گر پرونده

این توابع بر جریان‌های ورودی/خروجی که با توصیف‌گرهای پرونده به آن‌ها ارجاع داده می‌شوند، عمل می‌کنند.

توصیف‌گرهای پرونده (file descriptors) اعداد صحیح کوچکی هستند که به پرونده‌ای که فرایند جاری آن را باز کرده است مربوط می‌شوند. برای مثال، ورودی استاندارد معمولاً توصیف‌گر پرونده ۰ است، خروجی استاندارد ۱ است و خطای استاندارد ۲ است. سپس به پرونده‌های دیگری که توسط یک فرایند باز می‌شوند، توصیف‌گرهای ۳، ۴، ۵ و به همین ترتیب اختصاص داده می‌شود. نام «file descriptor» کمی فریبنده است؛ در پلتفرم‌های یونیکسی، به سوکت‌ها و پایپ‌ها نیز با توصیف‌گرهای پرونده ارجاع داده می‌شود.

می‌توان از متد fileno() برای دریافت توصیف‌گر پرونده مرتبط با یک file object در صورت نیاز استفاده کرد. توجه داشته باشید که استفاده مستقیم از توصیف‌گر پرونده، متدهای شیء پرونده را دور می‌زند و جنبه‌هایی مانند بافرینگ داخلی داده‌ها را نادیده می‌گیرد.

os.close(fd)

بستن توصیف‌گر پرونده fd.

توجه

این تابع برای ورودی/خروجی سطح پایین در نظر گرفته شده است و باید بر روی یک توصیف‌گر پرونده که توسط os.open() یا pipe() برگردانده شده است اعمال شود. برای بستن یک «شیء پرونده» برگردانده‌شده توسط تابع توکار open() یا popen() یا fdopen()، از متد close() آن استفاده کنید.

os.closerange(fd_low, fd_high, /)

تمام توصیف‌گرهای پرونده را از fd_low (شامل) تا fd_high (غیرشامل) می‌بندد و خطاها را نادیده می‌گیرد. معادل است با (اما بسیار سریع‌تر از):

for fd in range(fd_low, fd_high):
    try:
        os.close(fd)
    except OSError:
        pass
os.copy_file_range(src, dst, count, offset_src=None, offset_dst=None)

count بایت را از توصیف‌گر پرونده src، با شروع از آفست offset_src، به توصیف‌گر پرونده dst، با شروع از آفست offset_dst کپی می‌کند. اگر offset_src None باشد، src از موقعیت فعلی خوانده می‌شود؛ به‌همین‌ترتیب برای offset_dst.

در هسته لینوکس قدیمی‌تر از 5.3، پرونده‌هایی که src و dst به آن‌ها اشاره می‌کنند باید در یک سامانه فایل‌بندی قرار داشته باشند، در غیر این صورت یک OSError پرتاب می‌شود که errno آن روی errno.EXDEV تنظیم شده است.

این کپی بدون هزینه‌ی اضافی انتقال داده از هسته به فضای کاربر و سپس بازگشت آن به هسته انجام می‌شود. علاوه بر این، برخی سامانه فایل‌بندی‌ها می‌توانند بهینه‌سازی‌های اضافی را پیاده‌سازی کنند، مانند استفاده از رفلینک‌ها (reflinks) (یعنی دو یا چند آی‌نود (inodes) که نشانگرهایی را به بلوک‌های دیسک یکسان با کپی هنگام نوشتن (copy-on-write) به اشتراک می‌گذارند؛ سامانه فایل‌بندی‌های پشتیبانی‌شده شامل btrfs و XFS می‌شوند) و کپی سمت سرور (server-side copy) (در مورد NFS).

این تابع بایت‌ها را بین دو توصیف‌گر پرونده کپی می‌کند. گزینه‌های متنی، مانند کدگذاری و پایان خط، نادیده گرفته می‌شوند.

مقدار بازگشتی، میزان بایت‌های کپی‌شده است. این مقدار ممکن است کمتر از میزان درخواست‌شده باشد.

توجه

در لینوکس، برای کپی کردن محدوده‌ای از یک شبه‌پرونده در سامانه فایل‌بندی خاصی مانند procfs و sysfs نباید از os.copy_file_range() استفاده کنید. این تابع همیشه بدون کپی کردن هیچ بایتی، ۰ را برمی‌گرداند، گویی که پرونده خالی است؛ زیرا یک مشکل شناخته‌شده در هسته لینوکس وجود دارد.

دسترس‌پذیری: Linux >= 4.5 with glibc >= 2.27.

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

os.device_encoding(fd)

رشته‌ای را برمی‌گرداند که کدگذاری دستگاه مرتبط با fd را توصیف می‌کند، اگر به یک پایانه متصل باشد؛ در غیر این صورت None را برمی‌گرداند.

در یونیکس، اگر حالت UTF-8 پایتون فعال باشد، به‌جای کدگذاری دستگاه، 'UTF-8' را برمی‌گرداند.

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

os.dup(fd, /)

یک کپی از توصیف‌گر پرونده fd برمی‌گرداند. توصیف‌گر پرونده جدید غیرقابل ارث‌بردن است.

در ویندوز، هنگام تکثیر یک جریان استاندارد (۰: stdin، ۱: stdout، ۲: stderr)، توصیف‌گر پرونده جدید قابل ارث‌بردن است.

دسترس‌پذیری: not WASI.

تغییر یافته در نسخه‌ی 3.4: توصیف‌گر پرونده جدید اکنون غیرقابل‌ارث‌برداری است.

os.dup2(fd, fd2, inheritable=True)

توصیف‌گر پرونده fd را به fd2 تکثیر می‌کند و در صورت لزوم، ابتدا دومی را می‌بندد. fd2 را برمی‌گرداند. توصیف‌گر پرونده جدید به‌طور پیش‌فرض قابل ارث‌بردن است، یا اگر inheritable برابر False باشد، غیرقابل ارث‌بردن است.

دسترس‌پذیری: not WASI.

تغییر یافته در نسخه‌ی 3.4: پارامتر اختیاری inheritable را اضافه کنید.

تغییر یافته در نسخه‌ی 3.7: در صورت موفقیت، fd2 را برمی‌گرداند. پیش از این، همیشه None برگردانده می‌شد.

os.fchmod(fd, mode)

حالت پرونده مشخص‌شده با fd را به mode عددی تغییر دهید. برای مقادیر ممکن mode، مستندات chmod() را ببینید. از پایتون 3.3 به بعد، این معادل os.chmod(fd, mode) است.

یک رویداد حسابرسی os.chmod را با آرگومان‌های path، mode و dir_fd پرتاب می‌کند.

دسترس‌پذیری: Unix, Windows.

این تابع در WASI محدود است، برای اطلاعات بیشتر سکوهای WebAssembly را ببینید.

تغییر یافته در نسخه‌ی 3.13: پشتیبانی در ویندوز افزوده شد.

os.fchown(fd, uid, gid)

شناسه مالک و شناسه گروه پرونده داده‌شده با fd را به uid و gid عددی تغییر دهید. برای آنکه یکی از شناسه‌ها را بدون تغییر بگذارید، آن را روی -1 تنظیم کنید. chown() را ببینید. از پایتون 3.3 به بعد، این معادل os.chown(fd, uid, gid) است.

یک رویداد حسابرسی os.chown را با آرگومان‌های path، uid، gid و dir_fd پرتاب می‌کند.

دسترس‌پذیری: Unix.

این تابع در WASI محدود است، برای اطلاعات بیشتر سکوهای WebAssembly را ببینید.

os.fdatasync(fd)

نوشتن پرونده با توصیف‌گر پرونده fd روی دیسک را اجبار می‌کند. به‌روزرسانی فراداده را اجباری نمی‌کند.

دسترس‌پذیری: Unix, not macOS, not iOS.

os.fpathconf(fd, name, /)

اطلاعات پیکربندی سیستم مرتبط با یک پرونده باز را برمی‌گرداند. name مقدار پیکربندی برای بازیابی را مشخص می‌کند؛ ممکن است رشته‌ای باشد که نام یک مقدار سیستمی تعریف‌شده است؛ این نام‌ها در تعدادی از استانداردها (POSIX.1، Unix 95، Unix 98 و سایر استانداردها) مشخص شده‌اند. برخی سکوها نیز نام‌های اضافی تعریف می‌کنند. نام‌های شناخته‌شده برای سیستم‌عامل میزبان در دیکشنری pathconf_names آمده است. برای متغیرهای پیکربندی که در آن نگاشت گنجانده نشده‌اند، فرستادن یک عدد صحیح به‌عنوان name نیز پذیرفته می‌شود.

اگر name یک رشته باشد و شناخته‌شده نباشد، ValueError پرتاب می‌شود. اگر مقدار خاصی برای name توسط سیستم میزبان پشتیبانی نشود، حتی اگر در pathconf_names وجود داشته باشد، یک OSError با errno.EINVAL به‌عنوان شماره خطا پرتاب می‌شود.

از نسخه‌ی 3.3 پایتون، این معادل os.pathconf(fd, name) است.

دسترس‌پذیری: Unix.

os.fstat(fd)

وضعیت توصیف‌گر پرونده fd را دریافت می‌کند. یک شیء stat_result برمی‌گرداند.

از پایتون 3.3 به بعد، این معادل os.stat(fd) است.

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

تابع stat().

os.fstatvfs(fd, /)

اطلاعات مربوط به سامانه فایل‌بندی حاوی پرونده مرتبط با توصیف‌گر پرونده fd را در یک statvfs_result برمی‌گرداند، مانند statvfs(). از پایتون 3.3، این معادل os.statvfs(fd) است.

دسترس‌پذیری: Unix.

os.fsync(fd)

نوشتن پرونده با توصیف‌گر پرونده fd را به‌صورت اجباری روی دیسک انجام می‌دهد. در یونیکس، تابع بومی fsync() فراخوانی می‌شود؛ در ویندوز، تابع _commit() مایکروسافت فراخوانی می‌شود.

اگر کار خود را با یک file object دارای بافر در پایتون به نام f آغاز می‌کنید، ابتدا f.flush() و سپس os.fsync(f.fileno()) را اجرا کنید تا اطمینان حاصل شود که تمام بافرهای داخلی مرتبط با f بر روی دیسک نوشته شده‌اند.

دسترس‌پذیری: Unix, Windows.

os.ftruncate(fd, length, /)

پرونده متناظر با توصیف‌گر پرونده (file descriptor) fd را کوتاه کنید، به‌طوری که اندازه آن حداکثر length بایت باشد. از پایتون 3.3، این معادل os.truncate(fd, length) است.

یک رویداد حسابرسی os.truncate را با آرگومان‌های fd و length پرتاب می‌کند.

دسترس‌پذیری: Unix, Windows.

تغییر یافته در نسخه‌ی 3.5: پشتیبانی از ویندوز اضافه شد

os.get_blocking(fd, /)

حالت مسدودسازی توصیف‌گر پرونده را دریافت کنید: اگر پرچم O_NONBLOCK تنظیم شده باشد، False و اگر پرچم پاک شده باشد، True.

همچنین set_blocking() و socket.socket.setblocking() را ببینید.

دسترس‌پذیری: Unix, Windows.

این تابع در WASI محدود است، برای اطلاعات بیشتر سکوهای WebAssembly را ببینید.

در ویندوز، این تابع محدود به پایپ‌ها است.

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

تغییر یافته در نسخه‌ی 3.12: پشتیبانی از پایپ‌ها در ویندوز اضافه شد.

os.grantpt(fd, /)

دسترسی به دستگاه شبه‌پایانه‌ی فرعی (slave) مرتبط با دستگاه شبه‌پایانه‌ی اصلی (master) را که توصیف‌گر پرونده fd به آن اشاره می‌کند، اعطا می‌کند. توصیف‌گر پرونده fd در صورت شکست بسته نمی‌شود.

تابع grantpt() از کتابخانه‌ی استاندارد C را فراخوانی می‌کند.

دسترس‌پذیری: Unix, not WASI.

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

os.isatty(fd, /)

اگر توصیف‌گر پرونده fd باز و به یک دستگاه tty-مانند متصل باشد، True را برمی‌گرداند، در غیر این صورت False را برمی‌گرداند.

os.lockf(fd, cmd, len, /)

اعمال، آزمایش یا حذف یک قفل POSIX روی یک توصیف‌گر پرونده باز. fd یک توصیف‌گر پرونده باز است. cmd دستور مورد استفاده را مشخص می‌کند - یکی از F_LOCK، F_TLOCK، F_ULOCK یا F_TEST. len بخشی از پرونده را که باید قفل شود مشخص می‌کند.

یک رویداد حسابرسی os.lockf را با آرگومان‌های fd، cmd و len پرتاب می‌کند.

دسترس‌پذیری: Unix.

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

os.F_LOCK
os.F_TLOCK
os.F_ULOCK
os.F_TEST

پرچم‌هایی که مشخص می‌کنند lockf() چه عملیاتی را انجام خواهد داد.

دسترس‌پذیری: Unix.

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

os.login_tty(fd, /)

tty را که fd توصیف‌گر پرونده آن است، برای یک نشست ورود جدید آماده کنید. فرایند فراخواننده را به رهبر نشست تبدیل کنید؛ tty را به tty کنترل‌کننده، stdin، stdout و stderr فرایند فراخواننده تبدیل کنید؛ fd را ببندید.

دسترس‌پذیری: Unix, not WASI.

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

os.lseek(fd, pos, whence, /)

موقعیت فعلی توصیف‌گر پرونده fd را روی موقعیت pos تنظیم می‌کند، که با whence تغییر می‌یابد، و موقعیت جدید را بر حسب بایت نسبت به ابتدای پرونده برمی‌گرداند. مقادیر معتبر برای whence عبارت‌اند از:

  • SEEK_SET یا 0 -- تنظیم pos نسبت به ابتدای پرونده

  • SEEK_CUR یا 1 -- مقدار pos را نسبت به موقعیت فعلی پرونده تنظیم می‌کند

  • SEEK_END یا 2 -- pos را نسبت به پایان پرونده تنظیم می‌کند

  • SEEK_HOLE -- pos را به مکان بعدی داده، نسبت به pos تنظیم می‌کند

  • SEEK_DATA -- pos را به حفره‌ی داده‌ی بعدی، نسبت به pos تنظیم می‌کند

تغییر یافته در نسخه‌ی 3.3: افزودن پشتیبانی از SEEK_HOLE و SEEK_DATA.

os.SEEK_SET
os.SEEK_CUR
os.SEEK_END

پارامترهای تابع lseek() و متد seek() در اشیاء شبه‌پرونده، برای استفاده به‌عنوان whence جهت تنظیم نشانگر موقعیت پرونده.

SEEK_SET

موقعیت پرونده را نسبت به ابتدای پرونده تنظیم کنید.

SEEK_CUR

موقعیت پرونده را نسبت به موقعیت فعلی پرونده تنظیم کنید.

SEEK_END

موقعیت پرونده را نسبت به پایان پرونده تنظیم می‌کند.

مقدارهای آن‌ها به‌ترتیب ۰، ۱ و ۲ است.

os.SEEK_HOLE
os.SEEK_DATA

پارامترهایی برای تابع lseek() و متد seek() در اشیاء شبه‌پرونده، برای مکان‌یابی داده‌ها و حفره‌های پرونده در پرونده‌هایی با تخصیص پراکنده.

SEEK_DATA

آفست پرونده را نسبت به موقعیت مکان‌یابی، به مکان بعدی حاوی داده تنظیم می‌کند.

SEEK_HOLE

آفست پرونده را به مکان بعدی حاوی یک حفره، نسبت به موقعیت مکان‌یابی، تنظیم کنید. حفره به‌صورت دنباله‌ای از صفرها تعریف می‌شود.

توجه

این عملیات تنها برای سامانه فایل‌بندی‌هایی که از آن‌ها پشتیبانی می‌کنند، معنا دارند.

دسترس‌پذیری: Linux >= 3.1, macOS, Unix

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

os.open(path, flags, mode=0o777, *, dir_fd=None)

پرونده path را باز می‌کند و پرچم‌های مختلف را مطابق flags و در صورت لزوم حالت آن را مطابق mode تنظیم می‌کند. هنگام محاسبه mode، ابتدا مقدار umask فعلی نقاب می‌شود. توصیف‌گر پرونده برای پرونده تازه بازشده را برمی‌گرداند. توصیف‌گر پرونده جدید غیرقابل‌ارث است.

برای توضیح مقادیر پرچم و حالت، مستندات ران‌تایم C را ببینید؛ ثابت‌های پرچم (مانند O_RDONLY و O_WRONLY) در ماژول os تعریف شده‌اند. به‌ویژه، در ویندوز، برای باز کردن پرونده‌ها در حالت دودویی، افزودن O_BINARY لازم است.

این تابع می‌تواند با پارامتر dir_fd از مسیرهای نسبی به توصیف‌گرهای پوشه پشتیبانی کند.

یک رویداد حسابرسی open را با آرگومان‌های path، mode و flags پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.4: توصیف‌گر پرونده جدید اکنون غیرقابل‌ارث‌برداری است.

توجه

این تابع برای ورودی/خروجی سطح پایین در نظر گرفته شده است. برای استفاده‌ی عادی، از تابع توکار open() استفاده کنید، که یک file object با متدهای read() و write() را بازمی‌گرداند. برای دربرگرفتن یک توصیف‌گر پرونده در یک شیء پرونده، از fdopen() استفاده کنید.

تغییر یافته در نسخه‌ی 3.3: پارامتر dir_fd اضافه شد.

تغییر یافته در نسخه‌ی 3.5: اگر فراخوانی سیستمی دچار وقفه شود و مدیر سیگنال استثنایی پرتاب نکند، تابع اکنون به‌جای پرتاب استثنای InterruptedError، فراخوانی سیستمی را مجدداً اجرا می‌کند (برای مشاهده دلیل، PEP 475 را ببینید).

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

ثابت‌های زیر گزینه‌هایی برای پارامتر flags در تابع open() هستند. می‌توان آن‌ها را با استفاده از عملگر OR بیتی | ترکیب کرد. برخی از آن‌ها در همه سکوها در دسترس نیستند. برای توضیحات مربوط به دسترس‌پذیری و کاربرد آن‌ها، به صفحه راهنمای open(2) در یونیکس یا MSDN در ویندوز مراجعه کنید.

os.O_RDONLY
os.O_WRONLY
os.O_RDWR
os.O_APPEND
os.O_CREAT
os.O_EXCL
os.O_TRUNC

ثابت‌های فوق در یونیکس و ویندوز در دسترس هستند.

os.O_DSYNC
os.O_RSYNC
os.O_SYNC
os.O_NDELAY
os.O_NONBLOCK
os.O_NOCTTY
os.O_CLOEXEC

ثابت‌های فوق تنها در یونیکس در دسترس هستند.

تغییر یافته در نسخه‌ی 3.3: افزودن ثابت O_CLOEXEC.

os.O_BINARY
os.O_NOINHERIT
os.O_SHORT_LIVED
os.O_TEMPORARY
os.O_RANDOM
os.O_SEQUENTIAL
os.O_TEXT

ثابت‌های بالا فقط در ویندوز در دسترس هستند.

os.O_EVTONLY
os.O_FSYNC
os.O_NOFOLLOW_ANY

ثابت‌های فوق تنها در macOS در دسترس هستند.

تغییر یافته در نسخه‌ی 3.10: ثابت‌های O_EVTONLY، O_FSYNC، O_SYMLINK و O_NOFOLLOW_ANY اضافه شدند.

os.O_ASYNC
os.O_DIRECT
os.O_DIRECTORY
os.O_NOFOLLOW
os.O_NOATIME
os.O_PATH
os.O_TMPFILE
os.O_SHLOCK
os.O_EXLOCK

ثابت‌های بالا افزونه هستند و در صورتی که توسط کتابخانه C تعریف نشده باشند، وجود ندارند.

تغییر یافته در نسخه‌ی 3.4: افزودن O_PATH در سیستم‌هایی که از آن پشتیبانی می‌کنند. افزودن O_TMPFILE، که فقط در هسته لینوکس 3.11 یا جدیدتر در دسترس است.

os.openpty()

یک جفت شبه‌پایانه (pseudo-terminal) جدید را باز می‌کند. یک جفت توصیف‌گر پرونده (master, slave) را به‌ترتیب برای pty و tty برمی‌گرداند. توصیف‌گرهای پرونده جدید غیرقابل ارث‌بردن هستند. برای رویکردی (اندکی) قابل‌حمل‌تر، از ماژول pty استفاده کنید.

دسترس‌پذیری: Unix, not WASI.

تغییر یافته در نسخه‌ی 3.4: توصیف‌گرهای پرونده جدید اکنون غیرقابل ارث‌بری هستند.

os.pipe()

یک پایپ ایجاد می‌کند. یک جفت توصیف‌گر پرونده (r, w) برمی‌گرداند که به‌ترتیب برای خواندن و نوشتن قابل استفاده هستند. توصیف‌گر پرونده جدید غیرقابل ارث‌بردن است.

دسترس‌پذیری: Unix, Windows.

تغییر یافته در نسخه‌ی 3.4: توصیف‌گرهای پرونده جدید اکنون غیرقابل ارث‌بری هستند.

os.pipe2(flags, /)

یک پایپ ایجاد می‌کند که flags آن به‌صورت اتمی تنظیم شده است. می‌توان flags را با OR کردن یک یا چند مقدار از این مقادیر با یکدیگر ساخت: O_NONBLOCK، O_CLOEXEC. یک جفت توصیف‌گر پرونده (r, w) برمی‌گرداند که به‌ترتیب برای خواندن و نوشتن قابل استفاده هستند.

دسترس‌پذیری: Unix, not WASI, not macOS, not iOS.

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

os.posix_fallocate(fd, offset, len, /)

تضمین می‌کند که فضای دیسک کافی برای پرونده‌ای که با fd مشخص شده است، از offset به طول len بایت تخصیص داده شود.

دسترس‌پذیری: Unix, not macOS, not iOS.

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

os.posix_fadvise(fd, offset, len, advice, /)

قصد دسترسی به داده‌ها در الگویی مشخص را اعلام می‌کند و به این ترتیب به هسته اجازه می‌دهد بهینه‌سازی‌هایی انجام دهد. این توصیه به ناحیه‌ای از پرونده مشخص‌شده با fd اعمال می‌شود که از offset شروع می‌شود و به طول len بایت ادامه دارد. advice یکی از POSIX_FADV_NORMAL، POSIX_FADV_SEQUENTIAL، POSIX_FADV_RANDOM، POSIX_FADV_NOREUSE، POSIX_FADV_WILLNEED یا POSIX_FADV_DONTNEED است.

دسترس‌پذیری: Unix, not macOS, not iOS.

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

os.POSIX_FADV_NORMAL
os.POSIX_FADV_SEQUENTIAL
os.POSIX_FADV_RANDOM
os.POSIX_FADV_NOREUSE
os.POSIX_FADV_WILLNEED
os.POSIX_FADV_DONTNEED

پرچم‌هایی که می‌توان از آن‌ها در advice در posix_fadvise() استفاده کرد و الگوی دسترسی‌ای را که احتمالاً استفاده خواهد شد، مشخص می‌کنند.

دسترس‌پذیری: Unix.

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

os.pread(fd, n, offset, /)

حداکثر n بایت را از توصیف‌گر پرونده fd در موقعیت offset بخوانید، در حالی که آفست پرونده بدون تغییر باقی می‌ماند.

یک رشته‌بایت (bytestring) شامل بایت‌های خوانده‌شده برمی‌گرداند. اگر به انتهای پرونده‌ای که fd به آن اشاره دارد رسیده باشد، یک شیء bytes خالی برگردانده می‌شود.

دسترس‌پذیری: Unix.

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

os.posix_openpt(oflag, /)

یک دستگاه شبه‌پایانه‌ی اصلی را باز می‌کند و یک توصیف‌گر پرونده برای آن برمی‌گرداند.

تابع posix_openpt() از کتابخانه استاندارد C را فراخوانی می‌کند. آرگومان oflag برای تنظیم پرچم‌های وضعیت پرونده و حالت‌های دسترسی به پرونده، همان‌طور که در صفحه راهنمای posix_openpt() در سیستم شما مشخص شده است، استفاده می‌شود.

توصیف‌گر پرونده برگردانده‌شده غیرقابل ارث‌بردن است. اگر مقدار O_CLOEXEC در سیستم در دسترس باشد، به oflag اضافه می‌شود.

دسترس‌پذیری: Unix, not WASI.

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

os.preadv(fd, buffers, offset, flags=0, /)

از یک توصیف‌گر پرونده fd در موقعیت offset به درون buffers، که اشیاء شبه‌بایت تغییرپذیر هستند، می‌خواند و آفست پرونده را بدون تغییر باقی می‌گذارد. داده‌ها را به هر بافر منتقل می‌کند تا آن بافر پر شود، سپس برای نگهداری باقی‌مانده‌ی داده‌ها به بافر بعدی در دنباله می‌رود.

آرگومان flags شامل OR بیتی (bitwise OR) از صفر یا چند مورد از پرچم‌های زیر است:

تعداد کل بایت‌های واقعاً خوانده‌شده را برمی‌گرداند که می‌تواند کمتر از ظرفیت کل همه‌ی شیء‌ها باشد.

سیستم‌عامل ممکن است محدودیتی (sysconf() مقدار 'SC_IOV_MAX') برای تعداد بافرهای قابل استفاده تعیین کند.

عملکرد os.readv() و os.pread() را ترکیب می‌کند.

دسترس‌پذیری: Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1.

استفاده از پرچم‌ها نیازمند Linux >= 4.6 است.

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

os.RWF_NOWAIT

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

اگر مقداری داده با موفقیت خوانده شود، تعداد بایت‌های خوانده‌شده را بازمی‌گرداند. اگر هیچ بایتی خوانده نشود، -1 را بازمی‌گرداند و errno را روی errno.EAGAIN تنظیم می‌کند.

دسترس‌پذیری: Linux >= 4.14.

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

os.RWF_HIPRI

خواندن/نوشتن با اولویت بالا. به سامانه فایل‌بندی‌های مبتنی بر بلوک اجازه می‌دهد از پایش (polling) دستگاه استفاده کنند، که تأخیر کمتری به همراه دارد، اما ممکن است منابع اضافی مصرف کند.

در حال حاضر، در لینوکس، این قابلیت فقط برای توصیف‌گر پرونده‌ای که با پرچم O_DIRECT باز شده است، قابل استفاده است.

دسترس‌پذیری: Linux >= 4.6.

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

os.ptsname(fd, /)

نام دستگاه شبه‌پایانه پیرو (slave pseudo-terminal device) مرتبط با دستگاه شبه‌پایانه اصلی (master pseudo-terminal device) که توصیف‌گر پرونده fd به آن اشاره می‌کند را برمی‌گرداند. توصیف‌گر پرونده fd در صورت شکست بسته نمی‌شود.

اگر تابع بازورودی (reentrant) ptsname_r() از کتابخانه استاندارد C در دسترس باشد، آن را فراخوانی می‌کند؛ در غیر این صورت، تابع ptsname() از کتابخانه استاندارد C فراخوانی می‌شود که ایمنی آن در برابر نخ‌ها (thread-safe) تضمین نشده است.

دسترس‌پذیری: Unix, not WASI.

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

os.pwrite(fd, str, offset, /)

رشته بایتی موجود در str را به توصیف‌گر پرونده fd در موقعیت offset می‌نویسد، در حالی که آفست پرونده بدون تغییر باقی می‌ماند.

تعداد بایت‌های واقعاً نوشته‌شده را بازمی‌گرداند.

دسترس‌پذیری: Unix.

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

os.pwritev(fd, buffers, offset, flags=0, /)

محتوای buffers را در آفست offset در توصیف‌گر پرونده fd می‌نویسد، در حالی که آفست پرونده بدون تغییر باقی می‌ماند. buffers باید دنباله‌ای از اشیاء شبه‌بایت (bytes-like objects) باشد. بافرها به ترتیب آرایه پردازش می‌شوند. پیش از رفتن به بافر دوم، تمام محتوای بافر نخست نوشته می‌شود و به همین ترتیب ادامه می‌یابد.

آرگومان flags شامل OR بیتی (bitwise OR) از صفر یا چند مورد از پرچم‌های زیر است:

تعداد کل بایت‌های واقعاً نوشته‌شده را برمی‌گرداند.

سیستم‌عامل ممکن است محدودیتی (sysconf() مقدار 'SC_IOV_MAX') برای تعداد بافرهای قابل استفاده تعیین کند.

عملکرد os.writev() و os.pwrite() را ترکیب می‌کند.

دسترس‌پذیری: Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1.

استفاده از پرچم‌ها نیازمند Linux >= 4.6 است.

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

os.RWF_DSYNC

معادلی به‌ازای هر نوشتن از پرچم O_DSYNC در os.open() فراهم می‌کند. اثر این پرچم تنها به محدوده داده‌ای اعمال می‌شود که به‌وسیله فراخوانی سیستم نوشته‌شده است.

دسترس‌پذیری: Linux >= 4.7.

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

os.RWF_SYNC

معادلی به‌ازای هر نوشتن از پرچم O_SYNC در os.open() فراهم می‌کند. اثر این پرچم فقط به محدوده داده‌ای اعمال می‌شود که توسط فراخوانی سیستمی نوشته می‌شود.

دسترس‌پذیری: Linux >= 4.7.

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

os.RWF_APPEND

معادلی به‌ازای هر بار نوشتن برای پرچم O_APPEND در os.open() فراهم می‌کند. این پرچم فقط برای os.pwritev() معنا دارد، و اثر آن فقط بر محدوده داده‌ای است که فراخوانی سیستم آن را می‌نویسد. آرگومان offset بر عملیات نوشتن تأثیری ندارد؛ داده همیشه به پایان پرونده الحاق می‌شود. با این حال، اگر آرگومان offset برابر -1 باشد، offset فعلی پرونده به‌روزرسانی می‌شود.

دسترس‌پذیری: Linux >= 4.16.

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

os.read(fd, n, /)

حداکثر n بایت را از توصیف‌گر پرونده fd بخوانید.

یک رشته‌بایت (bytestring) شامل بایت‌های خوانده‌شده برمی‌گرداند. اگر به انتهای پرونده‌ای که fd به آن اشاره دارد رسیده باشد، یک شیء bytes خالی برگردانده می‌شود.

توجه

این تابع برای ورودی/خروجی سطح پایین در نظر گرفته شده است و باید روی یک توصیف‌گر پرونده که توسط os.open() یا pipe() برگردانده شده است اعمال شود. برای خواندن یک «شیء پرونده» که توسط تابع توکار open() یا popen() یا fdopen() برگردانده شده است، یا sys.stdin، از متدهای read() یا readline() آن استفاده کنید.

تغییر یافته در نسخه‌ی 3.5: اگر فراخوانی سیستمی دچار وقفه شود و مدیر سیگنال استثنایی پرتاب نکند، تابع اکنون به‌جای پرتاب استثنای InterruptedError، فراخوانی سیستمی را مجدداً اجرا می‌کند (برای مشاهده دلیل، PEP 475 را ببینید).

os.readinto(fd, buffer, /)

خواندن از یک توصیف‌گر پرونده fd به درون یک شیء بافر تغییرپذیر buffer.

buffer باید تغییرپذیر و شبه‌بایت باشد. در صورت موفقیت، تعداد بایت‌های خوانده‌شده را برمی‌گرداند. ممکن است تعداد بایت‌های خوانده‌شده کمتر از اندازه buffer باشد. فراخوانی سیستمی زیربنی هنگامی که با یک سیگنال قطع شود، دوباره تلاش خواهد شد، مگر آنکه هندلر سیگنال استثنایی پرتاب کند. برای سایر خطاها دوباره تلاش نخواهد شد و خطایی پرتاب خواهد شد.

اگر fd در پایان پرونده باشد یا buffer ارائه‌شده طول ۰ داشته باشد، ۰ را برمی‌گرداند (که می‌توان از آن برای بررسی خطاها بدون خواندن داده استفاده کرد). هرگز مقدار منفی برنمی‌گرداند.

توجه

این تابع برای ورودی/خروجی سطح پایین در نظر گرفته شده است و باید بر توصیف‌گر پرونده‌ای که توسط os.open() یا os.pipe() برگردانده شده است، اعمال شود. برای خواندن یک «شیء پرونده» برگردانده‌شده توسط تابع توکار open()، یا sys.stdin، از متدهای عضو آن استفاده کنید، برای مثال io.BufferedIOBase.readinto()، io.BufferedIOBase.read() یا io.TextIOBase.read()

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

os.sendfile(out_fd, in_fd, offset, count)
os.sendfile(out_fd, in_fd, offset, count, headers=(), trailers=(), flags=0)

count بایت را از توصیف‌گر پرونده in_fd به توصیف‌گر پرونده out_fd با شروع از offset کپی می‌کند. تعداد بایت‌های ارسال‌شده را برمی‌گرداند. در صورت رسیدن به EOF، 0 را برمی‌گرداند.

اولین نمادگذاری تابع در همه سکوهایی که sendfile() را تعریف می‌کنند، پشتیبانی می‌شود.

در لینوکس، اگر offset به‌صورت None داده شود، بایت‌ها از موقعیت فعلی in_fd خوانده می‌شوند و موقعیت in_fd به‌روزرسانی می‌شود.

می‌توان از حالت دوم در macOS و FreeBSD استفاده کرد؛ در آن‌ها headers و trailers دنباله‌های دلخواهی از بافرها هستند که پیش از نوشتن داده‌های in_fd و پس از نوشتن آن‌ها نوشته می‌شوند. این حالت همان مقدار حالت اول را برمی‌گرداند.

در macOS و FreeBSD، مقدار 0 برای count مشخص می‌کند که ارسال تا رسیدن به پایان in_fd ادامه یابد.

همه‌ی سکوها از سوکت‌ها به‌عنوان توصیف‌گر پرونده out_fd پشتیبانی می‌کنند و برخی سکوها انواع دیگر (برای مثال پرونده معمولی، پایپ) را نیز مجاز می‌دانند.

برنامه‌های کاربردی چندسکویی نباید از آرگومان‌های headers، trailers و flags استفاده کنند.

دسترس‌پذیری: Unix, not WASI.

توجه

برای پوششی سطح بالاتر از sendfile()، socket.socket.sendfile() را ببینید.

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

تغییر یافته در نسخه‌ی 3.9: پارامترهای out و in به out_fd و in_fd تغییر نام یافتند.

os.SF_NODISKIO
os.SF_MNOWAIT
os.SF_SYNC

پارامترهای تابع sendfile()، اگر پیاده‌سازی از آن‌ها پشتیبانی کند.

دسترس‌پذیری: Unix, not WASI.

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

os.SF_NOCACHE

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

دسترس‌پذیری: Unix, not WASI.

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

os.set_blocking(fd, blocking, /)

حالت مسدودسازی توصیف‌گر پرونده مشخص‌شده را تنظیم کنید. اگر مسدودسازی False باشد، پرچم O_NONBLOCK را تنظیم کنید، در غیر این صورت پرچم را پاک کنید.

همچنین get_blocking() و socket.socket.setblocking() را ببینید.

دسترس‌پذیری: Unix, Windows.

این تابع در WASI محدود است، برای اطلاعات بیشتر سکوهای WebAssembly را ببینید.

در ویندوز، این تابع محدود به پایپ‌ها است.

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

تغییر یافته در نسخه‌ی 3.12: پشتیبانی از پایپ‌ها در ویندوز اضافه شد.

os.splice(src, dst, count, offset_src=None, offset_dst=None, flags=0)

count بایت را از توصیف‌گر پرونده src، با شروع از آفست offset_src، به توصیف‌گر پرونده dst، با شروع از آفست offset_dst منتقل می‌کند.

می‌توان رفتار الحاق (splicing) را با تعیین یک مقدار برای flags تغییر داد. می‌توان از هر یک از متغیرهای زیر استفاده کرد و آن‌ها را با OR بیت‌به‌بیت (عملگر |) ترکیب کرد:

  • اگر SPLICE_F_MOVE مشخص شده باشد، از هسته خواسته می‌شود که صفحه‌ها را به‌جای کپی کردن جابه‌جا کند، اما اگر هسته نتواند صفحه‌ها را از پایپ جابه‌جا کند، ممکن است صفحه‌ها همچنان کپی شوند.

  • اگر SPLICE_F_NONBLOCK تعیین شده باشد، از هسته خواسته می‌شود که در ورودی/خروجی مسدود نشود. این باعث می‌شود عملیات‌های پایپ splice غیرمسدودکننده شوند، اما با این حال ممکن است splice مسدود شود، زیرا ممکن است توصیف‌گرهای پرونده spliceشده مسدود شوند.

  • اگر SPLICE_F_MORE مشخص شده باشد، به هسته اشاره می‌کند که داده‌های بیشتری در یک اسپلایس (splice) بعدی خواهند آمد.

حداقل یکی از توصیف‌گرهای پرونده باید به یک پایپ اشاره کند. اگر offset_src برابر None باشد، آنگاه src از موقعیت فعلی خوانده می‌شود؛ به‌همین ترتیب برای offset_dst. آفست مرتبط با توصیف‌گر پرونده‌ای که به یک پایپ اشاره می‌کند، باید None باشد. پرونده‌هایی که src و dst به آن‌ها اشاره می‌کنند باید در یک سامانه فایل‌بندی یکسان قرار داشته باشند، در غیر این صورت یک OSError پرتاب می‌شود که errno آن روی errno.EXDEV تنظیم شده است.

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

پس از تکمیل موفقیت‌آمیز، تعداد بایت‌هایی که به پایپ یا از آن پیوند داده شده‌اند (spliced) را برمی‌گرداند. مقدار بازگشتی ۰ به معنای پایان ورودی است. اگر src به یک پایپ اشاره کند، این بدان معناست که داده‌ای برای انتقال وجود نداشته است و مسدود شدن (block) معنایی ندارد، زیرا هیچ نویسنده‌ای به پایانه نوشتن پایپ متصل نیست.

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

صفحه‌ی راهنمای splice(2).

دسترس‌پذیری: Linux >= 2.6.17 with glibc >= 2.5

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

os.SPLICE_F_MOVE
os.SPLICE_F_NONBLOCK
os.SPLICE_F_MORE

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

os.readv(fd, buffers, /)

خواندن از یک توصیف‌گر پرونده fd به درون تعدادی بافر تغییرپذیر از نوع شیء شبه‌بایتی (bytes-like object)، buffers. داده به هر بافر تا پر شدن آن منتقل می‌شود و سپس از بافر بعدی در دنباله برای نگه‌داشتن باقی‌مانده‌ی داده استفاده می‌شود.

تعداد کل بایت‌های واقعاً خوانده‌شده را برمی‌گرداند که می‌تواند کمتر از ظرفیت کل همه‌ی شیء‌ها باشد.

سیستم‌عامل ممکن است محدودیتی (sysconf() مقدار 'SC_IOV_MAX') برای تعداد بافرهای قابل استفاده تعیین کند.

دسترس‌پذیری: Unix.

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

os.tcgetpgrp(fd, /)

برگرداندن گروه فرایند مرتبط با پایانه‌ی داده‌شده توسط fd (یک توصیف‌گر پرونده باز که توسط os.open() برگردانده می‌شود).

دسترس‌پذیری: Unix, not WASI.

os.tcsetpgrp(fd, pg, /)

گروه فرایند مرتبط با پایانه‌ی داده‌شده توسط fd (یک توصیف‌گر پرونده باز که توسط os.open() برگردانده‌شده است) را روی pg تنظیم می‌کند.

دسترس‌پذیری: Unix, not WASI.

os.ttyname(fd, /)

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

دسترس‌پذیری: Unix.

os.unlockpt(fd, /)

قفل دستگاه شبه‌پایانه‌ی پیرو مرتبط با دستگاه شبه‌پایانه‌ی اصلی را که توصیف‌گر پرونده fd به آن اشاره می‌کند، باز کنید. توصیف‌گر پرونده fd در صورت شکست بسته نمی‌شود.

تابع unlockpt() از کتابخانه استاندارد C را فراخوانی می‌کند.

دسترس‌پذیری: Unix, not WASI.

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

os.write(fd, str, /)

رشته بایتی (bytestring) موجود در str را در توصیف‌گر پرونده fd بنویسید.

تعداد بایت‌های واقعاً نوشته‌شده را بازمی‌گرداند.

توجه

این تابع برای ورودی/خروجی سطح پایین در نظر گرفته شده است و باید روی یک توصیف‌گر پرونده که توسط os.open() یا pipe() برگردانده شده است اعمال شود. برای نوشتن در یک «شیء پرونده» که توسط تابع توکار open() یا popen() یا fdopen()، یا sys.stdout یا sys.stderr برگردانده شده است، از متد write() آن استفاده کنید.

تغییر یافته در نسخه‌ی 3.5: اگر فراخوانی سیستمی دچار وقفه شود و مدیر سیگنال استثنایی پرتاب نکند، تابع اکنون به‌جای پرتاب استثنای InterruptedError، فراخوانی سیستمی را مجدداً اجرا می‌کند (برای مشاهده دلیل، PEP 475 را ببینید).

os.writev(fd, buffers, /)

محتوای buffers را در توصیف‌گر پرونده fd می‌نویسد. buffers باید دنباله‌ای از اشیاء شبه‌بایت باشد. بافرها به ترتیب آرایه پردازش می‌شوند. تمام محتوای نخستین بافر پیش از ادامه به دومین بافر نوشته می‌شود و به همین ترتیب ادامه می‌یابد.

تعداد کل بایت‌هایی که واقعاً نوشته شده‌اند را برمی‌گرداند.

سیستم‌عامل ممکن است محدودیتی (sysconf() مقدار 'SC_IOV_MAX') برای تعداد بافرهای قابل استفاده تعیین کند.

دسترس‌پذیری: Unix.

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

پرس‌وجوی اندازه‌ی پایانه

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

os.get_terminal_size(fd=STDOUT_FILENO, /)

اندازه‌ی پنجره‌ی پایانه را به‌صورت (columns, lines) برمی‌گرداند، تاپلی از نوع terminal_size.

آرگومان اختیاری fd (پیش‌فرض STDOUT_FILENO، یا خروجی استاندارد) مشخص می‌کند که کدام توصیف‌گر پرونده باید پرس‌وجو شود.

اگر توصیف‌گر پرونده به یک پایانه متصل نباشد، استثنای OSError پرتاب می‌شود.

shutil.get_terminal_size() تابع سطح‌بالایی است که معمولاً باید از آن استفاده شود، os.get_terminal_size پیاده‌سازی سطح‌پایین است.

دسترس‌پذیری: Unix, Windows.

class os.terminal_size

زیرکلاسی از tuple که (columns, lines) اندازه‌ی پنجره‌ی پایانه را نگه می‌دارد.

columns

عرض پنجره‌ی پایانه بر حسب نویسه.

lines

ارتفاع پنجره‌ی پایانه بر حسب نویسه.

وراثت توصیف‌گرهای پرونده

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

یک توصیف‌گر پرونده دارای پرچمی «قابل ارث‌بری» است که نشان می‌دهد آیا فرآیندهای فرزند می‌توانند آن توصیف‌گر پرونده را به ارث ببرند. از پایتون 3.4، توصیف‌گرهای پرونده‌ای که پایتون ایجاد می‌کند، به‌طور پیش‌فرض غیرقابل ارث‌بری هستند.

در یونیکس، توصیف‌گرهای پرونده غیرقابل‌ارث‌بری در فرآیندهای فرزند هنگام اجرای یک برنامه جدید بسته می‌شوند؛ سایر توصیف‌گرهای پرونده به ارث برده می‌شوند. توجه داشته باشید که توصیف‌گرهای پرونده غیرقابل‌ارث‌بری همچنان در os.fork() توسط فرآیندهای فرزند به ارث برده می‌شوند.

در ویندوز، دسته‌های غیرقابل‌وراثت و توصیف‌گرهای پرونده غیرقابل‌وراثت در فرایندهای فرزند بسته می‌شوند، به‌جز جریان‌های استاندارد (توصیف‌گرهای پرونده ۰، ۱ و ۲: stdin، stdout و stderr) که همیشه به ارث می‌رسند. با استفاده از توابع spawn*، تمام دسته‌های قابل‌وراثت و تمام توصیف‌گرهای پرونده قابل‌وراثت به ارث می‌رسند. با استفاده از ماژول subprocess، تمام توصیف‌گرهای پرونده به‌جز جریان‌های استاندارد بسته می‌شوند، و دسته‌های قابل‌وراثت تنها در صورتی به ارث می‌رسند که پارامتر close_fds برابر False باشد.

در سکوهای WebAssembly، نمی‌توان توصیف‌گر پرونده را تغییر داد.

os.get_inheritable(fd, /)

پرچم «قابل ارث‌بردن» توصیف‌گر پرونده مشخص‌شده (یک بولی) را دریافت کنید.

os.set_inheritable(fd, inheritable, /)

پرچم «قابل ارث‌بردن» (inheritable) را برای توصیف‌گر پرونده مشخص‌شده تنظیم کنید.

os.get_handle_inheritable(handle, /)

پرچم «inheritable» دسته‌ی مشخص‌شده (یک بولی) را دریافت کنید.

دسترس‌پذیری: Windows.

os.set_handle_inheritable(handle, inheritable, /)

پرچم «قابل ارث‌بردن» (inheritable) را برای دسته‌ی مشخص‌شده تنظیم کنید.

دسترس‌پذیری: Windows.

پرونده‌ها و پوشه‌ها

در برخی از سکوهای یونیکس، بسیاری از این توابع از یک یا چند مورد از این قابلیت‌ها پشتیبانی می‌کنند:

  • مشخص کردن یک توصیف‌گر پرونده : به‌طور معمول، آرگومان path که به توابع ماژول os داده می‌شود، باید رشته‌ای باشد که مسیر پرونده را مشخص می‌کند. با این حال، برخی از توابع اکنون به‌عنوان جایگزین، یک توصیف‌گر پرونده باز را برای آرگومان path خود می‌پذیرند. سپس تابع روی پرونده‌ای که توصیف‌گر به آن اشاره دارد عمل می‌کند. در سیستم‌های POSIX، پایتون نسخه‌ای از تابع را که پیشوند f دارد فراخوانی می‌کند (برای مثال، fchdir را به‌جای chdir فراخوانی می‌کند).

    شما می‌توانید با استفاده از os.supports_fd بررسی کنید که آیا می‌توان path را برای یک تابع خاص در پلتفرم شما به‌عنوان توصیف‌گر پرونده (file descriptor) مشخص کرد یا خیر. اگر این قابلیت در دسترس نباشد، استفاده از آن باعث پرتاب NotImplementedError خواهد شد.

    اگر تابع همچنین از آرگومان‌های dir_fd یا follow_symlinks پشتیبانی کند، هنگامی که path را به‌عنوان توصیف‌گر پرونده ارائه می‌دهید، مشخص کردن یکی از آن‌ها خطا است.

  • مسیرهای نسبی به توصیف‌گرهای پوشه:** اگر dir_fd None نباشد، باید یک توصیف‌گر پرونده باشد که به یک پوشه اشاره می‌کند، و مسیری که عملیات روی آن انجام می‌شود باید نسبی باشد؛ در این صورت مسیر نسبت به آن پوشه خواهد بود. اگر مسیر مطلق باشد، dir_fd نادیده گرفته می‌شود. در سیستم‌های POSIX، پایتون گونه‌ای از تابع را با پسوند at و احتمالاً با پیشوند f فراخوانی می‌کند (برای مثال به جای access، faccessat را فراخوانی می‌کند).

    می‌توانید با استفاده از os.supports_dir_fd بررسی کنید که آیا dir_fd برای یک تابع خاص در پلتفرم شما پشتیبانی می‌شود یا خیر. اگر در دسترس نباشد، استفاده از آن باعث پرتاب یک NotImplementedError می‌شود.

os.access(path, mode, *, dir_fd=None, effective_ids=False, follow_symlinks=True)

برای بررسی دسترسی به path از uid/gid واقعی استفاده می‌شود. توجه داشته باشید که بیشتر عملیات از uid/gid مؤثر استفاده می‌کنند، بنابراین می‌توان از این روتین در یک محیط suid/sgid برای بررسی این موضوع استفاده کرد که کاربر فراخواننده به path دسترسی مشخص‌شده دارد یا خیر. mode باید برای بررسی وجود path برابر F_OK باشد، یا می‌تواند OR شامل یک یا چند مورد از R_OK، W_OK و X_OK برای بررسی مجوزها باشد. اگر دسترسی مجاز باشد، True و در غیر این صورت False برگردانده می‌شود. برای اطلاعات بیشتر، صفحه‌ی راهنمای یونیکس access(2) را ببینید.

این تابع می‌تواند از تعیین مسیرهای نسبی نسبت به توصیف‌گرهای پوشه و عدم دنبال‌کردن پیوندهای نمادین پشتیبانی کند.

اگر effective_ids برابر True باشد، access() بررسی‌های دسترسی خود را با استفاده از uid/gid مؤثر به جای uid/gid واقعی انجام می‌دهد. ممکن است effective_ids روی پلتفرم شما پشتیبانی نشود؛ می‌توانید با استفاده از os.supports_effective_ids بررسی کنید که آیا در دسترس است یا خیر. اگر در دسترس نباشد، استفاده از آن موجب پرتاب NotImplementedError می‌شود.

توجه

استفاده از access() برای بررسی اینکه کاربر مجاز است مثلاً پرونده‌ای را باز کند، پیش از انجام واقعی آن با open()، یک حفره‌ی امنیتی ایجاد می‌کند، زیرا کاربر ممکن است از بازه‌ی زمانی کوتاه بین بررسی و باز کردن پرونده برای دستکاری آن سوءاستفاده کند. بهتر است از روش‌های EAFP استفاده کنید. برای مثال:

if os.access("myfile", os.R_OK):
    with open("myfile") as fp:
        return fp.read()
return "some default data"

بهتر است به‌صورت زیر نوشته شود:

try:
    fp = open("myfile")
except PermissionError:
    return "some default data"
else:
    with fp:
        return fp.read()

توجه

ممکن است عملیات ورودی/خروجی حتی زمانی که access() نشان می‌دهد که با موفقیت انجام خواهد شد، شکست بخورد، به‌ویژه برای عملیات روی سامانه فایل‌بندی‌های شبکه‌ای که ممکن است برای دسترسی‌ها معنایی فراتر از مدل معمول بیت‌های دسترسی POSIX داشته باشند.

تغییر یافته در نسخه‌ی 3.3: پارامترهای dir_fd، effective_ids و follow_symlinks افزوده شدند.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

os.F_OK
os.R_OK
os.W_OK
os.X_OK

مقادیری که باید به‌عنوان پارامتر mode به access() ارسال شوند تا به‌ترتیب وجود، قابلیت خواندن، قابلیت نوشتن و قابلیت اجرای path را آزمایش کنند.

os.chdir(path)

پوشه کاری جاری را به path تغییر دهید.

این تابع می‌تواند از تعیین یک توصیف‌گر پرونده پشتیبانی کند. توصیف‌گر باید به یک پوشه‌ی بازشده اشاره کند، نه یک پرونده باز.

این تابع ممکن است OSError و زیرکلاس‌هایی مانند FileNotFoundError، PermissionError و NotADirectoryError را پرتاب کند.

یک رویداد حسابرسی os.chdir را با آرگومان path پرتاب می‌کند.

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

مدیر زمینه contextlib.chdir()، که هنگام ورود پوشه کاری فعلی را تغییر می‌دهد و هنگام خروج پوشه پیشین را بازمی‌گرداند.

تغییر یافته در نسخه‌ی 3.3: پشتیبانی برای مشخص کردن path به‌عنوان یک توصیف‌گر پرونده در برخی سکوها افزوده شد.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

os.chflags(path, flags, *, follow_symlinks=True)

پرچم‌های path را روی flags عددی تنظیم کنید. flags می‌تواند ترکیبی (OR بیتی) از مقادیر زیر باشد (همان‌طور که در ماژول stat تعریف‌شده است):

این تابع می‌تواند از دنبال نکردن پیوندهای نمادین پشتیبانی کند.

یک رویداد حسابرسی os.chflags را با آرگومان‌های path و flags پرتاب می‌کند.

دسترس‌پذیری: Unix, not WASI.

تغییر یافته در نسخه‌ی 3.3: پارامتر follow_symlinks اضافه شد.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

os.chmod(path, mode, *, dir_fd=None, follow_symlinks=True)

حالت path را به mode عددی تغییر دهید. mode می‌تواند یکی از مقادیر زیر (همان‌طور که در ماژول stat تعریف شده است) یا ترکیب‌های OR بیتی آن‌ها را بپذیرد:

این تابع می‌تواند از مشخص کردن یک توصیف‌گر پرونده، مسیرهای نسبی به توصیف‌گرهای پوشه و دنبال‌نکردن پیوندهای نمادین پشتیبانی کند.

توجه

اگرچه ویندوز از chmod() پشتیبانی می‌کند، اما با آن فقط می‌توانید پرچم فقط‌خواندنی پرونده را تنظیم کنید (از طریق ثابت‌های stat.S_IWRITE و stat.S_IREAD یا یک مقدار عدد صحیح متناظر). تمام بیت‌های دیگر نادیده گرفته می‌شوند. مقدار پیش‌فرض follow_symlinks در ویندوز False است.

این تابع در WASI محدود است، برای اطلاعات بیشتر سکوهای WebAssembly را ببینید.

یک رویداد حسابرسی os.chmod را با آرگومان‌های path، mode و dir_fd پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.3: پشتیبانی برای تعیین path به‌عنوان یک توصیف‌گر پرونده باز، و آرگومان‌های dir_fd و follow_symlinks افزوده شد.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

تغییر یافته در نسخه‌ی 3.13: پشتیبانی از توصیف‌گر پرونده و آرگومان follow_symlinks در ویندوز افزوده شد.

os.chown(path, uid, gid, *, dir_fd=None, follow_symlinks=True)

شناسه مالک و گروه path را به مقادیر عددی uid و gid تغییر دهید. برای اینکه یکی از شناسه‌ها بدون تغییر بماند، آن را روی -1 تنظیم کنید.

این تابع می‌تواند از مشخص کردن یک توصیف‌گر پرونده، مسیرهای نسبی به توصیف‌گرهای پوشه و دنبال‌نکردن پیوندهای نمادین پشتیبانی کند.

برای تابع سطح بالاتری که علاوه بر شناسه‌های عددی، نام‌ها را نیز می‌پذیرد، shutil.chown() را ببینید.

یک رویداد حسابرسی os.chown را با آرگومان‌های path، uid، gid و dir_fd پرتاب می‌کند.

دسترس‌پذیری: Unix.

این تابع در WASI محدود است، برای اطلاعات بیشتر سکوهای WebAssembly را ببینید.

تغییر یافته در نسخه‌ی 3.3: پشتیبانی برای تعیین path به‌عنوان یک توصیف‌گر پرونده باز، و آرگومان‌های dir_fd و follow_symlinks افزوده شد.

تغییر یافته در نسخه‌ی 3.6: از یک path-like object پشتیبانی می‌کند.

os.chroot(path)

پوشه ریشه فرایند جاری را به path تغییر می‌دهد.

دسترس‌پذیری: Unix, not WASI, not Android.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

os.fchdir(fd)

پوشه کاری جاری را به پوشه‌ای که توصیف‌گر پرونده fd به آن اشاره می‌کند، تغییر می‌دهد. توصیف‌گر باید به یک پوشه باز اشاره کند، نه یک پرونده باز. از پایتون 3.3، این معادل os.chdir(fd) است.

یک رویداد حسابرسی os.chdir را با آرگومان path پرتاب می‌کند.

دسترس‌پذیری: Unix.

os.getcwd()

رشته‌ای را برمی‌گرداند که پوشه کاری جاری را نشان می‌دهد.

os.getcwdb()

یک رشته‌بایت (bytestring) را برمی‌گرداند که نشان‌دهنده‌ی پوشه‌ی کاری جاری است.

تغییر یافته در نسخه‌ی 3.8: این تابع اکنون در ویندوز به جای صفحه کد ANSI از کدگذاری UTF-8 استفاده می‌کند: برای دلیل آن، PEP 529 را ببینید. این تابع دیگر در ویندوز منسوخ نیست.

os.lchflags(path, flags)

پرچم‌های path را روی flags عددی تنظیم کنید، مانند chflags()، اما از پیوندهای نمادین پیروی نکنید. از پایتون 3.3 به بعد، این معادل os.chflags(path, flags, follow_symlinks=False) است.

یک رویداد حسابرسی os.chflags را با آرگومان‌های path و flags پرتاب می‌کند.

دسترس‌پذیری: Unix, not WASI.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

os.lchmod(path, mode)

حالت path را به mode عددی تغییر دهید. اگر path یک پیوند نمادین باشد، این کار به‌جای هدف بر پیوند نمادین تأثیر می‌گذارد. مستندات chmod() را برای مقادیر ممکن mode ببینید. از پایتون 3.3، این معادل os.chmod(path, mode, follow_symlinks=False) است.

lchmod() بخشی از POSIX نیست، اما پیاده‌سازی‌های یونیکس ممکن است در صورتی که از تغییر حالت پیوندهای نمادین پشتیبانی شود، آن را داشته باشند.

یک رویداد حسابرسی os.chmod را با آرگومان‌های path، mode و dir_fd پرتاب می‌کند.

دسترس‌پذیری: Unix, Windows, not Linux, FreeBSD >= 1.3, NetBSD >= 1.3, not OpenBSD

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

تغییر یافته در نسخه‌ی 3.13: پشتیبانی در ویندوز افزوده شد.

os.lchown(path, uid, gid)

مالک و شناسه‌ی گروه path را به uid و gid عددی تغییر می‌دهد. این تابع، پیوندهای نمادین را دنبال نمی‌کند. از پایتون 3.3، این معادل os.chown(path, uid, gid, follow_symlinks=False) است.

یک رویداد حسابرسی os.chown را با آرگومان‌های path، uid، gid و dir_fd پرتاب می‌کند.

دسترس‌پذیری: Unix.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

یک پیوند سخت (hard link) با نام dst ایجاد کنید که به src اشاره می‌کند.

این تابع می‌تواند از تعیین src_dir_fd و/یا dst_dir_fd برای فراهم کردن مسیرهای نسبی نسبت به توصیف‌گرهای پوشه، و دنبال‌نکردن پیوندهای نمادین پشتیبانی کند. مقدار پیش‌فرض follow_symlinks در ویندوز False است.

یک رویداد حسابرسی os.link را با آرگومان‌های src، dst، src_dir_fd و dst_dir_fd پرتاب می‌کند.

دسترس‌پذیری: Unix, Windows.

تغییر یافته در نسخه‌ی 3.2: پشتیبانی از ویندوز اضافه شد.

تغییر یافته در نسخه‌ی 3.3: پارامترهای src_dir_fd، dst_dir_fd و follow_symlinks افزوده شدند.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را برای src و dst می‌پذیرد.

os.listdir(path='.')

فهرستی شامل نام ورودی‌های موجود در پوشه‌ی داده‌شده با path را برمی‌گرداند. ترتیب این فهرست دلخواه است و ورودی‌های ویژه '.' و '..' را حتی اگر در پوشه وجود داشته باشند شامل نمی‌شود. اگر پرونده‌ای در حین فراخوانی این تابع از پوشه حذف یا به آن اضافه شود، اینکه نام آن پرونده گنجانده شود یا نه، نامشخص است.

path می‌تواند یک path-like object باشد. اگر path از نوع bytes باشد (به‌طور مستقیم یا غیرمستقیم از طریق رابط PathLike)، نام‌پرونده‌های برگردانده‌شده نیز از نوع bytes خواهند بود؛ در تمام شرایط دیگر، آن‌ها از نوع str خواهند بود.

این تابع همچنین می‌تواند از تعیین یک توصیف‌گر پرونده پشتیبانی کند؛ توصیف‌گر پرونده باید به یک پوشه اشاره کند.

یک رویداد حسابرسی os.listdir را با آرگومان path پرتاب می‌کند.

توجه

برای کدگذاری نام پرونده‌های str به bytes، از fsencode() استفاده کنید.

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

تابع scandir() ورودی‌های پوشه را به همراه اطلاعات ویژگی‌های پرونده برمی‌گرداند و عملکرد بهتری برای بسیاری از موارد استفاده رایج فراهم می‌کند.

تغییر یافته در نسخه‌ی 3.2: پارامتر path اختیاری شد.

تغییر یافته در نسخه‌ی 3.3: پشتیبانی از مشخص کردن path به‌عنوان یک توصیف‌گر پرونده باز (open file descriptor) افزوده شد.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

os.listdrives()

فهرستی شامل نام درایوهای یک سیستم ویندوزی را برمی‌گرداند.

نام درایو معمولاً به شکلی مانند 'C:\\' است. هر نام درایوی لزوماً با یک حجم مرتبط نیست، و برخی ممکن است به دلایل مختلف، از جمله مجوزها، اتصال شبکه یا نبود رسانه، غیرقابل‌دسترسی باشند. این تابع دسترسی را بررسی نمی‌کند.

ممکن است در صورت بروز خطا در جمع‌آوری نام‌های درایو، OSError پرتاب شود.

یک رویداد حسابرسی os.listdrives را بدون آرگومان پرتاب می‌کند.

دسترس‌پذیری: Windows

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

os.listmounts(volume)

فهرستی شامل نقاط اتصال برای یک حجم در یک سیستم ویندوزی برمی‌گرداند.

volume باید به‌صورت یک مسیر GUID نمایش داده شود، مانند مسیرهایی که os.listvolumes() برمی‌گرداند. حجم‌ها ممکن است در چندین مکان متصل شده باشند یا اصلاً متصل نشده باشند. در حالت دوم، فهرست خالی خواهد بود. این تابع نقاط اتصال را که با یک حجم مرتبط نیستند، برنمی‌گرداند.

نقطه‌های اتصالی که این تابع بازمی‌گرداند، مسیرهای مطلق خواهند بود و ممکن است طولانی‌تر از نام درایو باشند.

در صورتی که حجم شناسایی نشود یا خطایی در جمع‌آوری مسیرها رخ دهد، OSError پرتاب می‌شود.

یک رویداد حسابرسی os.listmounts را با آرگومان volume پرتاب می‌کند.

دسترس‌پذیری: Windows

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

os.listvolumes()

فهرستی شامل حجم‌های موجود در سیستم را برمی‌گرداند.

حجم‌ها معمولاً به‌صورت یک مسیر GUID نمایش داده می‌شوند که شبیه \\?\Volume{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}\ است. معمولاً می‌توان به پرونده‌ها از طریق یک مسیر GUID دسترسی داشت، مشروط به این‌که دسترسی‌ها اجازه دهند. با این حال، کاربران عموماً با آن‌ها آشنا نیستند، بنابراین استفاده‌ی توصیه‌شده از این تابع، دریافت نقاط اتصال با استفاده از os.listmounts() است.

ممکن است در صورت بروز خطا هنگام جمع‌آوری حجم‌ها، OSError پرتاب شود.

یک رویداد حسابرسی os.listvolumes را بدون آرگومان پرتاب می‌کند.

دسترس‌پذیری: Windows

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

os.lstat(path, *, dir_fd=None)

معادل یک فراخوانی سیستمی lstat() را روی مسیر داده‌شده انجام می‌دهد. مشابه stat() است، اما پیوندهای نمادین را دنبال نمی‌کند. یک شیء stat_result را برمی‌گرداند.

در پلتفرم‌هایی که از پیوندهای نمادین پشتیبانی نمی‌کنند، این یک نام مستعار برای stat() است.

از پایتون 3.3، این معادل os.stat(path, dir_fd=dir_fd, follow_symlinks=False) است.

این تابع همچنین می‌تواند از مسیرهای نسبی به توصیف‌گرهای پوشه پشتیبانی کند.

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

تابع stat().

تغییر یافته در نسخه‌ی 3.2: پشتیبانی از پیوندهای نمادین ویندوز 6.0 (ویستا) افزوده شد.

تغییر یافته در نسخه‌ی 3.3: پارامتر dir_fd اضافه شد.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

تغییر یافته در نسخه‌ی 3.8: در ویندوز، اکنون نقاط بازتفسیر (reparse points) را که نشان‌دهنده‌ی مسیر دیگری هستند (جانشین‌های نام یا name surrogates)، از جمله پیوندهای نمادین و اتصال‌های پوشه (directory junctions)، باز می‌کند. سایر انواع نقاط بازتفسیر، همان‌طور که برای stat() انجام می‌شود، توسط سیستم‌عامل حل می‌شوند.

os.mkdir(path, mode=0o777, *, dir_fd=None)

پوشه‌ای به نام path با حالت عددی mode ایجاد کنید.

اگر پوشه از قبل وجود داشته باشد، FileExistsError پرتاب می‌شود. اگر پوشه‌ی والدی در مسیر وجود نداشته باشد، FileNotFoundError پرتاب می‌شود.

در برخی سامانه‌ها، mode نادیده گرفته می‌شود. در مواردی که از آن استفاده می‌شود، ابتدا مقدار فعلی umask پوشانده می‌شود. اگر بیت‌هایی غیر از ۹ بیت آخر (یعنی ۳ رقم آخر نمایش mode در مبنای هشت) تنظیم شده باشند، معنای آن‌ها وابسته به سکو (platform) است. در برخی سکوها، آن‌ها نادیده گرفته می‌شوند و شما باید برای تنظیم آن‌ها chmod() را به‌صراحت فراخوانی کنید.

در ویندوز، mode با مقدار 0o700 به‌طور ویژه مدیریت می‌شود تا کنترل دسترسی به پوشه‌ی جدید اعمال شود، به‌طوری که فقط کاربر جاری و مدیران دسترسی داشته باشند. سایر مقادیر mode نادیده گرفته می‌شوند.

این تابع همچنین می‌تواند از مسیرهای نسبی به توصیف‌گرهای پوشه پشتیبانی کند.

همچنین می‌توانید پوشه‌های موقت ایجاد کنید؛ تابع tempfile.mkdtemp() در ماژول tempfile را ببینید.

یک رویداد حسابرسی os.mkdir را با آرگومان‌های path، mode و dir_fd پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.3: پارامتر dir_fd اضافه شد.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

تغییر یافته در نسخه‌ی 3.13: ویندوز اکنون یک mode با مقدار 0o700 را مدیریت می‌کند.

os.makedirs(name, mode=0o777, exist_ok=False)

تابع ایجاد پوشه به‌صورت بازگشتی. مانند mkdir()، اما تمام پوشه‌های سطح میانی مورد نیاز برای دربرگرفتن پوشه نهایی را ایجاد می‌کند.

پارامتر mode برای ایجاد پوشه برگ به mkdir() ارسال می‌شود؛ برای آگاهی از چگونگی تفسیر آن، توضیح mkdir() را ببینید. برای تنظیم بیت‌های دسترسی پرونده هر یک از پوشه‌های والد تازه‌ایجادشده می‌توانید پیش از فراخوانی makedirs()، umask را تنظیم کنید. بیت‌های دسترسی پرونده پوشه‌های والد موجود تغییر نمی‌یابند.

اگر exist_ok برابر False (پیش‌فرض) باشد، در صورتی که پوشه هدف از قبل وجود داشته باشد، یک FileExistsError پرتاب می‌شود.

توجه

اگر عناصر مسیری که باید ایجاد شوند شامل pardir باشند (برای مثال ".." در سیستم‌های UNIX)، makedirs() دچار سردرگمی می‌شود.

این تابع مسیرهای UNC را به‌درستی مدیریت می‌کند.

یک رویداد حسابرسی os.mkdir را با آرگومان‌های path، mode و dir_fd پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.2: پارامتر exist_ok افزوده شد.

تغییر یافته در نسخه‌ی 3.4.1: پیش از پایتون 3.4.1، اگر exist_ok برابر True بود و پوشه وجود داشت، makedirs() همچنان در صورتی خطایی پرتاب می‌کرد که mode با حالت پوشه موجود مطابقت نداشت. از آن‌جا که پیاده‌سازی این رفتار به‌صورت ایمن غیرممکن بود، این رفتار در پایتون 3.4.1 حذف شد. به bpo-21082 مراجعه کنید.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

تغییر یافته در نسخه‌ی 3.7: آرگومان mode دیگر بر بیت‌های مجوز فایلِ پوشه‌های سطح میانی تازه ایجادشده تأثیر نمی‌گذارد.

os.mkfifo(path, mode=0o666, *, dir_fd=None)

یک FIFO (یک پایپ نام‌دار) به نام path با حالت عددی mode ایجاد می‌کند. مقدار فعلی umask ابتدا از حالت نقاب می‌شود.

این تابع همچنین می‌تواند از مسیرهای نسبی به توصیف‌گرهای پوشه پشتیبانی کند.

FIFOها پایپ‌هایی هستند که می‌توان مانند پرونده‌های معمولی به آن‌ها دسترسی داشت. FIFOها تا حذف شدنشان وجود دارند (برای مثال با os.unlink()). به‌طور کلی، FIFOها به‌عنوان محل ملاقات بین فرایندهای نوع «کلاینت» و «سرور» استفاده می‌شوند: سرور FIFO را برای خواندن باز می‌کند و کلاینت آن را برای نوشتن باز می‌کند. توجه داشته باشید که mkfifo() FIFO را باز نمی‌کند — فقط محل ملاقات را ایجاد می‌کند.

دسترس‌پذیری: Unix, not WASI.

تغییر یافته در نسخه‌ی 3.3: پارامتر dir_fd اضافه شد.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

os.mknod(path, mode=0o600, device=0, *, dir_fd=None)

یک گره سامانه فایل‌بندی (پرونده، پرونده ویژه دستگاه یا پایپ نام‌دار) به نام path ایجاد کنید. mode هم مجوزهای مورد استفاده و هم نوع گرهی که ایجاد می‌شود را مشخص می‌کند و به‌صورت OR بیتی با یکی از stat.S_IFREG، stat.S_IFCHR، stat.S_IFBLK و stat.S_IFIFO ترکیب می‌شود (این ثابت‌ها در stat در دسترس هستند). برای stat.S_IFCHR و stat.S_IFBLK، device پرونده ویژه دستگاهی را که به‌تازگی ایجاد شده است تعریف می‌کند (احتمالاً با استفاده از os.makedev())، در غیر این صورت نادیده گرفته می‌شود.

این تابع همچنین می‌تواند از مسیرهای نسبی به توصیف‌گرهای پوشه پشتیبانی کند.

دسترس‌پذیری: Unix, not WASI.

تغییر یافته در نسخه‌ی 3.3: پارامتر dir_fd اضافه شد.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

os.major(device, /)

شماره اصلی دستگاه را از یک شماره خام دستگاه استخراج کنید (معمولاً فیلد st_dev یا st_rdev از stat).

os.minor(device, /)

شماره فرعی دستگاه را از یک شماره خام دستگاه استخراج کنید (معمولاً فیلد st_dev یا st_rdev از stat).

os.makedev(major, minor, /)

یک شماره‌ی دستگاه خام را از شماره‌های دستگاه اصلی و فرعی تشکیل دهید.

os.pathconf(path, name)

اطلاعات پیکربندی سیستم مربوط به یک پرونده نام‌گذاری‌شده را برمی‌گرداند. name مقدار پیکربندی برای بازیابی را مشخص می‌کند؛ ممکن است یک رشته باشد که نام یک مقدار سیستمی تعریف‌شده است؛ این نام‌ها در تعدادی از استانداردها مشخص شده‌اند (POSIX.1، Unix 95، Unix 98 و سایر موارد). برخی سکوها نیز نام‌های اضافی تعریف می‌کنند. نام‌های شناخته‌شده برای سیستم‌عامل میزبان در دیکشنری pathconf_names آمده‌اند. برای متغیرهای پیکربندی که در آن نگاشت گنجانده نشده‌اند، ارسال یک عدد صحیح برای name نیز پذیرفته می‌شود.

اگر name یک رشته باشد و شناخته‌شده نباشد، ValueError پرتاب می‌شود. اگر مقدار خاصی برای name توسط سیستم میزبان پشتیبانی نشود، حتی اگر در pathconf_names وجود داشته باشد، یک OSError با errno.EINVAL به‌عنوان شماره خطا پرتاب می‌شود.

این تابع می‌تواند از مشخص کردن یک توصیف‌گر پرونده پشتیبانی کند.

دسترس‌پذیری: Unix.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

os.pathconf_names

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

دسترس‌پذیری: Unix.

رشته‌ای را برمی‌گرداند که نشان‌دهنده‌ی مسیری است که پیوند نمادین به آن اشاره می‌کند. نتیجه ممکن است یک مسیر مطلق یا نسبی باشد؛ اگر نسبی باشد، می‌توان آن را با استفاده از os.path.join(os.path.dirname(path), result) به یک مسیر مطلق تبدیل کرد.

اگر path یک شیء رشته باشد (به‌طور مستقیم یا غیرمستقیم از طریق یک رابط PathLike)، نتیجه نیز یک شیء رشته خواهد بود و ممکن است این فراخوانی یک UnicodeDecodeError را پرتاب کند. اگر path یک شیء بایت باشد (به‌طور مستقیم یا غیرمستقیم)، نتیجه یک شیء بایت خواهد بود.

این تابع همچنین می‌تواند از مسیرهای نسبی به توصیف‌گرهای پوشه پشتیبانی کند.

هنگام تلاش برای تعیین مسیری که ممکن است شامل پیوندها باشد، برای مدیریت صحیح بازگشت و تفاوت‌های میان سکوها از realpath() استفاده کنید.

دسترس‌پذیری: Unix, Windows.

تغییر یافته در نسخه‌ی 3.2: پشتیبانی از پیوندهای نمادین ویندوز 6.0 (ویستا) افزوده شد.

تغییر یافته در نسخه‌ی 3.3: پارامتر dir_fd اضافه شد.

تغییر یافته در نسخه‌ی 3.6: در یونیکس، یک شیء شبه‌مسیر را می‌پذیرد.

تغییر یافته در نسخه‌ی 3.8: در ویندوز، یک path-like object و یک شیء bytes را می‌پذیرد.

پشتیبانی از اتصال‌های پوشه (directory junctions) افزوده شد و تغییر کرد تا به‌جای فیلد اختیاری "print name" که پیش‌تر برگردانده می‌شد، مسیر جایگزینی (substitution path) را برگرداند (که معمولاً شامل پیشوند \\?\ است).

os.remove(path, *, dir_fd=None)

پرونده path را حذف می‌کند. اگر path یک پوشه باشد، یک OSError پرتاب می‌شود. برای حذف پوشه‌ها از rmdir() استفاده کنید. اگر پرونده وجود نداشته باشد، یک FileNotFoundError پرتاب می‌شود.

این تابع می‌تواند از مسیرهای نسبت به توصیف‌گرهای پوشه پشتیبانی کند.

در ویندوز، تلاش برای حذف پرونده‌ای که در حال استفاده است باعث پرتاب یک استثنا می‌شود؛ در یونیکس، مدخل پوشه حذف می‌شود اما فضای ذخیره‌سازی تخصیص‌یافته به پرونده تا زمانی که پرونده اصلی دیگر در حال استفاده نباشد، آزاد نمی‌شود.

این تابع از نظر معنایی با unlink() یکسان است.

یک رویداد حسابرسی os.remove را با آرگومان‌های path و dir_fd پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.3: پارامتر dir_fd اضافه شد.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

os.removedirs(name)

پوشه‌ها را به‌صورت بازگشتی حذف می‌کند. مانند rmdir() عمل می‌کند، با این تفاوت که اگر پوشه برگ با موفقیت حذف شود، removedirs() تلاش می‌کند هر پوشه والد ذکرشده در path را به‌ترتیب حذف کند تا زمانی که خطایی پرتاب شود (این خطا نادیده گرفته می‌شود، زیرا معمولاً به این معناست که یک پوشه والد خالی نیست). برای مثال، os.removedirs('foo/bar/baz') ابتدا پوشه 'foo/bar/baz' را حذف می‌کند و سپس اگر 'foo/bar' و 'foo' خالی باشند، آن‌ها را حذف می‌کند. اگر پوشه برگ نتواند با موفقیت حذف شود، OSError پرتاب می‌شود.

یک رویداد حسابرسی os.remove را با آرگومان‌های path و dir_fd پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

os.rename(src, dst, *, src_dir_fd=None, dst_dir_fd=None)

نام پرونده یا پوشه src را به dst تغییر دهید. اگر dst وجود داشته باشد، عملیات در تعدادی از موارد با یک زیرکلاس از OSError شکست خواهد خورد:

در ویندوز، اگر dst وجود داشته باشد، همیشه FileExistsError پرتاب می‌شود. اگر src و dst روی سامانه فایل‌بندی‌های متفاوتی باشند، ممکن است این عملیات شکست بخورد. برای پشتیبانی از جابه‌جایی به سامانه فایل‌بندی‌ای دیگر، از shutil.move() استفاده کنید.

در یونیکس، اگر src یک پرونده و dst یک پوشه باشد یا برعکس، به‌ترتیب یک IsADirectoryError یا یک NotADirectoryError پرتاب می‌شود. اگر هر دو پوشه باشند و dst خالی باشد، dst بدون هیچ پیامی جایگزین می‌شود. اگر dst یک پوشه‌ی غیرخالی باشد، یک OSError پرتاب می‌شود. اگر هر دو پرونده باشند، در صورتی که کاربر اجازه داشته باشد، dst بدون هیچ پیامی جایگزین می‌شود. اگر src و dst روی سیستم‌پرونده‌های متفاوت باشند، این عملیات ممکن است در برخی گونه‌های یونیکس ناموفق باشد. در صورت موفقیت، تغییر نام یک عملیات اتمی خواهد بود (این یک الزام POSIX است).

این تابع می‌تواند از تعیین src_dir_fd و/یا dst_dir_fd برای فراهم کردن مسیرهای نسبی نسبت به توصیف‌گرهای پوشه پشتیبانی کند.

اگر می‌خواهید مقصد به‌صورت بین‌سکویی بازنویسی شود، از replace() استفاده کنید.

یک رویداد حسابرسی os.rename را با آرگومان‌های src، dst، src_dir_fd و dst_dir_fd پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.3: پارامترهای src_dir_fd و dst_dir_fd اضافه شدند.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را برای src و dst می‌پذیرد.

os.renames(old, new)

تابع تغییر نام بازگشتی پوشه یا پرونده. مانند rename() عمل می‌کند، با این تفاوت که ابتدا تلاش می‌شود هر پوشه‌ی میانی لازم برای معتبر شدن نام مسیر جدید ایجاد شود. پس از تغییر نام، پوشه‌های متناظر با سمت راست‌ترین بخش‌های مسیر نام قدیمی با استفاده از removedirs() حذف می‌شوند.

توجه

این تابع ممکن است با ساختار پوشه‌ای جدید ایجادشده با خطا مواجه شود، اگر دسترسی‌های موردنیاز برای حذف پوشه یا پرونده برگ را نداشته باشید.

یک رویداد حسابرسی os.rename را با آرگومان‌های src، dst، src_dir_fd و dst_dir_fd پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.6: برای old و new یک path-like object را می‌پذیرد.

os.replace(src, dst, *, src_dir_fd=None, dst_dir_fd=None)

نام پرونده یا پوشه‌ی src را به dst تغییر می‌دهد. اگر dst یک پوشه‌ی غیرخالی باشد، OSError پرتاب خواهد شد. اگر dst وجود داشته باشد و یک پرونده باشد، در صورتی که کاربر اجازه داشته باشد، به‌صورت بی‌صدا جایگزین می‌شود. ممکن است این عملیات در صورتی که src و dst بر روی سامانه فایل‌بندی‌های متفاوتی قرار داشته باشند، شکست بخورد. در صورت موفقیت، تغییر نام یک عملیات اتمی خواهد بود (این یک الزام POSIX است).

این تابع می‌تواند از تعیین src_dir_fd و/یا dst_dir_fd برای فراهم کردن مسیرهای نسبی نسبت به توصیف‌گرهای پوشه پشتیبانی کند.

یک رویداد حسابرسی os.rename را با آرگومان‌های src، dst، src_dir_fd و dst_dir_fd پرتاب می‌کند.

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

تغییر یافته در نسخه‌ی 3.6: یک path-like object را برای src و dst می‌پذیرد.

os.rmdir(path, *, dir_fd=None)

پوشه‌ی path را حذف (پاک) می‌کند. اگر پوشه وجود نداشته باشد یا خالی نباشد، به‌ترتیب FileNotFoundError یا OSError پرتاب می‌شود. برای حذف درخت‌های پوشه به‌طور کامل، می‌توان از shutil.rmtree() استفاده کرد.

این تابع می‌تواند از مسیرهای نسبت به توصیف‌گرهای پوشه پشتیبانی کند.

یک رویداد حسابرسی os.rmdir را با آرگومان‌های path و dir_fd پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.3: پارامتر dir_fd اضافه شد.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

os.scandir(path='.')

یک پیمایش‌گر از اشیای os.DirEntry متناظر با ورودی‌های موجود در پوشه مشخص‌شده با path برمی‌گرداند. ورودی‌ها با ترتیب دلخواه برگردانده می‌شوند و ورودی‌های ویژه '.' و '..' گنجانده نمی‌شوند. اگر پس از ایجاد پیمایش‌گر، پرونده‌ای از پوشه حذف یا به آن اضافه شود، اینکه ورودی‌ای برای آن پرونده گنجانده می‌شود یا نه، نامشخص است.

استفاده از scandir() به‌جای listdir() می‌تواند عملکرد کدی را که همچنین به اطلاعات نوع پرونده یا ویژگی‌های پرونده نیاز دارد، به‌طور قابل‌توجهی افزایش دهد، زیرا اشیاء os.DirEntry این اطلاعات را در صورتی در دسترس قرار می‌دهند که سیستم‌عامل آن را هنگام پویش یک پوشه فراهم کند. تمام متدهای os.DirEntry ممکن است یک فراخوانی سیستمی انجام دهند، اما is_dir() و is_file() معمولاً فقط برای پیوندهای نمادین به یک فراخوانی سیستمی نیاز دارند؛ os.DirEntry.stat() در یونیکس همیشه به یک فراخوانی سیستمی نیاز دارد، اما در ویندوز فقط برای پیوندهای نمادین به یک فراخوانی سیستمی نیاز دارد.

path می‌تواند یک شیء شبه‌مسیر باشد. اگر path از نوع bytes باشد (چه مستقیماً و چه به‌طور غیرمستقیم از طریق رابط PathLike)، نوع ویژگی‌های name و path در هر os.DirEntry، bytes خواهد بود؛ در تمام حالت‌های دیگر، آن‌ها از نوع str خواهند بود.

این تابع همچنین می‌تواند از تعیین یک توصیف‌گر پرونده پشتیبانی کند؛ توصیف‌گر پرونده باید به یک پوشه اشاره کند.

یک رویداد حسابرسی os.scandir را با آرگومان path پرتاب می‌کند.

پیمایش‌گر scandir() از پروتکل context manager پشتیبانی می‌کند و متد زیر را دارد:

scandir.close()

پیمایش‌گر را ببندید و منابع به‌دست‌آمده را آزاد کنید.

This is called automatically when the iterator is exhausted or garbage collected, or when an error happens during iterating. However it is advisable to call it explicitly or use the with statement.

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

مثال زیر استفاده‌ی ساده‌ای از scandir() را برای نمایش همه‌ی پرونده‌ها (به‌جز پوشه‌ها) در path داده‌شده نشان می‌دهد که با '.' شروع نمی‌شوند. فراخوانی entry.is_file() معمولاً فراخوانی سیستمی اضافی انجام نمی‌دهد:

with os.scandir(path) as it:
    for entry in it:
        if not entry.name.startswith('.') and entry.is_file():
            print(entry.name)

توجه

در سیستم‌های مبتنی بر یونیکس، scandir() از توابع opendir() و readdir() سیستم استفاده می‌کند. در ویندوز، از توابع FindFirstFileW و FindNextFileW Win32 استفاده می‌کند.

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

تغییر یافته در نسخه‌ی 3.6: پشتیبانی از پروتکل context manager و متد close() افزوده شد. اگر پیمایش‌گر scandir() نه به پایان رسیده باشد و نه به‌صراحت بسته شده باشد، یک ResourceWarning در تخریب‌کننده‌ی آن نمایش داده خواهد شد.

این تابع یک path-like object را می‌پذیرد.

تغییر یافته در نسخه‌ی 3.7: پشتیبانی از توصیف‌گرهای پرونده در یونیکس افزوده شد.

class os.DirEntry

شیء‌ای که توسط scandir() تولید می‌شود تا مسیر پرونده و سایر ویژگی‌های فایلِ یک ورودیِ پوشه را در دسترس قرار دهد.

scandir() تا حد امکان این اطلاعات را بدون انجام فراخوانی‌های سیستمی اضافی فراهم می‌کند. هنگامی که یک فراخوانی سیستمی stat() یا lstat() انجام می‌شود، شیء os.DirEntry نتیجه را در نهانگاه ذخیره می‌کند.

نمونه‌های os.DirEntry برای ذخیره‌سازی در ساختارهای داده‌ای با طول عمر زیاد در نظر گرفته نشده‌اند؛ اگر می‌دانید فراداده پرونده تغییر کرده است یا زمان زیادی از فراخوانی scandir() سپری شده است، برای دریافت اطلاعات به‌روز، os.stat(entry.path) را فراخوانی کنید.

از آنجا که متدهای os.DirEntry می‌توانند فراخوانی‌های سیستم‌عامل انجام دهند، ممکن است همچنین OSError را پرتاب کنند. اگر به کنترل بسیار ریزدانه‌ای بر خطاها نیاز دارید، می‌توانید هنگام فراخوانی یکی از متدهای os.DirEntry، OSError را بگیرید و به‌شکل مناسب مدیریت کنید.

برای آنکه مستقیماً به‌عنوان یک شیء شبه‌مسیر قابل‌استفاده باشد، os.DirEntry رابط PathLike را پیاده‌سازی می‌کند.

اشیای DirEntry نسبت به نوع مسیر عام هستند (str یا bytes).

ویژگی‌ها و متدهای یک نمونه os.DirEntry به شرح زیر است:

name

نام پرونده پایه‌ی ورودی، نسبت به آرگومان path در scandir().

اگر آرگومان path در scandir() از نوع bytes باشد، ویژگی name از نوع bytes خواهد بود و در غیر این صورت از نوع str خواهد بود. برای کدگشایی نام‌پرونده‌های بایتی از fsdecode() استفاده کنید.

path

نام مسیر ورودی: معادل os.path.join(scandir_path, entry.name) است که در آن scandir_path آرگومان path اصلی scandir() است. به‌جز نام پرونده، مسیر آرگومان اصلی scandir() را حفظ می‌کند. اگر آرگومان path برای scandir() نسبی بود، ویژگی path نیز نسبی است. تغییر پوشه کاری جاری پس از ایجاد پیمایش‌گر scandir() ممکن است باعث شود که در استفاده‌های بعدی، path به‌گونه‌ای متفاوت تفسیر شود. در برخی سکوها، ممکن است مسیر ساخته‌شده معتبر نباشد اگر آرگومان اصلی scandir() برای فهرست‌گیری قابل استفاده بود، اما برای پیوند با نام ورودی قابل استفاده نبود. اگر آرگومان path برای scandir() یک توصیف‌گر پرونده بود، ویژگی path همان ویژگی name است.

ویژگی path زمانی از نوع bytes خواهد بود که آرگومان path تابع scandir() از نوع bytes باشد و در غیر این صورت، از نوع str خواهد بود. برای کدگشایی نام پرونده‌های بایتی از fsdecode() استفاده کنید.

inode()

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

نتیجه در نهانگاه شیء os.DirEntry ذخیره می‌شود. برای دریافت اطلاعات به‌روز، از os.stat(entry.path, follow_symlinks=False).st_ino استفاده کنید.

در نخستین فراخوانی نهانگاه‌نشده، در ویندوز به یک فراخوانی سیستمی نیاز است، اما در یونیکس نیاز نیست.

is_dir(*, follow_symlinks=True)

اگر این ورودی یک پوشه یا یک پیوند نمادین باشد که به یک پوشه اشاره می‌کند، True را برمی‌گرداند؛ اگر ورودی هر نوع پرونده دیگری باشد یا به هر نوع پرونده دیگری اشاره کند، یا دیگر وجود نداشته باشد، False را برمی‌گرداند.

اگر follow_symlinks برابر False باشد، تنها در صورتی True را برمی‌گرداند که این ورودی یک پوشه باشد (بدون دنبال کردن پیوندهای نمادین)؛ اگر ورودی هر نوع پرونده دیگری باشد یا دیگر وجود نداشته باشد، False را برمی‌گرداند.

نتیجه در نهانگاه شیء os.DirEntry ذخیره می‌شود، با نهانگاهی جداگانه برای follow_symlinks True و False. برای دریافت اطلاعات به‌روز، os.stat() را همراه با stat.S_ISDIR() فراخوانی کنید.

در نخستین فراخوانی بدون نهانگاه، در بیشتر موارد نیازی به فراخوانی سیستمی نیست. به‌طور مشخص، برای مواردی که پیوند نمادین نیستند، نه ویندوز و نه یونیکس نیازی به فراخوانی سیستمی ندارند، مگر در برخی سیستم‌پرونده‌های یونیکس، مانند سیستم‌پرونده‌های شبکه، که dirent.d_type == DT_UNKNOWN را برمی‌گردانند. اگر ورودی یک پیوند نمادین باشد، برای دنبال کردن پیوند نمادین به یک فراخوانی سیستمی نیاز خواهد بود، مگر اینکه follow_symlinks برابر False باشد.

این متد ممکن است OSError را پرتاب کند، مانند PermissionError، اما FileNotFoundError گرفته می‌شود و پرتاب نمی‌شود.

is_file(*, follow_symlinks=True)

اگر این ورودی یک پرونده یا یک پیوند نمادین به یک پرونده باشد، True را برمی‌گرداند؛ اگر ورودی یک پوشه یا یک ورودی غیرفایل دیگر باشد یا به آن اشاره کند، یا دیگر وجود نداشته باشد، False را برمی‌گرداند.

اگر follow_symlinks برابر False باشد، تنها در صورتی True را برمی‌گرداند که این ورودی یک پرونده باشد (بدون دنبال کردن پیوندهای نمادین)؛ اگر ورودی یک پوشه یا ورودی دیگری غیر از پرونده باشد، یا دیگر وجود نداشته باشد، False را برمی‌گرداند.

نتیجه در شیء os.DirEntry در نهانگاه ذخیره می‌شود. ذخیره در نهانگاه، فراخوانی‌های سیستمی انجام‌شده و استثناهای پرتاب‌شده مطابق is_dir() هستند.

اگر این ورودی یک پیوند نمادین باشد (حتی اگر شکسته باشد)، True را برمی‌گرداند؛ اگر ورودی به یک پوشه یا هر نوع پرونده‌ای اشاره کند، یا دیگر وجود نداشته باشد، False را برمی‌گرداند.

نتیجه در نهانگاهِ شیء os.DirEntry ذخیره می‌شود. برای دریافت اطلاعات به‌روز، os.path.islink() را فراخوانی کنید.

در نخستین فراخوانی بدون نهانگاه، در بیشتر موارد نیازی به فراخوانی سیستمی نیست. به‌طور مشخص، نه ویندوز و نه یونیکس به فراخوانی سیستمی نیاز ندارند، مگر در برخی از سامانه فایل‌بندی‌های یونیکسی، مانند سامانه فایل‌بندی‌های شبکه، که dirent.d_type == DT_UNKNOWN را برمی‌گردانند.

این متد ممکن است OSError را پرتاب کند، مانند PermissionError، اما FileNotFoundError گرفته می‌شود و پرتاب نمی‌شود.

is_junction()

اگر این آیتم یک نقطه اتصال (junction) باشد (حتی اگر شکسته باشد)، True برمی‌گرداند؛ اگر آیتم به یک پوشه معمولی، هر نوع پرونده، یک پیوند نمادین اشاره کند یا دیگر وجود نداشته باشد، False برمی‌گرداند.

نتیجه در نهانگاه شیء os.DirEntry ذخیره می‌شود. برای دریافت اطلاعات به‌روز، os.path.isjunction() را فراخوانی کنید.

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

stat(*, follow_symlinks=True)

یک شیء stat_result برای این ورودی برمی‌گرداند. این متد به‌طور پیش‌فرض پیوندهای نمادین را دنبال می‌کند؛ برای گرفتن وضعیت (stat) یک پیوند نمادین، آرگومان follow_symlinks=False را اضافه کنید.

در یونیکس، این متد همیشه به یک فراخوانی سیستمی نیاز دارد. در ویندوز، تنها در صورتی به یک فراخوانی سیستمی نیاز دارد که follow_symlinks برابر True باشد و ورودی یک نقطه‌ی تحلیل مجدد (reparse point) باشد (برای مثال، یک پیوند نمادین یا یک اتصالِ پوشه (directory junction)).

در ویندوز، ویژگی‌های st_ino، st_dev و st_nlink از stat_result همیشه روی صفر تنظیم می‌شوند. برای دریافت این ویژگی‌ها، os.stat() را فراخوانی کنید.

نتیجه در شیء os.DirEntry در نهانگاه ذخیره می‌شود، با نهانگاه‌های جداگانه برای follow_symlinks True و False. برای دریافت اطلاعات به‌روز، os.stat() را فراخوانی کنید.

توجه داشته باشید که تناظر خوبی بین چندین ویژگی و متدِ os.DirEntry و pathlib.Path وجود دارد. به‌ویژه، ویژگی name معنای یکسانی دارد و متدهای is_dir()، is_file()، is_symlink()، is_junction() و stat() نیز معنای یکسانی دارند.

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

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

تغییر یافته در نسخه‌ی 3.12: ویژگی st_ctime در نتیجه‌ی stat در ویندوز منسوخ شده است. زمان ایجاد پرونده به‌درستی به‌عنوان st_birthtime در دسترس است و در آینده ممکن است st_ctime تغییر کند تا صفر یا زمان تغییر فراداده را، در صورت موجود بودن، برگرداند.

os.stat(path, *, dir_fd=None, follow_symlinks=True)

وضعیت یک پرونده یا توصیف‌گر پرونده را دریافت می‌کند. معادل فراخوانی سیستمی stat() روی مسیر داده‌شده را انجام می‌دهد. path می‌تواند به‌صورت یک رشته یا بایت -- به‌طور مستقیم یا غیرمستقیم از طریق رابط PathLike -- یا به‌عنوان یک توصیف‌گر پرونده باز مشخص شود. یک شیء stat_result برمی‌گرداند.

این تابع به‌طور معمول پیوندهای نمادین را دنبال می‌کند؛ برای گرفتن وضعیت (stat) یک پیوند نمادین، آرگومان follow_symlinks=False را اضافه کنید یا از lstat() استفاده کنید.

این تابع می‌تواند از تعیین یک توصیف‌گر پرونده و عدم دنبال‌کردن پیوندهای نمادین پشتیبانی کند.

در ویندوز، ارسال follow_symlinks=False دنبال کردن همه‌ی نقاط بازتفسیر جانشین نام (name-surrogate reparse points) را غیرفعال می‌کند؛ این نقاط شامل پیوندهای نمادین و اتصال‌های پوشه (directory junctions) می‌شوند. سایر انواع نقاط بازتفسیر (reparse points) که شبیه پیوند نیستند یا سیستم‌عامل قادر به دنبال کردن آن‌ها نیست، مستقیماً باز خواهند شد. هنگام دنبال کردن زنجیره‌ای از چند پیوند، این موضوع ممکن است باعث شود پیوند اصلی به‌جای موردی که پیوند نیست اما مانع پیمایش کامل شده است، بازگردانده شود. برای به‌دست آوردن نتایج stat برای مسیر نهایی در این حالت، از تابع os.path.realpath() استفاده کنید تا نام مسیر را تا حد ممکن حل کند و سپس lstat() را روی نتیجه فراخوانی کنید. این موضوع درباره‌ی پیوندهای نمادین آویزان (dangling symlinks) یا نقاط اتصال (junction points) صدق نمی‌کند؛ این موارد باعث ایجاد استثناهای معمول خواهند شد.

مثال:

>>> import os
>>> statinfo = os.stat('somefile.txt')
>>> statinfo
os.stat_result(st_mode=33188, st_ino=7876932, st_dev=234881026,
st_nlink=1, st_uid=501, st_gid=501, st_size=264, st_atime=1297230295,
st_mtime=1297230027, st_ctime=1297230027)
>>> statinfo.st_size
264

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

توابع fstat() و lstat().

تغییر یافته در نسخه‌ی 3.3: پارامترهای dir_fd و follow_symlinks افزوده شدند تا به‌جای مسیر، یک توصیف‌گر پرونده را مشخص کنند.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

تغییر یافته در نسخه‌ی 3.8: در ویندوز، اکنون تمام نقاط reparse (reparse points) که سیستم‌عامل قادر به حل آن‌ها است، دنبال می‌شوند، و ارسال follow_symlinks=False دنبال کردن تمام نقاط reparse جانشین نام (name surrogate reparse points) را غیرفعال می‌کند. اگر سیستم‌عامل به نقطه‌ی reparse برسد که نتواند آن را دنبال کند، stat اکنون به‌جای پرتاب خطا، اطلاعات مسیر اصلی را برمی‌گرداند، گویی follow_symlinks=False تعیین شده بود.

class os.stat_result

شیءای که ویژگی‌های آن تقریباً معادل اعضای ساختار stat است. این شیء برای نتیجه‌ی os.stat()، os.fstat() و os.lstat() استفاده می‌شود.

ویژگی‌ها:

st_mode

حالت پرونده: نوع پرونده و بیت‌های حالت پرونده (مجوزها).

st_ino

وابسته به پلتفرم است، اما اگر غیرصفر باشد، پرونده را برای یک مقدار مشخص از st_dev به‌طور یکتا شناسایی می‌کند. معمولاً:

st_dev

شناسه‌ی دستگاهی که این پرونده روی آن قرار دارد.

تعداد پیوندهای سخت.

st_uid

شناسه‌ی کاربری مالک پرونده.

st_gid

شناسه‌ی گروه مالک پرونده.

st_size

اندازه‌ی پرونده به بایت، در صورتی که یک پرونده معمولی یا پیوند نمادین باشد. اندازه‌ی یک پیوند نمادین برابر با طول نام مسیر موجود در آن است، بدون یک بایت نول (null byte) پایان‌دهنده.

برچسب‌های زمانی:

st_atime

زمان آخرین دسترسی، بیان‌شده بر حسب ثانیه.

st_mtime

زمان آخرین تغییر محتوا، بیان‌شده بر حسب ثانیه.

st_ctime

زمان آخرین تغییر فراداده، بیان‌شده بر حسب ثانیه.

تغییر یافته در نسخه‌ی 3.12: st_ctime در ویندوز منسوخ شده است. برای زمان ایجاد پرونده از st_birthtime استفاده کنید. در آینده، st_ctime شامل زمان آخرین تغییر فراداده خواهد بود، مانند سایر سکوهای دیگر.

st_atime_ns

زمان آخرین دسترسی بر حسب نانوثانیه به‌صورت عدد صحیح بیان می‌شود.

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

st_mtime_ns

زمان آخرین تغییر محتوا، بیان‌شده بر حسب نانوثانیه به‌صورت عدد صحیح.

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

st_ctime_ns

زمان آخرین تغییر فراداده، بیان‌شده بر حسب نانوثانیه به‌صورت عدد صحیح.

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

تغییر یافته در نسخه‌ی 3.12: st_ctime_ns در ویندوز منسوخ شده است. برای زمان ایجاد پرونده از st_birthtime_ns استفاده کنید. در آینده، st_ctime حاوی زمان آخرین تغییر فراداده خواهد بود، همان‌گونه که برای سایر پلتفرم‌ها است.

st_birthtime

زمان ایجاد پرونده که بر حسب ثانیه بیان می‌شود. این ویژگی همیشه در دسترس نیست و ممکن است AttributeError را پرتاب کند.

تغییر یافته در نسخه‌ی 3.12: st_birthtime اکنون در ویندوز در دسترس است.

st_birthtime_ns

زمان ایجاد پرونده، بیان‌شده بر حسب نانوثانیه به‌صورت عدد صحیح. این ویژگی همیشه در دسترس نیست و ممکن است AttributeError را پرتاب کند.

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

توجه

معنای دقیق و دقت ویژگی‌های st_atime، st_mtime، st_ctime و st_birthtime به سیستم‌عامل و سامانه فایل‌بندی بستگی دارد. برای مثال، در سیستم‌های ویندوزی که از سیستم‌پرونده‌های FAT32 استفاده می‌کنند، st_mtime دقت ۲ ثانیه‌ای دارد و st_atime تنها دقت ۱ روزه دارد. برای جزئیات، مستندات سیستم‌عامل خود را ببینید.

به‌طور مشابه، اگرچه st_atime_ns، st_mtime_ns، st_ctime_ns و st_birthtime_ns همیشه بر حسب نانوثانیه بیان می‌شوند، بسیاری از سیستم‌ها دقت نانوثانیه‌ای فراهم نمی‌کنند. در سیستم‌هایی که دقت نانوثانیه‌ای فراهم می‌کنند، شیء ممیز شناوری که برای ذخیره st_atime، st_mtime، st_ctime و st_birthtime استفاده می‌شود نمی‌تواند تمام آن را حفظ کند، و بنابراین کمی نادقیق خواهد بود. اگر به برچسب‌های زمانی دقیق نیاز دارید، باید همیشه از st_atime_ns، st_mtime_ns، st_ctime_ns و st_birthtime_ns استفاده کنید.

در برخی سیستم‌های یونیکسی (مانند لینوکس)، ممکن است ویژگی‌های زیر نیز در دسترس باشند:

st_blocks

تعداد بلوک‌های ۵۱۲ بایتی تخصیص‌یافته برای پرونده. این مقدار ممکن است وقتی پرونده حفره‌هایی دارد، کوچک‌تر از st_size/512 باشد.

st_blksize

اندازه بلوک «ترجیحی» برای ورودی/خروجی کارآمد سامانه فایل‌بندی. نوشتن در یک پرونده با تکه‌های کوچک‌تر ممکن است منجر به خواندن-اصلاح-بازنویسی (read-modify-rewrite) ناکارآمد شود.

st_rdev

نوع دستگاه، در صورتی که آی‌نود یک دستگاه باشد.

st_flags

پرچم‌های تعریف‌شده توسط کاربر برای پرونده.

در سایر سیستم‌های یونیکسی (مانند FreeBSD)، ممکن است ویژگی‌های زیر در دسترس باشند (اما ممکن است تنها زمانی پر شده باشند که root سعی کند از آن‌ها استفاده کند):

st_gen

شماره‌ی نسل پرونده.

در Solaris و مشتقات آن، ممکن است ویژگی‌های زیر نیز در دسترس باشند:

st_fstype

رشته‌ای که به‌طور یکتا نوع سامانه فایل‌بندیِ حاوی پرونده را شناسایی می‌کند.

در سیستم‌های macOS، ممکن است ویژگی‌های زیر نیز در دسترس باشند:

st_rsize

اندازه واقعی پرونده.

st_creator

ایجادکننده‌ی پرونده.

st_type

نوع پرونده.

در سیستم‌های ویندوزی، ویژگی‌های زیر نیز در دسترس هستند:

st_file_attributes

ویژگی‌های پرونده در ویندوز: عضو dwFileAttributes از ساختار BY_HANDLE_FILE_INFORMATION که توسط GetFileInformationByHandle() بازگردانده می‌شود. ثابت‌های FILE_ATTRIBUTE_* <stat.FILE_ATTRIBUTE_ARCHIVE> را در ماژول stat ببینید.

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

st_reparse_tag

هنگامی که FILE_ATTRIBUTE_REPARSE_POINT در st_file_attributes تنظیم‌شده باشد، این فیلد شامل برچسبی است که نوع نقطه‌ی reparse (reparse point) را مشخص می‌کند. به ثابت‌های IO_REPARSE_TAG_* در ماژول stat مراجعه کنید.

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

برای سازگاری با نسخه‌های پیشین، یک نمونه stat_result نیز به‌صورت یک تاپل از حداقل ۱۰ عدد صحیح قابل دسترسی است که مهم‌ترین (و قابل حمل) اعضای ساختار stat را به ترتیب st_mode، st_ino، st_dev، st_nlink، st_uid، st_gid، st_size، st_atime، st_mtime، st_ctime ارائه می‌دهد. ممکن است برخی پیاده‌سازی‌ها آیتم‌های بیشتری را به انتهای آن اضافه کنند. برای سازگاری با نسخه‌های قدیمی‌تر پایتون، دسترسی به stat_result به‌صورت یک تاپل همیشه اعداد صحیح را برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.5: ویندوز اکنون در صورت موجود بودن، اندیس پرونده را به‌عنوان st_ino برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.7: عضو st_fstype برای Solaris و مشتقات آن افزوده شد.

تغییر یافته در نسخه‌ی 3.8: عضو st_reparse_tag در ویندوز اضافه شد.

تغییر یافته در نسخه‌ی 3.8: در ویندوز، عضو st_mode اکنون پرونده‌های ویژه را حسب مورد به‌عنوان S_IFCHR، S_IFIFO یا S_IFBLK شناسایی می‌کند.

تغییر یافته در نسخه‌ی 3.12: در ویندوز، st_ctime منسوخ شده است. در نهایت، این ویژگی برای سازگاری با سایر سکوها، شامل زمان آخرین تغییر فراداده خواهد شد، اما در حال حاضر همچنان شامل زمان ایجاد است. برای زمان ایجاد از st_birthtime استفاده کنید.

در ویندوز، st_ino اکنون ممکن است بسته به سامانه فایل‌بندی تا ۱۲۸ بیت باشد. پیش‌تر این مقدار از ۶۴ بیت بیشتر نمی‌شد و شناسه‌های پرونده بزرگ‌تر به‌صورت دلخواه فشرده می‌شدند.

در ویندوز، st_rdev دیگر مقداری برنمی‌گرداند. پیش‌تر، همان مقدار st_dev را شامل می‌شد که نادرست بود.

عضو st_birthtime در ویندوز افزوده شد.

os.statvfs(path)

یک فراخوانی سیستمی statvfs(3) روی مسیر داده‌شده انجام می‌دهد. مقدار بازگشتی یک statvfs_result است که ویژگی‌های آن، سامانه فایل‌بندی در مسیر داده‌شده را توصیف می‌کنند و با اعضای ساختار statvfs مطابقت دارند.

این تابع می‌تواند از مشخص کردن یک توصیف‌گر پرونده پشتیبانی کند.

دسترس‌پذیری: Unix.

تغییر یافته در نسخه‌ی 3.3: پشتیبانی از مشخص کردن path به‌عنوان یک توصیف‌گر پرونده باز (open file descriptor) افزوده شد.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

class os.statvfs_result

آمار سامانه فایل‌بندی بازگردانده‌شده توسط os.statvfs() و os.fstatvfs(). برای جزئیات بیشتر، statvfs(3) را ببینید.

f_bsize

اندازه بلوک.

f_frsize

اندازه‌ی قطعه.

f_blocks

تعداد بلوک‌های هم‌اندازه با f_frsize که سامانه فایل‌بندی می‌تواند در خود جای دهد.

f_bfree

تعداد بلوک‌های آزاد.

f_bavail

تعداد بلوک‌های آزاد برای کاربران بدون امتیاز.

f_files

تعداد ورودی‌های پرونده، آی‌نودها (inodes)، که سامانه فایل‌بندی می‌تواند شامل شود.

f_ffree

تعداد مدخل‌های آزاد پرونده.

f_favail

تعداد ورودی‌های آزاد پرونده برای کاربران فاقد امتیاز.

f_flag

نقاب بیتی از پرچم‌های سوار کردن (mount). پرچم‌های زیر تعریف شده‌اند: ST_RDONLY، ST_NOSUID، ST_NODEV، ST_NOEXEC، ST_SYNCHRONOUS، ST_MANDLOCK، ST_WRITE، ST_APPEND، ST_IMMUTABLE، ST_NOATIME، ST_NODIRATIME و ST_RELATIME.

f_namemax

حداکثر طول نام پرونده در سامانه فایل‌بندی. ممکن است محدودیت‌های خاص سیستم‌عامل، مانند Windows MAX_PATH و مواردی که در pathname(7) لینوکس توضیح داده شده‌اند، وجود داشته باشند.

f_fsid

شناسه‌ی سامانه فایل‌بندی.

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

پرچم‌های زیر در statvfs_result.f_flag استفاده می‌شوند.

os.ST_RDONLY

سامانه فایل‌بندی فقط‌خواندنی.

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

os.ST_NOSUID

بیت‌های setuid/setgid غیرفعال هستند یا پشتیبانی نمی‌شوند.

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

os.ST_NODEV

دسترسی به پرونده‌های ویژه‌ی دستگاه را ممنوع می‌کند.

دسترس‌پذیری: Linux.

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

os.ST_NOEXEC

جلوگیری از اجرای برنامه.

دسترس‌پذیری: Linux.

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

os.ST_SYNCHRONOUS

نوشتن‌ها بلافاصله همگام‌سازی می‌شوند.

دسترس‌پذیری: Linux.

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

os.ST_MANDLOCK

اجازه‌ی قفل‌های اجباری روی یک سامانه فایل‌بندی.

دسترس‌پذیری: Linux.

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

os.ST_WRITE

نوشتن روی پرونده/پوشه/پیوند نمادین.

دسترس‌پذیری: Linux.

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

os.ST_APPEND

پرونده فقط الحاقی.

دسترس‌پذیری: Linux.

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

os.ST_IMMUTABLE

پرونده تغییرناپذیر.

دسترس‌پذیری: Linux.

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

os.ST_NOATIME

زمان‌های دسترسی را به‌روزرسانی نکنید.

دسترس‌پذیری: Linux.

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

os.ST_NODIRATIME

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

دسترس‌پذیری: Linux.

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

os.ST_RELATIME

به‌روزرسانی atime نسبت به mtime/ctime.

دسترس‌پذیری: Linux.

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

os.supports_dir_fd

یک شیء set که نشان می‌دهد کدام‌یک از توابع ماژول os یک توصیف‌گر پرونده باز را برای پارامتر dir_fd خود می‌پذیرند. پلتفرم‌های مختلف امکانات متفاوتی ارائه می‌دهند، و قابلیت زیربنایی‌ای که پایتون برای پیاده‌سازی پارامتر dir_fd از آن استفاده می‌کند، در تمام پلتفرم‌هایی که پایتون از آن‌ها پشتیبانی می‌کند، در دسترس نیست. برای حفظ سازگاری، توابعی که ممکن است از dir_fd پشتیبانی کنند، همیشه اجازه‌ی مشخص کردن این پارامتر را می‌دهند، اما در صورت استفاده از این قابلیت هنگامی که به‌صورت محلی در دسترس نیست، یک استثنا پرتاب می‌کنند. (مشخص کردن None برای dir_fd همیشه در تمام پلتفرم‌ها پشتیبانی می‌شود.)

برای بررسی این‌که آیا یک تابع خاص برای پارامتر dir_fd خود یک توصیف‌گر پرونده باز را می‌پذیرد، از عملگر in روی supports_dir_fd استفاده کنید. به‌عنوان مثال، اگر os.stat() توصیف‌گرهای پرونده باز را برای dir_fd در پلتفرم محلی بپذیرد، این عبارت به‌صورت True ارزیابی می‌شود:

os.stat in os.supports_dir_fd

در حال حاضر پارامترهای dir_fd فقط روی پلتفرم‌های یونیکسی کار می‌کنند؛ هیچ‌کدام از آن‌ها در ویندوز کار نمی‌کنند.

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

os.supports_effective_ids

یک شیء set که نشان می‌دهد آیا os.access() در سکوی محلی اجازه می‌دهد که مقدار True برای پارامتر effective_ids آن تعیین شود. (تعیین False برای effective_ids همیشه در تمام سکوها پشتیبانی می‌شود.) اگر سکوی محلی آن را پشتیبانی کند، این مجموعه شامل os.access() خواهد بود؛ در غیر این صورت خالی خواهد بود.

این عبارت در صورتی به True ارزیابی می‌شود که os.access() روی پلتفرم محلی از effective_ids=True پشتیبانی کند:

os.access in os.supports_effective_ids

در حال حاضر effective_ids فقط در پلتفرم‌های یونیکسی پشتیبانی می‌شود؛ روی ویندوز کار نمی‌کند.

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

os.supports_fd

یک شیء set که نشان می‌دهد کدام توابع در ماژول os اجازه می‌دهند پارامتر path خود را به‌صورت یک توصیف‌گر پرونده باز در سکوی محلی مشخص کنید. سکوهای مختلف امکانات متفاوتی ارائه می‌دهند، و قابلیت زیربنایی که پایتون برای پذیرش توصیف‌گرهای پرونده باز به‌عنوان آرگومان‌های path استفاده می‌کند، در همه سکوهای پشتیبانی‌شده توسط پایتون در دسترس نیست.

برای تعیین اینکه آیا یک تابع خاص اجازه می‌دهد یک توصیف‌گر پرونده باز برای پارامتر path آن مشخص شود، از عملگر in بر روی supports_fd استفاده کنید. به‌عنوان مثال، اگر os.chdir() توصیف‌گرهای پرونده باز را برای path در سکوی محلی شما بپذیرد، این عبارت به مقدار True ارزیابی می‌شود:

os.chdir in os.supports_fd

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

یک شیء set که نشان می‌دهد کدام توابع در ماژول os در پلتفرم محلی، False را برای پارامتر follow_symlinks خود می‌پذیرند. پلتفرم‌های مختلف، قابلیت‌های متفاوتی ارائه می‌دهند و قابلیت زیربنایی‌ای که پایتون برای پیاده‌سازی follow_symlinks از آن استفاده می‌کند، در همه پلتفرم‌های مورد پشتیبانی پایتون در دسترس نیست. برای حفظ یکپارچگی، توابعی که ممکن است از follow_symlinks پشتیبانی کنند، همیشه اجازه‌ی تعیین این پارامتر را می‌دهند، اما در صورت استفاده از این قابلیت در زمانی که به‌صورت محلی در دسترس نیست، استثنا پرتاب می‌کنند. (تعیین True برای follow_symlinks همیشه در همه پلتفرم‌ها پشتیبانی می‌شود.)

برای بررسی اینکه آیا یک تابع خاص برای پارامتر follow_symlinks خود مقدار False را می‌پذیرد، از عملگر in روی supports_follow_symlinks استفاده کنید. به‌عنوان مثال، اگر هنگام فراخوانی os.stat() روی پلتفرم محلی بتوانید follow_symlinks=False را مشخص کنید، این عبارت به True ارزیابی می‌شود:

os.stat in os.supports_follow_symlinks

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

یک پیوند نمادین با نام dst ایجاد کنید که به src اشاره می‌کند.

پارامتر src به هدف پیوند (پرونده یا پوشه‌ای که به آن پیوند داده می‌شود) اشاره دارد، و dst نام پیوندی است که ایجاد می‌شود.

در ویندوز، یک پیوند نمادین نشان‌دهنده یک پرونده یا یک پوشه است و به‌صورت پویا به هدف تغییر شکل نمی‌دهد. اگر هدف موجود باشد، نوع پیوند نمادین متناسب با آن ایجاد می‌شود. در غیر این صورت، اگر target_is_directory برابر True باشد، پیوند نمادین به‌عنوان یک پوشه ایجاد می‌شود؛ در غیر این صورت پیوند نمادین به پرونده (حالت پیش‌فرض) ایجاد می‌شود. در پلتفرم‌های غیر ویندوزی، target_is_directory نادیده گرفته می‌شود.

این تابع می‌تواند از مسیرهای نسبت به توصیف‌گرهای پوشه پشتیبانی کند.

توجه

در نسخه‌های جدیدتر Windows 10، حساب‌های فاقد امتیاز در صورت فعال بودن حالت توسعه‌دهنده (Developer Mode) می‌توانند پیوندهای نمادینایجاد کنند. هنگامی که حالت توسعه‌دهنده در دسترس/فعال نباشد، به امتیاز SeCreateSymbolicLinkPrivilege نیاز است، یا فرایند باید به‌عنوان مدیر اجرا شود.

هنگامی که تابع توسط یک کاربر بدون امتیاز فراخوانی شود، OSError پرتاب می‌شود.

یک رویداد حسابرسی os.symlink را با آرگومان‌های src، dst و dir_fd پرتاب می‌کند.

دسترس‌پذیری: Unix, Windows.

این تابع در WASI محدود است، برای اطلاعات بیشتر سکوهای WebAssembly را ببینید.

تغییر یافته در نسخه‌ی 3.2: پشتیبانی از پیوندهای نمادین ویندوز 6.0 (ویستا) افزوده شد.

تغییر یافته در نسخه‌ی 3.3: پارامتر dir_fd افزوده شد و اکنون target_is_directory در سکوهای غیرویندوزی مجاز است.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را برای src و dst می‌پذیرد.

تغییر یافته در نسخه‌ی 3.8: پشتیبانی از پیوندهای نمادین بدون ارتقاء (unelevated symlinks) در ویندوز با حالت توسعه‌دهنده افزوده شد.

os.sync()

نوشتن همه‌چیز روی دیسک را اجباری می‌کند.

دسترس‌پذیری: Unix.

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

os.truncate(path, length)

پرونده متناظر با path را کوتاه کنید تا اندازه‌ی آن حداکثر length بایت باشد.

این تابع می‌تواند از مشخص کردن یک توصیف‌گر پرونده پشتیبانی کند.

یک رویداد حسابرسی os.truncate را با آرگومان‌های path و length پرتاب می‌کند.

دسترس‌پذیری: Unix, Windows.

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

تغییر یافته در نسخه‌ی 3.5: پشتیبانی از ویندوز اضافه شد

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

پرونده path را حذف (پاک کردن) می‌کند. این تابع از نظر معنایی با remove() یکسان است؛ نام unlink نام سنتی آن در یونیکس است. لطفاً برای اطلاعات بیشتر، مستندات remove() را ببینید.

یک رویداد حسابرسی os.remove را با آرگومان‌های path و dir_fd پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.3: پارامتر dir_fd اضافه شد.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

os.utime(path, times=None, *, [ns, ]dir_fd=None, follow_symlinks=True)

زمان‌های دسترسی و اصلاح پرونده مشخص‌شده با path را تنظیم می‌کند.

utime() دو پارامتر اختیاری می‌پذیرد، times و ns. این‌ها زمان‌هایی را که برای path تنظیم می‌شوند مشخص می‌کنند و به صورت زیر استفاده می‌شوند:

  • اگر ns تعیین‌شده باشد، باید یک تاپل دوتایی به شکل (atime_ns, mtime_ns) باشد که هر عضو آن یک عدد صحیح بیانگر نانوثانیه باشد.

  • اگر times برابر None نباشد، باید یک تاپل دوتایی به شکل (atime, mtime) باشد که هر عضو آن یک int یا float بیان‌کننده‌ی ثانیه‌ها است.

  • اگر times برابر None باشد و ns مشخص نشده باشد، این معادل مشخص کردن ns=(atime_ns, mtime_ns) است که در آن هر دو زمان، زمان فعلی هستند.

مشخص کردن تاپل‌ها برای هر دو times و ns خطا است.

توجه داشته باشید که زمان‌های دقیقی که در اینجا تنظیم می‌کنید ممکن است توسط یک فراخوانی بعدی stat() برگردانده نشوند، بسته به میزان دقتی که سیستم‌عامل شما زمان‌های دسترسی و تغییر را ثبت می‌کند؛ stat() را ببینید. بهترین راه برای حفظ زمان‌های دقیق، استفاده از فیلدهای st_atime_ns و st_mtime_ns از شیء نتیجه‌ی os.stat() به‌همراه پارامتر ns برای utime() است.

این تابع می‌تواند از مشخص کردن یک توصیف‌گر پرونده، مسیرهای نسبی به توصیف‌گرهای پوشه و دنبال‌نکردن پیوندهای نمادین پشتیبانی کند.

یک رویداد حسابرسی os.utime را با آرگومان‌های path، times، ns و dir_fd پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.3: پشتیبانی برای مشخص کردن path به‌عنوان یک توصیف‌گر پرونده باز، و پارامترهای dir_fd، follow_symlinks و ns افزوده شد.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

os.walk(top, topdown=True, onerror=None, followlinks=False)

نام پرونده‌های یک درخت پوشه را با پیمایش درخت از بالا به پایین یا از پایین به بالا تولید می‌کند. برای هر پوشه در درختی که ریشه آن پوشه top است (از جمله خود top)، یک ۳-تایی (dirpath, dirnames, filenames) برمی‌گرداند.

dirpath یک رشته است، مسیر پوشه. dirnames فهرستی از نام‌های زیرپوشه‌های درون dirpath است (شامل پیوندهای نمادینبه پوشه‌ها، و به‌جز '.' و '..'). filenames فهرستی از نام‌های پرونده‌های غیرپوشه‌ای درون dirpath است. توجه داشته باشید که نام‌های درون فهرست‌ها شامل هیچ‌یک از کامپوننت‌های مسیر نیستند. برای به‌دست آوردن مسیر کامل (که با top شروع می‌شود) برای یک پرونده یا پوشه در dirpath، از os.path.join(dirpath, name) استفاده کنید. این که فهرست‌ها مرتب باشند یا نه، به سامانه فایل‌بندی بستگی دارد. اگر در حین تولید فهرست‌ها، پرونده‌ای از پوشه dirpath حذف یا به آن اضافه شود، این که نام آن پرونده در فهرست‌ها گنجانده شود یا نه، نامشخص است.

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

هنگامی که topdown برابر True باشد، فراخواننده می‌تواند فهرست dirnames را به‌صورت درجا تغییر دهد (شاید با استفاده از del یا انتساب اسلایسی)، و walk() فقط به‌صورت بازگشتی وارد زیرپوشه‌هایی خواهد شد که نامشان در dirnames باقی مانده است؛ این می‌تواند برای هرس جستجو، اعمال ترتیب مشخص برای بازدید، یا حتی اطلاع دادن به walk() درباره پوشه‌هایی استفاده شود که فراخواننده پیش از آنکه walk() را دوباره از سر بگیرد، ایجاد یا تغییر نام می‌دهد. تغییر dirnames هنگامی که topdown برابر False باشد، تأثیری بر رفتار پیمایش ندارد، زیرا در حالت پایین‌به‌بالا، پوشه‌های موجود در dirnames پیش از آنکه خود dirpath تولید شود، تولید می‌شوند.

به‌طور پیش‌فرض، خطاهای حاصل از فراخوانی scandir() نادیده گرفته می‌شوند. اگر آرگومان اختیاری onerror مشخص شده باشد، باید یک تابع باشد؛ این تابع با یک آرگومان فراخوانی می‌شود که یک نمونه از OSError است. این تابع می‌تواند خطا را گزارش دهد تا پیمایش ادامه یابد، یا استثنا را پرتاب کند تا پیمایش متوقف شود. توجه داشته باشید که نام پرونده به‌عنوان ویژگی filename شیء استثنا در دسترس است.

به‌طور پیش‌فرض، walk() وارد پیوندهای نمادینی که به پوشه‌ها اشاره دارند نمی‌شود. برای بازدید از پوشه‌هایی که پیوندهای نمادین به آن‌ها اشاره دارند، در سیستم‌هایی که از آن‌ها پشتیبانی می‌کنند، followlinks را روی True تنظیم کنید.

توجه

توجه داشته باشید که تنظیم followlinks روی True می‌تواند منجر به بازگشت بی‌پایان شود، اگر پیوندی به پوشه‌ی والد خود اشاره کند. walk() پوشه‌هایی را که پیش‌تر بازدید کرده است پیگیری نمی‌کند.

توجه

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

این مثال تعداد بایت‌های اشغال‌شده توسط پرونده‌های غیرپوشه‌ای را در هر پوشه زیر پوشه‌ی شروع نمایش می‌دهد، به‌جز این که در هیچ زیرپوشه‌ی __pycache__ جستجو نمی‌کند:

import os
from os.path import join, getsize
for root, dirs, files in os.walk('python/Lib/xml'):
    print(root, "consumes", end=" ")
    print(sum(getsize(join(root, name)) for name in files), end=" ")
    print("bytes in", len(files), "non-directory files")
    if '__pycache__' in dirs:
        dirs.remove('__pycache__')  # don't visit __pycache__ directories

در مثال بعدی (پیاده‌سازی ساده‌ای از shutil.rmtree())، پیمایش درخت از پایین به بالا ضروری است؛ rmdir() اجازه‌ی حذف یک پوشه پیش از خالی شدن آن را نمی‌دهد:

# Delete everything reachable from the directory named in "top",
# assuming there are no symbolic links.
# CAUTION:  This is dangerous!  For example, if top == '/', it
# could delete all your disk files.
import os
for root, dirs, files in os.walk(top, topdown=False):
    for name in files:
        os.remove(os.path.join(root, name))
    for name in dirs:
        os.rmdir(os.path.join(root, name))
os.rmdir(top)

یک رویداد حسابرسی os.walk را با آرگومان‌های top، topdown، onerror و followlinks پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.5: این تابع اکنون به جای os.listdir()، os.scandir() را فراخوانی می‌کند و با کاهش تعداد فراخوانی‌های os.stat()، سریع‌تر می‌شود.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

os.fwalk(top='.', topdown=True, onerror=None, *, follow_symlinks=False, dir_fd=None)

این دقیقاً مانند walk() رفتار می‌کند، با این تفاوت که یک ۴-تایی (dirpath, dirnames, filenames, dirfd) تولید می‌کند و از dir_fd پشتیبانی می‌کند.

dirpath، dirnames و filenames با خروجی walk() یکسان هستند، و dirfd یک توصیف‌گر پرونده است که به پوشه‌ی dirpath اشاره می‌کند.

این تابع همیشه از مسیرهای نسبی نسبت به توصیف‌گرهای پوشه و عدم دنبال‌کردن پیوندهای نمادین پشتیبانی می‌کند. با این حال توجه داشته باشید که برخلاف سایر توابع، مقدار پیش‌فرض follow_symlinks در fwalk() برابر False است.

توجه

از آن‌جا که fwalk() توصیف‌گرهای پرونده را برمی‌گرداند، آن‌ها فقط تا گام بعدی تکرار معتبر هستند؛ بنابراین اگر می‌خواهید آن‌ها را برای مدت طولانی‌تری نگه دارید، باید آن‌ها را تکثیر کنید (برای مثال با dup()).

این مثال تعداد بایت‌های اشغال‌شده توسط پرونده‌های غیرپوشه‌ای را در هر پوشه زیر پوشه‌ی شروع نمایش می‌دهد، به‌جز این که در هیچ زیرپوشه‌ی __pycache__ جستجو نمی‌کند:

import os
for root, dirs, files, rootfd in os.fwalk('python/Lib/xml'):
    print(root, "consumes", end=" ")
    print(sum([os.stat(name, dir_fd=rootfd).st_size for name in files]),
          end=" ")
    print("bytes in", len(files), "non-directory files")
    if '__pycache__' in dirs:
        dirs.remove('__pycache__')  # don't visit __pycache__ directories

در مثال بعدی، پیمایش درخت از پایین به بالا ضروری است: rmdir() اجازه‌ی حذف یک پوشه را پیش از خالی بودن آن نمی‌دهد:

# Delete everything reachable from the directory named in "top",
# assuming there are no symbolic links.
# CAUTION:  This is dangerous!  For example, if top == '/', it
# could delete all your disk files.
import os
for root, dirs, files, rootfd in os.fwalk(top, topdown=False):
    for name in files:
        os.unlink(name, dir_fd=rootfd)
    for name in dirs:
        os.rmdir(name, dir_fd=rootfd)

رویداد حسابرسی os.fwalk را با آرگومان‌های top، topdown، onerror، follow_symlinks و dir_fd پرتاب می‌کند.

دسترس‌پذیری: Unix.

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

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

تغییر یافته در نسخه‌ی 3.7: پشتیبانی از مسیرهای bytes افزوده شد.

os.memfd_create(name[, flags=os.MFD_CLOEXEC])

یک پرونده ناشناس ایجاد می‌کند و یک توصیف‌گر پرونده که به آن اشاره دارد برمی‌گرداند. flags باید یکی از ثابت‌های os.MFD_* در دسترس روی سیستم باشد (یا ترکیبی از آن‌ها با عملگر بیتی OR). به‌طور پیش‌فرض، توصیف‌گر پرونده جدید غیرقابل ارث‌بردن است.

نام ارائه‌شده در name به‌عنوان نام پرونده استفاده می‌شود و به‌عنوان هدف پیوند نمادین متناظر در پوشه /proc/self/fd/ نمایش داده می‌شود. نام نمایش‌داده‌شده همیشه دارای پیشوند memfd: است و فقط برای اهداف اشکال‌زدایی به کار می‌رود. نام‌ها بر رفتار توصیف‌گر پرونده تأثیری ندارند، و بنابراین چندین پرونده می‌توانند بدون هیچ‌گونه عوارض جانبی نام یکسانی داشته باشند.

دسترس‌پذیری: Linux >= 3.17 with glibc >= 2.27.

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

os.MFD_CLOEXEC
os.MFD_ALLOW_SEALING
os.MFD_HUGETLB
os.MFD_HUGE_SHIFT
os.MFD_HUGE_MASK
os.MFD_HUGE_64KB
os.MFD_HUGE_512KB
os.MFD_HUGE_1MB
os.MFD_HUGE_2MB
os.MFD_HUGE_8MB
os.MFD_HUGE_16MB
os.MFD_HUGE_32MB
os.MFD_HUGE_256MB
os.MFD_HUGE_512MB
os.MFD_HUGE_1GB
os.MFD_HUGE_2GB
os.MFD_HUGE_16GB

این پرچم‌ها را می‌توان به memfd_create() ارسال کرد.

دسترس‌پذیری: Linux >= 3.17 with glibc >= 2.27

پرچم‌های MFD_HUGE* تنها از لینوکس 4.14 در دسترس هستند.

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

os.eventfd(initval[, flags=os.EFD_CLOEXEC])

یک توصیف‌گر پرونده رویداد ایجاد می‌کند و آن را بازمی‌گرداند. این توصیف‌گر پرونده از read() و write() خام با اندازه‌ی بافر ۸، select()، poll() و موارد مشابه پشتیبانی می‌کند. برای اطلاعات بیشتر، صفحه‌ی man eventfd(2) را ببینید. به‌طور پیش‌فرض، توصیف‌گر پرونده جدید غیرقابل ارث‌بردن است.

initval مقدار اولیه شمارنده رویداد است. مقدار اولیه باید یک عدد صحیح بدون علامت ۳۲ بیتی باشد. لطفاً توجه داشته باشید که مقدار اولیه به یک عدد صحیح بدون علامت ۳۲ بیتی محدود است، اگرچه شمارنده رویداد یک عدد صحیح بدون علامت ۶۴ بیتی با بیشینه مقدار 264-2 است.

flags را می‌توان از EFD_CLOEXEC، EFD_NONBLOCK و EFD_SEMAPHORE ساخت.

اگر EFD_SEMAPHORE تعیین شده باشد و شمارنده رویداد غیرصفر باشد، eventfd_read() مقدار ۱ را برمی‌گرداند و شمارنده را یک واحد کاهش می‌دهد.

اگر EFD_SEMAPHORE مشخص نشده باشد و شمارنده رویداد غیرصفر باشد، eventfd_read() مقدار فعلی شمارنده رویداد را برمی‌گرداند و شمارنده را به صفر بازنشانی می‌کند.

اگر شمارنده رویداد صفر باشد و EFD_NONBLOCK مشخص نشده باشد، eventfd_read() مسدود می‌شود.

eventfd_write() شمارنده رویداد را افزایش می‌دهد. نوشتن زمانی مسدود می‌شود که عملیات نوشتن بخواهد شمارنده را به مقداری بزرگ‌تر از 264-2 افزایش دهد.

مثال:

import os

# semaphore with start value '1'
fd = os.eventfd(1, os.EFD_SEMAPHORE | os.EFD_CLOEXEC)
try:
    # acquire semaphore
    v = os.eventfd_read(fd)
    try:
        do_work()
    finally:
        # release semaphore
        os.eventfd_write(fd, v)
finally:
    os.close(fd)

دسترس‌پذیری: Linux >= 2.6.27 with glibc >= 2.8

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

os.eventfd_read(fd)

مقدار را از یک توصیف‌گر پرونده eventfd() می‌خواند و یک عدد صحیح بدون علامت ۶۴ بیتی برمی‌گرداند. این تابع بررسی نمی‌کند که fd یک eventfd() باشد.

دسترس‌پذیری: Linux >= 2.6.27

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

os.eventfd_write(fd, value)

افزودن مقدار به یک توصیف‌گر پرونده eventfd(). value باید یک عدد صحیح بدون علامت ۶۴ بیتی باشد. این تابع بررسی نمی‌کند که fd یک eventfd() باشد.

دسترس‌پذیری: Linux >= 2.6.27

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

os.EFD_CLOEXEC

تنظیم پرچم close-on-exec برای توصیف‌گر پرونده جدید eventfd().

دسترس‌پذیری: Linux >= 2.6.27

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

os.EFD_NONBLOCK

تنظیم پرچم وضعیت O_NONBLOCK برای توصیف‌گر پرونده جدید eventfd().

دسترس‌پذیری: Linux >= 2.6.27

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

os.EFD_SEMAPHORE

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

دسترس‌پذیری: Linux >= 2.6.30

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

توصیف‌گرهای پرونده زمان‌سنج

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

این توابع پشتیبانی از API توصیف‌گر پرونده تایمر (timer file descriptor) لینوکس را فراهم می‌کنند. طبیعتاً، همه‌ی آن‌ها فقط در لینوکس در دسترس هستند.

os.timerfd_create(clockid, /, *, flags=0)

ایجاد و بازگرداندن یک توصیف‌گر پرونده زمان‌سنج (timerfd).

توصیف‌گر پرونده برگردانده‌شده توسط timerfd_create() از موارد زیر پشتیبانی می‌کند:

می‌توان متد read() توصیف‌گر پرونده را با اندازه بافر ۸ فراخوانی کرد. اگر زمان‌سنج پیش‌تر یک یا چند بار منقضی شده باشد، read() تعداد دفعات انقضا را با ترتیب بایت‌های میزبان برمی‌گرداند، که می‌توان آن را با int.from_bytes(x, byteorder=sys.byteorder) به یک int تبدیل کرد.

می‌توان از select() و poll() برای منتظر ماندن تا منقضی شدن زمان‌سنج و قابل خواندن شدن توصیف‌گر پرونده استفاده کرد.

clockid باید یک شناسه ساعت (clock ID) معتبر باشد، همان‌طور که در ماژول time تعریف شده است:

If clockid is time.CLOCK_REALTIME, a settable system-wide real-time clock is used. If the system clock is changed, the timer setting needs to be updated. To cancel the timer when the system clock is changed, see TFD_TIMER_CANCEL_ON_SET.

اگر clockid برابر time.CLOCK_MONOTONIC باشد، از ساعتی غیرقابل‌تنظیم استفاده می‌شود که به‌صورت یکنواخت افزایش می‌یابد. حتی اگر ساعت سیستم تغییر کند، تنظیم زمان‌سنج تحت تأثیر قرار نمی‌گیرد.

If clockid is time.CLOCK_BOOTTIME, it is the same as time.CLOCK_MONOTONIC except it includes any time that the system is suspended.

می‌توان رفتار توصیف‌گر پرونده را با تعیین یک مقدار flags تغییر داد. می‌توان از هر یک از متغیرهای زیر استفاده کرد و آن‌ها را با OR بیتی (عملگر |) ترکیب کرد:

If TFD_NONBLOCK is not set as a flag, read() blocks until the timer expires. If it is set as a flag, read() doesn't block, but if there hasn't been an expiration since the last call to read, read() raises OSError with errno set to errno.EAGAIN.

TFD_CLOEXEC همواره به‌صورت خودکار توسط پایتون تنظیم می‌شود.

توصیف‌گر پرونده باید هنگامی که دیگر نیازی به آن نیست، با os.close() بسته شود، در غیر این صورت توصیف‌گر پرونده نشت خواهد کرد.

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

صفحه‌ی man مربوط به timerfd_create(2).

دسترس‌پذیری: Linux >= 2.6.27 with glibc >= 2.8

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

os.timerfd_settime(fd, /, *, flags=0, initial=0.0, interval=0.0)

زمان‌سنج داخلی یک توصیف‌گر پرونده زمان‌سنج را تغییر می‌دهد. این تابع همان زمان‌سنج بازه‌ای timerfd_settime_ns() را مدیریت می‌کند.

fd باید یک توصیف‌گر پرونده زمان‌سنج معتبر باشد.

رفتار زمان‌سنج را می‌توان با تعیین یک مقدار flags تغییر داد. می‌توان از هر یک از متغیرهای زیر استفاده کرد و آن‌ها را با OR بیتی (عملگر |) ترکیب کرد:

The timer is disabled by setting initial to zero (0). If initial is greater than zero, the timer is enabled. If initial is less than zero, it raises an OSError exception with errno set to errno.EINVAL.

By default the timer will fire when initial seconds have elapsed.

با این حال، اگر پرچم TFD_TIMER_ABSTIME تنظیم شده باشد، تایمر زمانی فعال می‌شود که ساعت تایمر (که با clockid در timerfd_create() تنظیم می‌شود) به initial ثانیه برسد.

The timer's interval is set by the interval float. If interval is zero, the timer only fires once, on the initial expiration. If interval is greater than zero, the timer fires every time interval seconds have elapsed since the previous expiration. If interval is less than zero, it raises OSError with errno set to errno.EINVAL.

If the TFD_TIMER_CANCEL_ON_SET flag is set along with TFD_TIMER_ABSTIME and the clock for this timer is time.CLOCK_REALTIME, the timer is marked as cancelable if the real-time clock is changed discontinuously. Reading the descriptor is aborted with the error errno.ECANCELED.

لینوکس ساعت سیستم را به‌صورت UTC مدیریت می‌کند. انتقال ساعت تابستانی تنها با تغییر آفست زمان (time offset) انجام می‌شود و باعث تغییر ناپیوسته ساعت سیستم نمی‌شود.

رویدادهای زیر موجب تغییر ناپیوسته ساعت سیستم خواهند شد:

  • settimeofday

  • clock_settime

  • تاریخ و زمان سیستم را با دستور date تنظیم کنید

یک تاپل دو آیتمی شامل (next_expiration, interval) را از وضعیت پیشین تایمر، پیش از اجرای این تابع برمی‌گرداند.

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

timerfd_create(2)، timerfd_settime(2)، settimeofday(2)، clock_settime(2) و date(1).

دسترس‌پذیری: Linux >= 2.6.27 with glibc >= 2.8

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

os.timerfd_settime_ns(fd, /, *, flags=0, initial=0, interval=0)

مشابه timerfd_settime()، اما از زمان به‌صورت نانوثانیه استفاده می‌کند. این تابع همان زمان‌سنج بازه‌ای timerfd_settime() را به کار می‌گیرد.

دسترس‌پذیری: Linux >= 2.6.27 with glibc >= 2.8

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

os.timerfd_gettime(fd, /)

یک تاپل ۲ آیتمی از مقادیر float (next_expiration، interval) برمی‌گرداند.

next_expiration زمان نسبی تا فعال شدن بعدی زمان‌سنج را نشان می‌دهد، صرف‌نظر از اینکه پرچم TFD_TIMER_ABSTIME تنظیم شده باشد.

interval نشان‌دهنده‌ی فاصله‌ی زمانی تایمر است. اگر صفر باشد، تایمر تنها یک‌بار، پس از سپری شدن next_expiration ثانیه، فعال می‌شود.

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

timerfd_gettime(2)

دسترس‌پذیری: Linux >= 2.6.27 with glibc >= 2.8

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

os.timerfd_gettime_ns(fd, /)

مشابه timerfd_gettime()، اما زمان را به‌صورت نانوثانیه برمی‌گرداند.

دسترس‌پذیری: Linux >= 2.6.27 with glibc >= 2.8

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

os.TFD_NONBLOCK

پرچمی برای تابع timerfd_create()، که پرچم وضعیت O_NONBLOCK را برای توصیف‌گر پرونده زمان‌سنج جدید تنظیم می‌کند. اگر TFD_NONBLOCK به‌عنوان پرچم تنظیم نشده باشد، read() مسدود می‌شود.

دسترس‌پذیری: Linux >= 2.6.27 with glibc >= 2.8

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

os.TFD_CLOEXEC

پرچمی برای تابع timerfd_create()؛ اگر TFD_CLOEXEC به‌عنوان پرچم تنظیم شود، پرچم close-on-exec را برای توصیف‌گر پرونده جدید تنظیم می‌کند.

دسترس‌پذیری: Linux >= 2.6.27 with glibc >= 2.8

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

os.TFD_TIMER_ABSTIME

پرچمی برای توابع timerfd_settime() و timerfd_settime_ns(). اگر این پرچم تنظیم‌شده باشد، initial به‌عنوان یک مقدار مطلق بر اساس ساعت تایمر تفسیر می‌شود (به‌صورت ثانیه‌ها یا نانوثانیه‌های UTC از مبدأ یونیکس).

دسترس‌پذیری: Linux >= 2.6.27 with glibc >= 2.8

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

os.TFD_TIMER_CANCEL_ON_SET

پرچمی برای توابع timerfd_settime() و timerfd_settime_ns() به‌همراه TFD_TIMER_ABSTIME. این زمان‌سنج هنگامی لغو می‌شود که زمان ساعت زیربنایی به‌صورت ناپیوسته تغییر کند.

دسترس‌پذیری: Linux >= 2.6.27 with glibc >= 2.8

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

ویژگی‌های گسترش‌یافته لینوکس

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

این توابع همگی تنها در لینوکس در دسترس هستند.

os.getxattr(path, attribute, *, follow_symlinks=True)

مقدار ویژگی گسترش‌یافته‌ی سامانه فایل‌بندی attribute را برای path برمی‌گرداند. attribute می‌تواند bytes یا str باشد (به‌طور مستقیم یا غیرمستقیم از طریق رابط PathLike). اگر str باشد، با کدگذاری سامانه فایل‌بندی کدگذاری می‌شود.

این تابع می‌تواند از تعیین یک توصیف‌گر پرونده و عدم دنبال‌کردن پیوندهای نمادین پشتیبانی کند.

یک رویداد حسابرسی os.getxattr را با آرگومان‌های path و attribute پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را برای path و attribute می‌پذیرد.

os.listxattr(path=None, *, follow_symlinks=True)

فهرستی از ویژگی‌های توسعه‌یافته‌ی سامانه فایل‌بندی برای path برمی‌گرداند. ویژگی‌های موجود در فهرست به‌صورت رشته‌هایی نمایش داده می‌شوند که با کدگذاری سامانه فایل‌بندی کدگشایی شده‌اند. اگر path برابر None باشد، listxattr() پوشه جاری را بررسی خواهد کرد.

این تابع می‌تواند از تعیین یک توصیف‌گر پرونده و عدم دنبال‌کردن پیوندهای نمادین پشتیبانی کند.

یک رویداد حسابرسی os.listxattr را با آرگومان path پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

os.removexattr(path, attribute, *, follow_symlinks=True)

ویژگی توسعه‌یافته‌ی سامانه فایل‌بندی attribute را از path حذف می‌کند. attribute باید از نوع bytes یا str باشد (مستقیماً یا به‌طور غیرمستقیم از طریق رابط PathLike). اگر یک رشته باشد، با filesystem encoding and error handler کدگذاری می‌شود.

این تابع می‌تواند از تعیین یک توصیف‌گر پرونده و عدم دنبال‌کردن پیوندهای نمادین پشتیبانی کند.

یک رویداد حسابرسی os.removexattr را با آرگومان‌های path و attribute پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را برای path و attribute می‌پذیرد.

os.setxattr(path, attribute, value, flags=0, *, follow_symlinks=True)

ویژگی گسترده‌ی سامانه فایل‌بندی‌ای attribute را برای path به value تنظیم کنید. attribute باید از نوع bytes یا str بدون هیچ نویسه‌ی NUL نهفته‌ای باشد (چه مستقیم و چه غیرمستقیم از طریق رابط PathLike). اگر از نوع str باشد، با کدگذاری و هندلر خطای سامانه فایل‌بندی‌ای کدگذاری می‌شود. flags می‌تواند XATTR_REPLACE یا XATTR_CREATE باشد. اگر XATTR_REPLACE داده شده باشد و ویژگی وجود نداشته باشد، ENODATA پرتاب خواهد شد. اگر XATTR_CREATE داده شده باشد و ویژگی از قبل وجود داشته باشد، ویژگی ایجاد نخواهد شد و EEXISTS پرتاب خواهد شد.

این تابع می‌تواند از تعیین یک توصیف‌گر پرونده و عدم دنبال‌کردن پیوندهای نمادین پشتیبانی کند.

توجه

یک اشکال در نسخه‌های کمتر از 2.6.39 هسته لینوکس باعث می‌شد که آرگومان flags در برخی سامانه فایل‌بندی‌ها نادیده گرفته شود.

یک رویداد حسابرسی os.setxattr را با آرگومان‌های path، attribute، value و flags پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را برای path و attribute می‌پذیرد.

os.XATTR_SIZE_MAX

حداکثر اندازه ممکن برای مقدار یک ویژگی گسترش‌یافته. در حال حاضر، این مقدار در لینوکس ۶۴ KiB است.

os.XATTR_CREATE

این یک مقدار ممکن برای آرگومان flags در setxattr() است. این نشان می‌دهد که عملیات باید یک ویژگی ایجاد کند.

os.XATTR_REPLACE

این یک مقدار ممکن برای آرگومان flags در setxattr() است. این نشان می‌دهد که عملیات باید یک ویژگی موجود را جایگزین کند.

مدیریت فرایند

می‌توان از این توابع برای ایجاد و مدیریت فرآیندها استفاده کرد.

توابع گوناگون exec* فهرستی از آرگومان‌ها را برای برنامه جدیدی که در فرایند بارگذاری می‌شود دریافت می‌کنند. در هر مورد، نخستین آرگومان از این آرگومان‌ها به‌عنوان نام خود برنامه به برنامه جدید ارسال می‌شود، نه به‌عنوان آرگومانی که کاربر ممکن است در خط فرمان وارد کرده باشد. برای برنامه‌نویس C، این همان argv[0] است که به main() یک برنامه ارسال می‌شود. برای مثال، os.execv('/bin/echo', ['foo', 'bar']) تنها bar را در خروجی استاندارد چاپ می‌کند؛ به نظر می‌رسد که foo چشم‌پوشی شده است.

os.abort()

یک سیگنال SIGABRT به فرایند جاری ارسال می‌کند. در یونیکس، رفتار پیش‌فرض تولید یک برون‌ریزی هسته است؛ در ویندوز، فرایند بلافاصله کد خروجی 3 را برمی‌گرداند. توجه داشته باشید که فراخوانی این تابع، هندلر سیگنال پایتونی را که برای SIGABRT با signal.signal() ثبت شده است، فراخوانی نخواهد کرد.

os.add_dll_directory(path)

مسیری به مسیر جستجوی DLL اضافه کنید.

این مسیر جست‌وجو هنگام حل وابستگی‌های ماژول‌های توسعه‌ای ایمپورت‌شده (خود ماژول از طریق sys.path یافت می‌شود)، و همچنین توسط ctypes استفاده می‌شود.

پوشه را با فراخوانی close() روی شیء برگردانده‌شده یا استفاده از آن در یک دستور with حذف کنید.

برای اطلاعات بیشتر درباره‌ی چگونگی بارگذاری DLLها، مستندات مایکروسافت را ببینید.

یک رویداد حسابرسی os.add_dll_directory را با آرگومان path پرتاب می‌کند.

دسترس‌پذیری: Windows.

اضافه شده در نسخه‌ی 3.8: نسخه‌های پیشین CPython، DLLها را با استفاده از رفتار پیش‌فرض فرایند جاری پیدا می‌کردند. این موضوع به ناسازگاری‌هایی منجر می‌شد؛ از جمله اینکه تنها گاهی PATH یا پوشه‌ی کاری جاری جستجو می‌شد و توابع سیستم‌عامل مانند AddDllDirectory تأثیری نداشتند.

در 3.8، دو روش اصلی بارگذاری DLLها اکنون به‌صراحت رفتار در سطح فرایند را نادیده می‌گیرند تا سازگاری تضمین شود. برای کسب اطلاعات در مورد به‌روزرسانی کتابخانه‌ها، یادداشت‌های انتقال را ببینید.

os.execl(path, arg0, arg1, ...)
os.execle(path, arg0, arg1, ..., env)
os.execlp(file, arg0, arg1, ...)
os.execlpe(file, arg0, arg1, ..., env)
os.execv(path, args)
os.execve(path, args, env)
os.execvp(file, args)
os.execvpe(file, args, env)

این توابع همگی یک برنامه جدید را اجرا می‌کنند و جایگزین فرایند جاری می‌شوند؛ آن‌ها بازگشت نمی‌کنند. در یونیکس، پرونده اجرایی جدید در فرایند جاری بارگذاری می‌شود و همان شناسه فرایند فراخواننده را خواهد داشت. خطاها به‌صورت استثناهای OSError گزارش می‌شوند.

فرایند جاری بلافاصله جایگزین می‌شود. اشیای پرونده باز و توصیف‌گرها تخلیه نمی‌شوند، بنابراین اگر ممکن است داده‌ای در بافر این پرونده‌های باز وجود داشته باشد، باید پیش از فراخوانی تابع exec*، آن‌ها را با استفاده از flush() یا os.fsync() تخلیه کنید.

گونه‌های «l» و «v» از توابع exec* در چگونگی ارسال آرگومان‌های خط فرمان تفاوت دارند. گونه‌های «l» شاید آسان‌ترین گزینه برای کار کردن باشند اگر تعداد پارامترها هنگام نوشتن کد ثابت باشد؛ پارامترهای جداگانه صرفاً به پارامترهای اضافی برای توابع execl*() تبدیل می‌شوند. گونه‌های «v» زمانی مناسب هستند که تعداد پارامترها متغیر باشد و آرگومان‌ها در قالب یک فهرست یا تاپل به‌عنوان پارامتر args ارسال شوند. در هر دو حالت، آرگومان‌های ارسالی به فرایند فرزند باید با نام فرمانی که اجرا می‌شود شروع شوند، اما این امر الزامی نیست.

گونه‌هایی که شامل یک «p» نزدیک به انتها هستند (execlp()، execlpe()، execvp() و execvpe())، از متغیر محیطی PATH برای یافتن file برنامه استفاده می‌کنند. هنگامی که محیط جایگزین می‌شود (با استفاده از یکی از گونه‌های exec*e، که در پاراگراف بعدی توضیح داده شده است)، از محیط جدید به‌عنوان منبع متغیر PATH استفاده می‌شود. سایر گونه‌ها، execl()، execle()، execv() و execve()، از متغیر PATH برای یافتن پرونده اجرایی استفاده نخواهند کرد؛ path باید شامل یک مسیر مطلق یا نسبی مناسب باشد. مسیرهای نسبی باید دست‌کم یک اسلش داشته باشند، حتی در ویندوز، زیرا نام‌های ساده حل نخواهند شد.

برای execle()، execlpe()، execve() و execvpe() (توجه داشته باشید که همه این‌ها به «e» ختم می‌شوند)، پارامتر env باید یک نگاشت باشد که برای تعریف متغیرهای محیطی فرایند جدید استفاده می‌شود (این متغیرها به جای محیط فرایند جاری استفاده می‌شوند)؛ توابع execl()، execlp()، execv() و execvp() همگی باعث می‌شوند فرایند جدید محیط فرایند جاری را به ارث ببرد.

برای execve() در برخی سکوها، همچنین می‌توان path را به‌عنوان یک توصیف‌گر پرونده باز مشخص کرد. ممکن است این قابلیت در سکو شما پشتیبانی نشود؛ می‌توانید با استفاده از os.supports_fd بررسی کنید که آیا این قابلیت در دسترس است یا خیر. اگر در دسترس نباشد، استفاده از آن باعث پرتاب استثنای NotImplementedError می‌شود.

یک رویداد حسابرسی os.exec را با آرگومان‌های path، args و env پرتاب می‌کند.

دسترس‌پذیری: Unix, Windows, not WASI, not Android, not iOS.

تغییر یافته در نسخه‌ی 3.3: پشتیبانی از مشخص کردن path به‌عنوان یک توصیف‌گر پرونده باز برای execve() افزوده شد.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

os._exit(n)

فرایند را با وضعیت n خارج می‌کند، بدون فراخوانی هندلرهای پاک‌سازی، تخلیه بافرهای stdio و غیره.

توجه

راه استاندارد برای خروج sys.exit(n) است. معمولاً _exit() باید فقط در فرایند فرزند پس از fork() استفاده شود.

کدهای خروجی زیر تعریف شده‌اند و می‌توان آن‌ها را با _exit() به کار برد، اگرچه استفاده از آن‌ها الزامی نیست. این کدها معمولاً برای برنامه‌های سیستمی نوشته‌شده با پایتون استفاده می‌شوند، مانند برنامه‌ی تحویل فرمان خارجی یک سرور پست.

توجه

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

os.EX_OK

کد خروجی که نشان می‌دهد هیچ خطایی رخ نداده است. ممکن است از مقدار تعریف‌شده EXIT_SUCCESS در برخی پلتفرم‌ها گرفته شود. معمولاً دارای مقدار صفر است.

دسترس‌پذیری: Unix, Windows.

os.EX_USAGE

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

دسترس‌پذیری: Unix, not WASI.

os.EX_DATAERR

کد خروجی‌ای که به معنای نادرست بودن داده‌های ورودی است.

دسترس‌پذیری: Unix, not WASI.

os.EX_NOINPUT

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

دسترس‌پذیری: Unix, not WASI.

os.EX_NOUSER

کد خروجی که به معنای وجود نداشتن کاربر مشخص‌شده است.

دسترس‌پذیری: Unix, not WASI.

os.EX_NOHOST

کد خروجی که به معنای وجود نداشتن میزبان مشخص‌شده است.

دسترس‌پذیری: Unix, not WASI.

os.EX_UNAVAILABLE

کد خروجی که نشان می‌دهد یک سرویس مورد نیاز در دسترس نیست.

دسترس‌پذیری: Unix, not WASI.

os.EX_SOFTWARE

کد خروجی که نشان می‌دهد یک خطای نرم‌افزاری داخلی شناسایی شده است.

دسترس‌پذیری: Unix, not WASI.

os.EX_OSERR

کد خروجی‌ای که به معنای شناسایی یک خطای سیستم‌عامل است، مانند ناتوانی در fork یا ایجاد pipe.

دسترس‌پذیری: Unix, not WASI.

os.EX_OSFILE

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

دسترس‌پذیری: Unix, not WASI.

os.EX_CANTCREAT

کد خروجی که به معنای ایجاد نشدن پرونده خروجی مشخص‌شده توسط کاربر است.

دسترس‌پذیری: Unix, not WASI.

os.EX_IOERR

کد خروجی که نشان می‌دهد خطایی هنگام انجام ورودی/خروجی روی پرونده‌ای رخ داده است.

دسترس‌پذیری: Unix, not WASI.

os.EX_TEMPFAIL

کد خروجی‌ای که به معنای وقوع یک شکست موقت است. این نشان‌دهنده‌ی موردی است که ممکن است واقعاً یک خطا نباشد، مانند اتصال شبکه‌ای که در حین یک عملیات قابل تلاش مجدد برقرار نشده است.

دسترس‌پذیری: Unix, not WASI.

os.EX_PROTOCOL

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

دسترس‌پذیری: Unix, not WASI.

os.EX_NOPERM

کد خروجی که به معنای ناکافی بودن دسترسی‌ها برای انجام عملیات است (اما برای مشکلات سامانه فایل‌بندی در نظر گرفته نشده است).

دسترس‌پذیری: Unix, not WASI.

os.EX_CONFIG

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

دسترس‌پذیری: Unix, not WASI.

os.EX_NOTFOUND

کد خروجی که معنایی شبیه به «ورودی‌ای یافت نشد» دارد.

دسترس‌پذیری: Unix, not WASI.

os.fork()

یک فرایند فرزند را fork می‌کند . در فرایند فرزند 0 و در فرایند والد شناسه فرایند فرزند را برمی‌گرداند. اگر خطایی رخ دهد، OSError پرتاب می‌شود.

توجه داشته باشید که برخی سکوها، از جمله FreeBSD <= 6.3 و Cygwin، هنگام استفاده از fork() از یک نخ، مشکلات شناخته‌شده‌ای دارند.

یک رویداد حسابرسی os.fork را بدون آرگومان پرتاب می‌کند.

هشدار

اگر از سوکت‌های TLS در برنامه‌ای که fork() را فراخوانی می‌کند استفاده می‌کنید، هشدار موجود در مستندات ssl را ببینید.

هشدار

در macOS، استفاده از این تابع هنگامی که با استفاده از APIهای سیستمی سطح بالاتر ترکیب شود، ناامن است، و این شامل استفاده از urllib.request نیز می‌شود.

تغییر یافته در نسخه‌ی 3.8: فراخوانی fork() در یک زیرمفسر دیگر پشتیبانی نمی‌شود (استثنای RuntimeError پرتاب می‌شود).

تغییر یافته در نسخه‌ی 3.12: اگر پایتون بتواند تشخیص دهد که فرایند شما چندین نخ دارد، os.fork() اکنون یک DeprecationWarning پرتاب می‌کند.

ما تصمیم گرفتیم این موضوع را، در صورت قابل‌تشخیص بودن، به‌صورت یک هشدار نشان دهیم تا بهتر توسعه‌دهندگان را از یک مشکل طراحی آگاه کنیم؛ مشکلی که سکوی POSIX به‌طور خاص آن را به‌عنوان پشتیبانی‌نشده ذکر کرده است. حتی در کدی که به نظر می‌رسد کار می‌کند، ترکیب استفاده از نخ‌ها با os.fork() در سکوهای POSIX هرگز ایمن نبوده است. خود ران‌تایم CPython همیشه فراخوانی‌های API انجام داده است که در صورت وجود نخ‌ها در فرایند والد، برای استفاده در فرایند فرزند ایمن نیستند (مانند malloc و free).

کاربران macOS یا کاربران پیاده‌سازی‌های دیگری از libc یا malloc غیر از آن‌هایی که تاکنون معمولاً در glibc یافت شده‌اند، از جمله کسانی هستند که از قبل بیشتر احتمال می‌رود هنگام اجرای چنین کدی با بن‌بست مواجه شوند.

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

دسترس‌پذیری: POSIX, not WASI, not Android, not iOS.

os.forkpty()

یک فرایند فرزند را با استفاده از یک شبه‌پایانه (pseudo-terminal) جدید به‌عنوان پایانه کنترل‌کننده فرزند fork می‌کند. یک جفت (pid, fd) را برمی‌گرداند، که در آن pid در فرزند 0 و در والد شناسه فرایند فرزند جدید است، و fd توصیف‌گر پرونده سمت اصلی شبه‌پایانه است. برای رویکرد قابل‌حمل‌تر، از ماژول pty استفاده کنید. در صورت بروز خطا، OSError پرتاب می‌شود.

رویداد حسابرسی os.forkpty را بدون آرگومان پرتاب می‌کند.

هشدار

در macOS، استفاده از این تابع هنگامی که با استفاده از APIهای سیستمی سطح بالاتر ترکیب شود، ناامن است، و این شامل استفاده از urllib.request نیز می‌شود.

تغییر یافته در نسخه‌ی 3.8: فراخوانی forkpty() در یک زیرمفسر دیگر پشتیبانی نمی‌شود (RuntimeError پرتاب می‌شود).

تغییر یافته در نسخه‌ی 3.12: اگر پایتون بتواند تشخیص دهد که فرایند شما دارای چندین نخ است، این مورد اکنون یک DeprecationWarning پرتاب می‌کند. توضیح طولانی‌تر درباره‌ی os.fork() را ببینید.

دسترس‌پذیری: Unix, not WASI, not Android, not iOS.

os.kill(pid, sig, /)

سیگنال sig را به فرایند pid ارسال می‌کند. ثابت‌های مربوط به سیگنال‌های خاصی که روی پلتفرم میزبان در دسترس هستند، در ماژول signal تعریف شده‌اند.

ویندوز: سیگنال‌های signal.CTRL_C_EVENT و signal.CTRL_BREAK_EVENT سیگنال‌های خاصی هستند که فقط می‌توان آن‌ها را به فرایندهای کنسولی که یک پنجره کنسول مشترک دارند ارسال کرد، برای مثال، برخی از زیرفرایندها. هر مقدار دیگری برای sig باعث می‌شود فرایند به‌طور غیرمشروط توسط TerminateProcess API خاتمه داده شود و کد خروجی روی sig تنظیم شود.

همچنین ببینید signal.pthread_kill().

یک رویداد حسابرسی os.kill را با آرگومان‌های pid و sig پرتاب می‌کند.

دسترس‌پذیری: Unix, Windows, not WASI, not iOS.

تغییر یافته در نسخه‌ی 3.2: پشتیبانی از ویندوز اضافه شد.

os.killpg(pgid, sig, /)

سیگنال sig را به گروه فرایند pgid ارسال می‌کند.

یک رویداد حسابرسی os.killpg را با آرگومان‌های pgid و sig پرتاب می‌کند.

دسترس‌پذیری: Unix, not WASI, not iOS.

os.nice(increment, /)

increment را به «مقدار nice (niceness)» فرایند می‌افزاید. مقدار جدید nice (niceness) را برمی‌گرداند.

دسترس‌پذیری: Unix, not WASI.

os.pidfd_open(pid, flags=0)

یک توصیف‌گر پرونده که به فرایند pid اشاره می‌کند، با flags تنظیم‌شده برمی‌گرداند. از این توصیف‌گر می‌توان برای مدیریت فرایند بدون رقابت و سیگنال استفاده کرد.

برای جزئیات بیشتر، صفحه‌ی man مربوط به pidfd_open(2) را ببینید.

دسترس‌پذیری: Linux >= 5.3, Android >= build-time API level 31

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

os.PIDFD_NONBLOCK

این پرچم نشان می‌دهد که توصیف‌گر پرونده غیرمسدود خواهد بود. اگر فرایندی که توصیف‌گر پرونده به آن ارجاع دارد هنوز خاتمه نیافته باشد، تلاش برای انتظار روی توصیف‌گر پرونده با استفاده از waitid(2) به‌جای مسدود شدن، بلافاصله خطای EAGAIN را برمی‌گرداند.

دسترس‌پذیری: Linux >= 5.10

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

os.plock(op, /)

قطعه‌های برنامه را در حافظه قفل می‌کند. مقدار op (تعریف‌شده در <sys/lock.h>) تعیین می‌کند کدام قطعه‌ها قفل می‌شوند.

دسترس‌پذیری: Unix, not WASI, not macOS, not iOS.

os.popen(cmd, mode='r', buffering=-1)

یک پایپبه فرمان cmd یا از آن باز کنید. مقدار بازگشتی، یک شیء پرونده باز متصل به پایپ است که بسته به اینکه mode برابر 'r' (پیش‌فرض) یا 'w' باشد، قابل خواندن یا نوشتن است. آرگومان buffering همان معنای آرگومان متناظر در تابع توکار open() را دارد. شیء پرونده بازگشتی به‌جای بایت‌ها، رشته‌های متنی را می‌خواند یا می‌نویسد.

متد close در صورتی که زیرفرایند با موفقیت خارج شده باشد، None را بازمی‌گرداند، یا در صورت بروز خطا، کد بازگشتی زیرفرایند را بازمی‌گرداند. در سیستم‌های POSIX، اگر کد بازگشتی مثبت باشد، نشان‌دهنده‌ی مقدار بازگشتی فرایند است که به‌اندازه‌ی یک بایت به چپ شیفت داده شده است. اگر کد بازگشتی منفی باشد، فرایند با سیگنالی خاتمه یافته است که از قرینه‌ی مقدار کد بازگشتی به‌دست می‌آید. (برای مثال، اگر زیرفرایند کشته شده باشد، ممکن است مقدار بازگشتی - signal.SIGKILL باشد.) در سیستم‌های ویندوزی، مقدار بازگشتی حاوی کد بازگشتیِ عدد صحیح علامت‌دار از فرایند فرزند است.

در یونیکس، اگر نتیجه‌ی متد close (وضعیت خروج) None نباشد، می‌توان از waitstatus_to_exitcode() برای تبدیل آن به کد خروج استفاده کرد. در ویندوز، نتیجه‌ی متد close مستقیماً کد خروج (یا None) است.

این با استفاده از subprocess.Popen پیاده‌سازی شده است؛ برای روش‌های قدرتمندتر جهت مدیریت و ارتباط با زیرفرایندها، به مستندات آن کلاس مراجعه کنید.

دسترس‌پذیری: not WASI, not Android, not iOS.

توجه

حالت UTF-8 پایتون بر کدگذاری‌های مورد استفاده برای cmd و محتوای پایپ تأثیر می‌گذارد.

popen() یک دربرگیرنده ساده حول subprocess.Popen است. برای کنترل گزینه‌هایی مانند کدگذاری‌ها از subprocess.Popen یا subprocess.run() استفاده کنید.

منسوخ‌سازی نرم <Soft deprecated> از نسخه‌ی 3.14: در عوض، ماژول subprocess توصیه می‌شود.

os.posix_spawn(path, argv, env, *, file_actions=None, setpgroup=None, resetids=False, setsid=False, setsigmask=(), setsigdef=(), scheduler=None)

پوششی برای API کتابخانه‌ی C مربوط به posix_spawn() جهت استفاده از پایتون فراهم می‌کند.

بیشتر کاربران باید به‌جای posix_spawn() از subprocess.run() استفاده کنند.

آرگومان‌های فقط جایگاهی path، args و env مشابه execve() هستند. env می‌تواند None باشد، که در این صورت از محیط فرایند جاری استفاده می‌شود.

پارامتر path مسیر پرونده اجرایی است. path باید شامل یک پوشه باشد. برای ارسال پرونده اجرایی بدون پوشه از posix_spawnp() استفاده کنید.

آرگومان file_actions می‌تواند دنباله‌ای از تاپل‌هایی باشد که اقدامات لازم برای اعمال بر توصیف‌گرهای پرونده مشخصی را در فرآیند فرزند، بین مراحل fork() و exec() در پیاده‌سازی کتابخانه‌ی C توصیف می‌کنند. اولین آیتم در هر تاپل باید یکی از سه نشانگر نوع فهرست‌شده در زیر باشد که عناصر باقی‌مانده‌ی تاپل را توصیف می‌کند:

os.POSIX_SPAWN_OPEN

(os.POSIX_SPAWN_OPEN, fd, path, flags, mode)

os.dup2(os.open(path, flags, mode), fd) را اجرا می‌کند.

os.POSIX_SPAWN_CLOSE

(os.POSIX_SPAWN_CLOSE, fd)

os.close(fd) را اجرا می‌کند.

os.POSIX_SPAWN_DUP2

(os.POSIX_SPAWN_DUP2, fd, new_fd)

os.dup2(fd, new_fd) را اجرا می‌کند.

os.POSIX_SPAWN_CLOSEFROM

(os.POSIX_SPAWN_CLOSEFROM, fd)

os.closerange(fd, INF) را اجرا می‌کند.

این تاپل‌ها متناظر با فراخوانی‌های API کتابخانه‌ی C هستند: posix_spawn_file_actions_addopen()، posix_spawn_file_actions_addclose()، posix_spawn_file_actions_adddup2() و posix_spawn_file_actions_addclosefrom_np() که برای آماده‌سازی خود فراخوانی posix_spawn() به کار می‌روند.

آرگومان setpgroup گروه فرایند فرزند را روی مقدار تعیین‌شده تنظیم می‌کند. اگر مقدار تعیین‌شده ۰ باشد، شناسه‌ی گروه فرایند فرزند با شناسه‌ی فرایند آن یکسان می‌شود. اگر مقدار setpgroup تنظیم‌نشده باشد، فرزند شناسه‌ی گروه فرایند والد را به ارث می‌برد. این آرگومان معادل پرچم POSIX_SPAWN_SETPGROUP در کتابخانه‌ی C است.

اگر آرگومان resetids برابر True باشد، UID و GID مؤثر فرآیند فرزند به UID و GID واقعی فرآیند والد بازنشانی می‌شود. اگر آرگومان False باشد، فرآیند فرزند UID و GID مؤثر فرآیند والد را حفظ می‌کند. در هر صورت، اگر بیت‌های دسترسی set-user-ID و set-group-ID روی پرونده اجرایی فعال باشند، اثر آن‌ها بر تنظیم UID و GID مؤثر غلبه می‌کند. این آرگومان معادل پرچم POSIX_SPAWN_RESETIDS در کتابخانه‌ی C است.

اگر آرگومان setsid برابر True باشد، یک شناسه‌ی نشست جدید برای posix_spawn ایجاد می‌شود. setsid به پرچم POSIX_SPAWN_SETSID یا POSIX_SPAWN_SETSID_NP نیاز دارد. در غیر این صورت، NotImplementedError پرتاب می‌شود.

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

آرگومان sigdef رفتار همه سیگنال‌های موجود در مجموعه‌ی مشخص‌شده را بازنشانی می‌کند. این آرگومان متناظر با پرچم POSIX_SPAWN_SETSIGDEF در کتابخانه C است.

آرگومان scheduler باید یک تاپل حاوی سیاست زمان‌بند (اختیاری) و یک نمونه از sched_param با پارامترهای زمان‌بند باشد. مقدار None به‌جای سیاست زمان‌بند نشان می‌دهد که سیاست زمان‌بند ارائه نشده است. این آرگومان ترکیبی از پرچم‌های POSIX_SPAWN_SETSCHEDPARAM و POSIX_SPAWN_SETSCHEDULER در کتابخانه C است.

یک رویداد حسابرسی os.posix_spawn را با آرگومان‌های path، argv و env پرتاب می‌کند.

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

تغییر یافته در نسخه‌ی 3.13: پارامتر env، None را می‌پذیرد. os.POSIX_SPAWN_CLOSEFROM در پلتفرم‌هایی که posix_spawn_file_actions_addclosefrom_np() وجود دارد، در دسترس است.

دسترس‌پذیری: Unix, not WASI, not Android, not iOS.

os.posix_spawnp(path, argv, env, *, file_actions=None, setpgroup=None, resetids=False, setsid=False, setsigmask=(), setsigdef=(), scheduler=None)

API کتابخانه‌ی C مربوط به posix_spawnp() را برای استفاده از پایتون پوشش می‌دهد.

مشابه posix_spawn() است، با این تفاوت که سامانه فایل‌بندی اجرایی را در فهرست پوشه‌های مشخص‌شده توسط متغیر محیطی PATH جستجو می‌کند (همان‌گونه که برای execvp(3) انجام می‌شود).

یک رویداد حسابرسی os.posix_spawn را با آرگومان‌های path، argv و env پرتاب می‌کند.

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

دسترس‌پذیری: POSIX, not WASI, not Android, not iOS.

مستندات posix_spawn() را ببینید.

os.register_at_fork(*, before=None, after_in_parent=None, after_in_child=None)

فراخوانی‌پذیرهایی را ثبت کنید تا هنگام انشعاب یک فرایند فرزند جدید با استفاده از os.fork() یا APIهای مشابهِ تکثیر فرایند اجرا شوند. پارامترها اختیاری و فقط کلیدواژه‌ای هستند. هرکدام یک نقطه‌ی فراخوانی متفاوت را مشخص می‌کند.

  • before تابعی است که پیش از fork کردن یک فرایند فرزند فراخوانی می‌شود.

  • after_in_parent تابعی است که پس از فورک (forking) یک فرایند فرزند، از فرایند والد فراخوانی می‌شود.

  • after_in_child تابعی است که از فرایند فرزند فراخوانی می‌شود.

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

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

توجه داشته باشید که کد C شخص ثالثی که fork() را فراخوانی می‌کند، ممکن است آن توابع را فراخوانی نکند، مگر اینکه به‌صراحت PyOS_BeforeFork()، PyOS_AfterFork_Parent() و PyOS_AfterFork_Child() را فراخوانی کند.

هیچ راهی برای لغو ثبت یک تابع وجود ندارد.

دسترس‌پذیری: Unix, not WASI, not Android, not iOS.

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

os.spawnl(mode, path, ...)
os.spawnle(mode, path, ..., env)
os.spawnlp(mode, file, ...)
os.spawnlpe(mode, file, ..., env)
os.spawnv(mode, path, args)
os.spawnve(mode, path, args, env)
os.spawnvp(mode, file, args)
os.spawnvpe(mode, file, args, env)

برنامه‌ی path را در یک فرایند جدید اجرا کنید.

(توجه داشته باشید که ماژول subprocess امکانات قدرتمندتری برای ایجاد فرایندهای جدید و دریافت نتایج آن‌ها فراهم می‌کند؛ استفاده از آن ماژول به استفاده از این توابع ترجیح دارد. به‌ویژه بخش جایگزینی توابع قدیمی با ماژول subprocess را بررسی کنید.)

اگر mode برابر P_NOWAIT باشد، این تابع شناسه‌ی فرایند جدید را برمی‌گرداند؛ اگر mode برابر P_WAIT باشد، در صورت خروج عادی فرایند، کد خروج آن را برمی‌گرداند، یا -signal را برمی‌گرداند، که در آن signal سیگنالی است که فرایند را خاتمه داده است. در ویندوز، شناسه‌ی فرایند در واقع دسته فرایند (process handle) است، بنابراین می‌توان از آن با تابع waitpid() استفاده کرد.

توجه داشته باشید که در VxWorks، این تابع هنگامی که فرایند جدید خاتمه داده شود، -signal را برنمی‌گرداند. در عوض، استثنای OSError را پرتاب می‌کند.

انواع «l» و «v» توابع spawn* در چگونگی ارسال آرگومان‌های خط فرمان تفاوت دارند. اگر تعداد پارامترها هنگام نوشتن کد ثابت باشد، شاید کار با انواع «l» آسان‌ترین باشد؛ پارامترهای جداگانه صرفاً به پارامترهای اضافی برای توابع spawnl*() تبدیل می‌شوند. انواع «v» زمانی مناسب هستند که تعداد پارامترها متغیر باشد و آرگومان‌ها در قالب یک فهرست یا تاپلبه‌عنوان پارامتر args ارسال می‌شوند. در هر دو حالت، آرگومان‌های فرایند فرزند باید با نام فرمانی که اجرا می‌شود شروع شوند.

گونه‌هایی که یک «p» دوم نزدیک به انتها دارند (spawnlp()، spawnlpe()، spawnvp() و spawnvpe())، از متغیر محیطی PATH برای یافتن پرونده برنامه‌ی file استفاده می‌کنند. هنگامی که محیط جایگزین می‌شود (با استفاده از یکی از گونه‌های spawn*e، که در پاراگراف بعدی توضیح داده شده است)، محیط جدید به‌عنوان منبع متغیر PATH استفاده می‌شود. سایر گونه‌ها، spawnl()، spawnle()، spawnv() و spawnve()، از متغیر PATH برای یافتن پرونده اجرایی استفاده نمی‌کنند؛ path باید حاوی مسیر مطلق یا نسبی مناسب باشد.

برای spawnle()، spawnlpe()، spawnve() و spawnvpe() (توجه داشته باشید که همه‌ی این‌ها به "e" ختم می‌شوند)، پارامتر env باید یک نگاشت باشد که برای تعریف متغیرهای محیطی فرایند جدید استفاده می‌شود (آن‌ها به‌جای محیط فرایند جاری استفاده می‌شوند)؛ توابع spawnl()، spawnlp()، spawnv() و spawnvp() همگی باعث می‌شوند فرایند جدید محیط فرایند جاری را به ارث ببرد. توجه داشته باشید که کلیدها و مقدارها در دیکشنری env باید رشته باشند؛ کلیدها یا مقدارهای نامعتبر موجب شکست تابع با مقدار بازگشتی 127 می‌شوند.

به‌عنوان مثال، فراخوانی‌های زیر به spawnlp() و spawnvpe() معادل هستند:

import os
os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null')

L = ['cp', 'index.html', '/dev/null']
os.spawnvpe(os.P_WAIT, 'cp', L, os.environ)

یک رویداد حسابرسی os.spawn را با آرگومان‌های mode، path، args و env پرتاب می‌کند.

دسترس‌پذیری: Unix, Windows, not WASI, not Android, not iOS.

spawnlp()، spawnlpe()، spawnvp() و spawnvpe() در ویندوز در دسترس نیستند. spawnle() و spawnve() در ویندوز نخ‌ایمن نیستند؛ توصیه می‌کنیم در عوض از ماژول subprocess استفاده کنید.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

منسوخ‌سازی نرم <Soft deprecated> از نسخه‌ی 3.14: در عوض، ماژول subprocess توصیه می‌شود.

os.P_NOWAIT
os.P_NOWAITO

مقادیر ممکن برای پارامتر mode در خانواده‌ی توابع spawn*. اگر هر یک از این مقادیر داده شود، توابع spawn* به محض ایجاد فرایند جدید، با شناسه‌ی فرایند به‌عنوان مقدار بازگشتی بازمی‌گردند.

دسترس‌پذیری: Unix, Windows.

os.P_WAIT

مقدار ممکن برای پارامتر mode در خانواده‌ی توابع spawn*. اگر این مقدار به‌عنوان mode داده شود، توابع spawn* تا زمانی که فرایند جدید به‌طور کامل اجرا نشده باشد، بازنمی‌گردند و در صورت موفقیت‌آمیز بودن اجرا، کد خروجی فرایند را برمی‌گردانند، یا اگر سیگنالی فرایند را از بین ببرد، -signal را برمی‌گردانند.

دسترس‌پذیری: Unix, Windows.

os.P_DETACH
os.P_OVERLAY

مقادیر ممکن برای پارامتر mode در خانواده‌ی توابع spawn*. این مقادیر نسبت به موارد فهرست‌شده در بالا، قابلیت حمل کمتری دارند. P_DETACH مشابه P_NOWAIT است، اما فرایند جدید از کنسول فرایند فراخواننده جدا می‌شود. اگر از P_OVERLAY استفاده شود، فرایند جاری جایگزین خواهد شد؛ تابع spawn* بازگشت نخواهد کرد.

دسترس‌پذیری: Windows.

os.startfile(path[, operation][, arguments][, cwd][, show_cmd])

یک پرونده را با برنامه‌ی مرتبط آن اجرا کنید.

هنگامی که operation مشخص نشده باشد، این کار مانند دوبار کلیک کردن روی پرونده در Windows Explorer یا دادن نام پرونده به‌عنوان آرگومان به فرمان start از پوسته فرمان تعاملی است: پرونده با هر کاربردی (در صورت وجود) که پسوند آن به آن مرتبط شده باشد، باز می‌شود.

هنگامی که operation دیگری داده شود، باید یک «فعل فرمانی» (command verb) باشد که مشخص می‌کند با پرونده چه کاری باید انجام شود. فعل‌های رایجی که توسط مایکروسافت مستند شده‌اند عبارتند از 'open'، 'print' و 'edit' (برای استفاده روی پرونده‌ها) و همچنین 'explore' و 'find' (برای استفاده روی پوشه‌ها).

هنگام راه‌اندازی یک برنامه، arguments را به‌صورت یک رشته واحد مشخص کنید تا ارسال شوند. این آرگومان ممکن است هنگام استفاده از این تابع برای باز کردن یک سند تأثیری نداشته باشد.

پوشه کاری پیش‌فرض به ارث برده می‌شود، اما ممکن است با آرگومان cwd بازنویسی شود. این باید یک مسیر مطلق باشد. یک path نسبی بر اساس این آرگومان حل می‌شود.

برای تغییر سبک پیش‌فرض پنجره از show_cmd استفاده کنید. اینکه این مورد تأثیری دارد یا خیر، به برنامه‌ای که اجرا می‌شود بستگی دارد. مقادیر، اعداد صحیحی هستند که توسط تابع ShellExecute() در Win32 پشتیبانی می‌شوند.

startfile() به‌محض راه‌اندازی برنامه مرتبط بازمی‌گردد. گزینه‌ای برای منتظر ماندن تا بسته شدن برنامه وجود ندارد و راهی نیز برای دریافت وضعیت خروج برنامه وجود ندارد. پارامتر path نسبت به پوشه جاری یا cwd نسبی است. اگر می‌خواهید از یک مسیر مطلق استفاده کنید، اطمینان حاصل کنید که نویسه اول اسلش ('/') نباشد. از pathlib یا تابع os.path.normpath() استفاده کنید تا اطمینان حاصل شود که مسیرها به‌درستی برای Win32 کدگذاری شده‌اند.

برای کاهش سربار راه‌اندازی مفسر، تابع Win32 ShellExecute() تا زمانی که این تابع برای نخستین بار فراخوانی نشود، شناسایی نمی‌شود. اگر تابع شناسایی نشود، NotImplementedError پرتاب خواهد شد.

یک رویداد حسابرسی os.startfile را با آرگومان‌های path و operation پرتاب می‌کند.

یک رویداد حسابرسی os.startfile/2 را با آرگومان‌های path، operation، arguments، cwd، show_cmd پرتاب می‌کند.

دسترس‌پذیری: Windows.

تغییر یافته در نسخه‌ی 3.10: آرگومان‌های arguments، cwd و show_cmd، و رویداد حسابرسی os.startfile/2 افزوده شدند.

os.system(command)

فرمان (یک رشته) را در یک زیرپوسته اجرا می‌کند. این کار با فراخوانی تابع استاندارد C یعنی system() پیاده‌سازی شده است و همان محدودیت‌ها را دارد. تغییرات در sys.stdin و غیره در محیط فرمان اجراشده بازتاب نمی‌یابد. اگر command خروجی‌ای تولید کند، به جریان خروجی استاندارد مفسر فرستاده خواهد شد. استاندارد C معنای مقدار بازگشتی تابع C را تعیین نمی‌کند، بنابراین مقدار بازگشتی تابع Python وابسته به سیستم است.

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

در ویندوز، مقدار برگشتی همان مقداری است که پوسته‌ی سیستم پس از اجرای command برمی‌گرداند. پوسته از طریق متغیر محیطی ویندوز COMSPEC تعیین می‌شود: این پوسته معمولاً cmd.exe است که وضعیت خروجی دستور اجراشده را برمی‌گرداند؛ در سیستم‌هایی که از پوسته‌ی غیربومی استفاده می‌کنند، به مستندات پوسته‌ی خود مراجعه کنید.

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

در یونیکس، می‌توان از waitstatus_to_exitcode() برای تبدیل نتیجه (وضعیت خروج) به کد خروج استفاده کرد. در ویندوز، نتیجه مستقیماً کد خروج است.

یک رویداد حسابرسی os.system را با آرگومان command پرتاب می‌کند.

دسترس‌پذیری: Unix, Windows, not WASI, not Android, not iOS.

os.times()

زمان‌های فرایند سراسری جاری را برمی‌گرداند. مقدار بازگشتی یک شیء با ۵ ویژگی است:

  • user - زمان کاربر

  • system - زمان سیستم

  • children_user - زمان کاربری تمام فرایندهای فرزند

  • children_system - زمان سیستم برای همه فرایندهای فرزند

  • elapsed - زمان واقعی سپری‌شده از یک نقطه ثابت در گذشته

برای سازگاری با نسخه‌های پیشین، این شیء همچنین مانند یک پنج‌تایی (five-tuple) شامل user، system، children_user، children_system و elapsed به همین ترتیب رفتار می‌کند.

صفحه‌ی راهنمای یونیکس times(2) و صفحه‌ی راهنمای times(3) در یونیکس یا مستندات MSDN برای GetProcessTimes در ویندوز را ببینید. در ویندوز، تنها user و system شناخته‌شده هستند؛ سایر ویژگی‌ها صفر هستند.

دسترس‌پذیری: Unix, Windows.

تغییر یافته در نسخه‌ی 3.3: نوع برگشتی از یک تاپل به یک شیء تاپل‌مانند با ویژگی‌های نام‌دار تغییر کرد.

os.wait()

منتظر تکمیل یک فرآیند فرزند می‌ماند و یک تاپل شامل pid آن و نشانگر وضعیت خروج آن برمی‌گرداند: یک عدد ۱۶ بیتی که بایت پایینی آن شماره سیگنالی است که فرآیند را خاتمه داده است، و بایت بالایی آن وضعیت خروج است (اگر شماره سیگنال صفر باشد)؛ اگر یک پرونده core ایجاد شده باشد، بیت بالایی بایت پایینی تنظیم می‌شود.

اگر هیچ فرآیند فرزندی وجود نداشته باشد که بتوان منتظر آن ماند، ChildProcessError پرتاب می‌شود.

می‌توان از waitstatus_to_exitcode() برای تبدیل وضعیت خروج به کد خروج استفاده کرد.

دسترس‌پذیری: Unix, not WASI, not Android, not iOS.

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

سایر توابع wait*() که در زیر مستند شده‌اند، برای منتظر ماندن برای تکمیل یک فرایند فرزند مشخص قابل استفاده هستند و گزینه‌های بیشتری دارند. waitpid() تنها تابعی است که در ویندوز نیز در دسترس است.

os.waitid(idtype, id, options, /)

منتظر اتمام یک فرایند فرزند بمانید.

idtype می‌تواند P_PID، P_PGID، P_ALL، یا (در لینوکس) P_PIDFD باشد. تفسیر id به آن بستگی دارد؛ توضیحات جداگانه‌ی آن‌ها را ببینید.

options ترکیبی از پرچم‌ها با OR است. حداقل یکی از WEXITED، WSTOPPED یا WCONTINUED مورد نیاز است؛ WNOHANG و WNOWAIT پرچم‌های اختیاری اضافی هستند.

مقدار بازگشتی، شیءای است که داده‌های موجود در ساختار siginfo_t را نشان می‌دهد و دارای ویژگی‌های زیر است:

  • si_pid (شناسه فرایند)

  • si_uid (شناسه کاربری واقعی فرزند)

  • si_signo (همیشه SIGCHLD)

  • si_status (وضعیت خروج یا شماره سیگنال، بسته به si_code)

  • si_code (برای مقادیر ممکن CLD_EXITED را ببینید)

اگر WNOHANG مشخص شده باشد و هیچ فرزند منطبقی در وضعیت درخواست‌شده وجود نداشته باشد، None بازگردانده می‌شود. در غیر این صورت، اگر هیچ فرزند منطبقی که بتوان منتظر آن ماند وجود نداشته باشد، ChildProcessError پرتاب می‌شود.

دسترس‌پذیری: Unix, not WASI, not Android, not iOS.

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

تغییر یافته در نسخه‌ی 3.13: این تابع اکنون در macOS نیز در دسترس است.

os.waitpid(pid, options, /)

جزئیات این تابع در یونیکس و ویندوز متفاوت است.

در یونیکس: منتظر تکمیل فرایند فرزندی که با شناسه‌ی فرایند pid مشخص‌شده است می‌ماند، و یک تاپل شامل شناسه‌ی فرایند و نشانگر وضعیت خروج آن (کدگذاری‌شده مانند wait()) برمی‌گرداند. رفتار این فراخوانی تحت تأثیر مقدار عدد صحیح options است که برای عملکرد عادی باید 0 باشد.

اگر pid بزرگ‌تر از 0 باشد، waitpid() اطلاعات وضعیت آن فرایند مشخص را درخواست می‌کند. اگر pid برابر 0 باشد، درخواست برای وضعیت هر فرایند فرزند در گروه فرایند فرایند جاری است. اگر pid برابر -1 باشد، درخواست مربوط به هر فرایند فرزند فرایند جاری است. اگر pid کوچک‌تر از -1 باشد، وضعیت برای هر فرایند در گروه فرایند -pid (قدر مطلق pid) درخواست می‌شود.

options ترکیبی از پرچم‌ها با عملگر OR است. اگر شامل WNOHANG باشد و هیچ فرزند منطبقی در وضعیت درخواست‌شده وجود نداشته باشد، (0, 0) بازگردانده می‌شود. در غیر این صورت، اگر هیچ فرزند منطبقی که بتوان برای آن انتظار کشید وجود نداشته باشد، ChildProcessError پرتاب می‌شود. گزینه‌های دیگری که می‌توان از آن‌ها استفاده کرد، WUNTRACED و WCONTINUED هستند.

در ویندوز: منتظر تکمیل فرایندی که با دسته‌گیره‌ی فرایند pid مشخص شده است می‌ماند و یک تاپل شامل pid و وضعیت خروج آن که به اندازه‌ی ۸ بیت به چپ شیفت داده شده است برمی‌گرداند (شیفت دادن، استفاده‌ی بین‌سکویی از تابع را آسان‌تر می‌کند). یک pid کوچک‌تر یا مساوی 0 در ویندوز معنای خاصی ندارد و استثنایی را پرتاب می‌کند. مقدار عدد صحیح options تأثیری ندارد. pid می‌تواند به هر فرایندی که شناسه‌ی آن شناخته‌شده است اشاره کند، نه لزوماً به یک فرایند فرزند. توابع spawn* فراخوانی‌شده با P_NOWAIT، دسته‌گیره‌های مناسب فرایند برمی‌گردانند.

می‌توان از waitstatus_to_exitcode() برای تبدیل وضعیت خروج به کد خروج استفاده کرد.

دسترس‌پذیری: Unix, Windows, not WASI, not Android, not iOS.

تغییر یافته در نسخه‌ی 3.5: اگر فراخوانی سیستمی دچار وقفه شود و مدیر سیگنال استثنایی پرتاب نکند، تابع اکنون به‌جای پرتاب استثنای InterruptedError، فراخوانی سیستمی را مجدداً اجرا می‌کند (برای مشاهده دلیل، PEP 475 را ببینید).

os.wait3(options)

مشابه waitpid() است، با این تفاوت که آرگومان شناسه‌ی فرایند داده نمی‌شود و یک تاپل ۳ عنصری شامل شناسه‌ی فرایند فرزند، نشانگر وضعیت خروج و اطلاعات مصرف منابع بازگردانده می‌شود. برای جزئیات درباره اطلاعات مصرف منابع، به resource.getrusage() مراجعه کنید. آرگومان options همان آرگومانی است که به waitpid() و wait4() داده می‌شود.

می‌توان از waitstatus_to_exitcode() برای تبدیل وضعیت خروج به کد خروج استفاده کرد.

دسترس‌پذیری: Unix, not WASI, not Android, not iOS.

os.wait4(pid, options)

مشابه waitpid() است، با این تفاوت که یک تاپل ۳ عضوی شامل شناسه فرایند فرزند، نشانگر وضعیت خروج و اطلاعات مصرف منابع بازگردانده می‌شود. برای جزئیات درباره اطلاعات مصرف منابع به resource.getrusage() مراجعه کنید. آرگومان‌های wait4() همان آرگومان‌های waitpid() هستند.

می‌توان از waitstatus_to_exitcode() برای تبدیل وضعیت خروج به کد خروج استفاده کرد.

دسترس‌پذیری: Unix, not WASI, not Android, not iOS.

os.P_PID
os.P_PGID
os.P_ALL
os.P_PIDFD

این‌ها مقادیر ممکن برای idtype در waitid() هستند. آن‌ها بر چگونگی تفسیر id تأثیر می‌گذارند:

  • P_PID - منتظر فرزند که PID آن id است بمانید.

  • P_PGID - منتظر هر فرزندی که شناسه گروه فرایند آن id است بمانید.

  • P_ALL - منتظر هر فرزند می‌ماند؛ id نادیده گرفته می‌شود.

  • P_PIDFD - منتظر فرزند شناسایی‌شده با توصیف‌گر پرونده id (یک توصیف‌گر پرونده فرایند که با pidfd_open() ایجاد شده است) بمانید.

دسترس‌پذیری: Unix, not WASI, not Android, not iOS.

توجه

P_PIDFD فقط در لینوکس >= 5.4 در دسترس است.

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

اضافه شده در نسخه‌ی 3.9: ثابت P_PIDFD.

os.WCONTINUED

این پرچم options برای waitpid()، wait3()، wait4() و waitid() سبب می‌شود فرآیندهای فرزند در صورتی گزارش شوند که از آخرین باری که گزارش شده‌اند، از حالت توقف ناشی از کنترل کار ادامه یافته باشند.

دسترس‌پذیری: Unix, not WASI, not Android, not iOS.

os.WEXITED

این پرچم options برای waitid() موجب می‌شود فرآیندهای فرزندی که خاتمه‌یافته‌اند گزارش شوند.

سایر توابع wait* همیشه فرآیندهای فرزندی را که خاتمه یافته‌اند گزارش می‌کنند، بنابراین این گزینه برای آن‌ها در دسترس نیست.

دسترس‌پذیری: Unix, not WASI, not Android, not iOS.

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

os.WSTOPPED

این پرچم options برای waitid() باعث می‌شود فرآیندهای فرزندی که با تحویل یک سیگنال متوقف شده‌اند، گزارش شوند.

این گزینه برای سایر توابع wait* در دسترس نیست.

دسترس‌پذیری: Unix, not WASI, not Android, not iOS.

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

os.WUNTRACED

این پرچم options برای waitpid()، wait3() و wait4() باعث می‌شود فرآیندهای فرزند نیز در صورتی گزارش شوند که متوقف شده باشند، اما وضعیت فعلی آن‌ها از زمان توقفشان گزارش نشده باشد.

این گزینه برای waitid() در دسترس نیست.

دسترس‌پذیری: Unix, not WASI, not Android, not iOS.

os.WNOHANG

این پرچم options باعث می‌شود waitpid()، wait3()، wait4() و waitid() در صورتی که هیچ وضعیت فرآیند فرزندی به‌صورت فوری در دسترس نباشد، بلافاصله بازگردند.

دسترس‌پذیری: Unix, not WASI, not Android, not iOS.

os.WNOWAIT

این پرچم options باعث می‌شود waitid() فرزند را در وضعیتی انتظارپذیر باقی بگذارد، تا بتوان با فراخوانی بعدی wait*() دوباره اطلاعات وضعیت فرزند را دریافت کرد.

این گزینه برای سایر توابع wait* در دسترس نیست.

دسترس‌پذیری: Unix, not WASI, not Android, not iOS.

os.CLD_EXITED
os.CLD_KILLED
os.CLD_DUMPED
os.CLD_TRAPPED
os.CLD_STOPPED
os.CLD_CONTINUED

این‌ها مقادیر ممکن برای si_code در نتیجه‌ی برگردانده‌شده توسط waitid() هستند.

دسترس‌پذیری: Unix, not WASI, not Android, not iOS.

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

تغییر یافته در نسخه‌ی 3.9: مقادیر CLD_KILLED و CLD_STOPPED افزوده شدند.

os.waitstatus_to_exitcode(status)

تبدیل وضعیت انتظار به کد خروجی.

در یونیکس:

  • اگر فرآیند به‌طور عادی خارج شده باشد (اگر WIFEXITED(status) درست باشد)، وضعیت خروج فرآیند را برمی‌گرداند (WEXITSTATUS(status) را برمی‌گرداند): نتیجه بزرگ‌تر یا مساوی ۰.

  • اگر فرایند با یک سیگنال خاتمه یافته باشد (اگر WIFSIGNALED(status) درست باشد)، -signum را برمی‌گرداند که signum شماره سیگنالی است که باعث خاتمه فرایند شده است (-WTERMSIG(status) را برمی‌گرداند): نتیجه کمتر از ۰.

  • در غیر این صورت، یک ValueError پرتاب می‌شود.

در ویندوز، status را به اندازه‌ی ۸ بیت به راست شیفت‌یافته برمی‌گرداند.

در یونیکس، اگر فرایند در حال ردگیری باشد یا اگر waitpid() با گزینه‌ی WUNTRACED فراخوانی شده باشد، فراخواننده باید ابتدا بررسی کند که آیا WIFSTOPPED(status) درست است یا خیر. اگر WIFSTOPPED(status) درست باشد، این تابع نباید فراخوانی شود.

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

توابع WIFEXITED()، WEXITSTATUS()، WIFSIGNALED()، WTERMSIG()، WIFSTOPPED()، WSTOPSIG().

دسترس‌پذیری: Unix, Windows, not WASI, not Android, not iOS.

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

توابع زیر یک کد وضعیت فرایند را که توسط system()، wait() یا waitpid() بازگشت داده شده است، به‌عنوان پارامتر دریافت می‌کنند. می‌توان از آن‌ها برای تعیین سرنوشت یک فرایند استفاده کرد.

os.WCOREDUMP(status, /)

اگر برای فرایند یک برون‌ریزی هسته تولید شده باشد، True برمی‌گرداند، در غیر این صورت False برمی‌گرداند.

این تابع باید تنها زمانی استفاده شود که WIFSIGNALED() درست باشد.

دسترس‌پذیری: Unix, not WASI, not Android, not iOS.

os.WIFCONTINUED(status)

اگر یک فرزند متوقف‌شده با ارسال SIGCONT از سر گرفته شده باشد (اگر فرایند از یک توقف کنترل کار ادامه یافته باشد)، True را برمی‌گرداند، در غیر این صورت False را برمی‌گرداند.

گزینه‌ی WCONTINUED را ببینید.

دسترس‌پذیری: Unix, not WASI, not Android, not iOS.

os.WIFSTOPPED(status)

اگر فرایند با ارسال یک سیگنال متوقف شده باشد، True را برمی‌گرداند، در غیر این صورت False را برمی‌گرداند.

WIFSTOPPED() تنها در صورتی True را برمی‌گرداند که فراخوانی waitpid() با استفاده از گزینه‌ی WUNTRACED انجام شده باشد یا فرایند در حال ردگیری باشد (به ptrace(2) مراجعه کنید).

دسترس‌پذیری: Unix, not WASI, not Android, not iOS.

os.WIFSIGNALED(status)

اگر فرایند با یک سیگنال خاتمه یافته باشد، True برمی‌گرداند؛ در غیر این صورت False برمی‌گرداند.

دسترس‌پذیری: Unix, not WASI, not Android, not iOS.

os.WIFEXITED(status)

اگر فرایند به‌صورت عادی خاتمه یافته باشد، یعنی با فراخوانی exit() یا _exit()، یا با بازگشت از main()، مقدار True را برمی‌گرداند؛ در غیر این صورت مقدار False را برمی‌گرداند.

دسترس‌پذیری: Unix, not WASI, not Android, not iOS.

os.WEXITSTATUS(status)

وضعیت خروج فرایند را برمی‌گرداند.

این تابع باید تنها در صورتی استفاده شود که WIFEXITED() درست باشد.

دسترس‌پذیری: Unix, not WASI, not Android, not iOS.

os.WSTOPSIG(status)

سیگنالی را که باعث توقف فرآیند شد، برمی‌گرداند.

این تابع باید تنها در صورتی استفاده شود که WIFSTOPPED() درست باشد.

دسترس‌پذیری: Unix, not WASI, not Android, not iOS.

os.WTERMSIG(status)

شماره‌ی سیگنالی را که باعث خاتمه‌ی فرایند شده است، برمی‌گرداند.

این تابع باید تنها زمانی استفاده شود که WIFSIGNALED() درست باشد.

دسترس‌پذیری: Unix, not WASI, not Android, not iOS.

رابط با زمان‌بند

این توابع چگونگی تخصیص زمان پردازنده به یک فرایند توسط سیستم‌عامل را کنترل می‌کنند. این توابع تنها در برخی از پلتفرم‌های یونیکس در دسترس هستند. برای اطلاعات دقیق‌تر، به صفحات man یونیکس خود مراجعه کنید.

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

سیاست‌های زمان‌بندی زیر در صورت پشتیبانی سیستم‌عامل، در دسترس قرار می‌گیرند.

os.SCHED_OTHER

سیاست زمان‌بندی پیش‌فرض.

os.SCHED_BATCH

سیاست زمان‌بندی برای فرآیندهای پرمصرف CPU که تلاش می‌کند تعامل‌پذیری بقیه‌ی رایانه را حفظ کند.

os.SCHED_DEADLINE

سیاست زمان‌بندی برای وظایف دارای محدودیت‌های مهلت.

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

os.SCHED_IDLE

سیاست زمان‌بندی برای وظایف پس‌زمینه با اولویت بسیار پایین.

os.SCHED_NORMAL

نام مستعاری برای SCHED_OTHER.

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

os.SCHED_SPORADIC

سیاست زمان‌بندی برای برنامه‌های سرور گاه‌به‌گاه.

os.SCHED_FIFO

یک سیاست زمان‌بندی اولین ورود، اولین خروج (First In First Out).

os.SCHED_RR

یک سیاست زمان‌بندی نوبتی (round-robin).

os.SCHED_RESET_ON_FORK

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

class os.sched_param(sched_priority)

این کلاس نشان‌دهنده‌ی پارامترهای زمان‌بندی قابل‌تنظیم مورد استفاده در sched_setparam()، sched_setscheduler() و sched_getparam() است. این کلاس تغییرناپذیر است.

در حال حاضر، تنها یک پارامتر ممکن وجود دارد:

sched_priority

اولویت زمان‌بندی برای یک سیاست زمان‌بندی.

os.sched_get_priority_min(policy)

کمترین مقدار اولویت برای policy را دریافت کنید. policy یکی از ثابت‌های سیاست زمان‌بندی در بالا است.

os.sched_get_priority_max(policy)

بیشترین مقدار اولویت را برای policy دریافت کنید. policy یکی از ثابت‌های سیاست زمان‌بندی در بالا است.

os.sched_setscheduler(pid, policy, param, /)

سیاست زمان‌بندی را برای فرایند با PID pid تنظیم می‌کند. مقدار ۰ برای pid به معنای فرایند فراخوان است. policy یکی از ثابت‌های سیاست زمان‌بندی بالا است. param یک نمونه از sched_param است.

os.sched_getscheduler(pid, /)

سیاست زمان‌بندی برای فرایندی با PID pid را برمی‌گرداند. مقدار ۰ برای pid به معنای فرایند فراخوان است. نتیجه یکی از ثابت‌های سیاست زمان‌بندی بالا است.

os.sched_setparam(pid, param, /)

پارامترهای زمان‌بندی فرایندی با PID pid را تنظیم می‌کند. مقدار ۰ برای pid به معنای فرایند فراخوان است. param یک نمونه از sched_param است.

os.sched_getparam(pid, /)

برگرداندن پارامترهای زمان‌بندی به‌صورت یک نمونه از sched_param برای فرایندی با PID pid. مقدار ۰ برای pid به معنای فرایند فراخوان است.

os.sched_rr_get_interval(pid, /)

کوانتوم نوبت‌گردشی (round-robin quantum) را بر حسب ثانیه برای فرایندی با PID pid برمی‌گرداند. مقدار pid برابر ۰ به معنای فرایند فراخوان است.

os.sched_yield()

به‌صورت داوطلبانه CPU را واگذار کنید. برای جزئیات، sched_yield(2) را ببینید.

os.sched_setaffinity(pid, mask, /)

فرایند با PID pid (یا فرایند جاری در صورت صفر بودن) را به مجموعه‌ای از پردازنده‌ها محدود می‌کند. mask یک پیمایش‌پذیر از اعداد صحیح است که مجموعه‌ای از پردازنده‌ها را نشان می‌دهد که فرایند باید به آن‌ها محدود شود.

os.sched_getaffinity(pid, /)

مجموعه‌ی CPUهایی که فرآیند با PID pid به آن‌ها محدود شده است را برمی‌گرداند.

اگر pid صفر باشد، مجموعه‌ی پردازنده‌هایی را برمی‌گرداند که نخ فراخوان فرایند جاری به آن‌ها محدود شده است.

همچنین تابع process_cpu_count() را ببینید.

اطلاعات متفرقه سیستم

os.confstr(name, /)

مقادیر پیکربندی سیستمی با مقدار رشته‌ای را برمی‌گرداند. name مقدار پیکربندی برای واکشی را مشخص می‌کند؛ ممکن است رشته‌ای باشد که نام یک مقدار سیستمی تعریف‌شده است؛ این نام‌ها در تعدادی از استانداردها (POSIX، Unix 95، Unix 98 و دیگر استانداردها) مشخص شده‌اند. برخی سکوها نیز نام‌های اضافه‌ای تعریف می‌کنند. نام‌های شناخته‌شده برای سیستم‌عامل میزبان به‌عنوان کلیدهای دیکشنری confstr_names داده شده‌اند. برای متغیرهای پیکربندی که در آن نگاشت قرار ندارند، ارسال یک عدد صحیح برای name نیز پذیرفته می‌شود.

اگر مقدار پیکربندی مشخص‌شده توسط name تعریف نشده باشد، None برگردانده می‌شود.

اگر name یک رشته باشد و شناخته‌شده نباشد، ValueError پرتاب می‌شود. اگر مقدار خاصی برای name توسط سیستم میزبان پشتیبانی نشود، حتی اگر در confstr_names وجود داشته باشد، یک OSError با errno.EINVAL به‌عنوان شماره خطا پرتاب می‌شود.

دسترس‌پذیری: Unix.

os.confstr_names

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

دسترس‌پذیری: Unix.

os.cpu_count()

تعداد CPUهای منطقی در سیستم را برمی‌گرداند. در صورت نامشخص بودن، None برمی‌گرداند.

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

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

تغییر یافته در نسخه‌ی 3.13: اگر -X cpu_count داده شده باشد یا PYTHON_CPU_COUNT تنظیم شده باشد، cpu_count() مقدار جایگزین n را برمی‌گرداند.

os.getloadavg()

میانگین تعداد فرآیندهای موجود در صف اجرای سیستم در ۱، ۵ و ۱۵ دقیقه اخیر را برمی‌گرداند یا اگر میانگین بار قابل‌دسترس نباشد، OSError را پرتاب می‌کند.

دسترس‌پذیری: Unix.

os.process_cpu_count()

دریافت تعداد پردازنده‌های منطقی قابل‌استفاده برای نخ فراخواننده‌ی فرایند جاری. در صورت نامشخص بودن، None برمی‌گرداند. ممکن است بسته به وابستگی به پردازنده (CPU affinity) کمتر از cpu_count() باشد.

می‌توان از تابع cpu_count() برای دریافت تعداد پردازنده‌های منطقی در سیستم استفاده کرد.

اگر -X cpu_count داده شده باشد یا PYTHON_CPU_COUNT تنظیم شده باشد، process_cpu_count() مقدار جایگزین n را بازمی‌گرداند.

همچنین تابع sched_getaffinity() را نیز ببینید.

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

os.sysconf(name, /)

مقادیر پیکربندی سامانه با مقدار عدد صحیح را برمی‌گرداند. اگر مقدار پیکربندی مشخص‌شده با name تعریف‌نشده باشد، -1 برگردانده می‌شود. کامنت‌های مربوط به پارامتر name برای confstr() در اینجا نیز صدق می‌کند؛ دیکشنری‌ای که اطلاعاتی درباره‌ی نام‌های شناخته‌شده ارائه می‌دهد، sysconf_names است.

دسترس‌پذیری: Unix.

os.sysconf_names

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

دسترس‌پذیری: Unix.

تغییر یافته در نسخه‌ی 3.11: نام 'SC_MINSIGSTKSZ' را اضافه کنید.

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

عملیات سطح بالاتر روی مسیرها در ماژول os.path تعریف شده‌اند.

os.curdir

رشته ثابتی که سیستم‌عامل برای ارجاع به پوشه جاری از آن استفاده می‌کند. این مقدار برای ویندوز و POSIX برابر '.' است. همچنین از طریق os.path نیز در دسترس است.

os.pardir

رشته‌ی ثابتی که سیستم‌عامل برای ارجاع به پوشه‌ی والد از آن استفاده می‌کند. این رشته برای ویندوز و POSIX برابر با '..' است. همچنین از طریق os.path نیز در دسترس است.

os.sep

نویسه‌ای که سیستم‌عامل برای جداسازی کامپوننت‌های مسیر از آن استفاده می‌کند. این مقدار برای POSIX '/' و برای ویندوز '\\' است. توجه داشته باشید که دانستن این مقدار برای تجزیه یا الحاق مسیرها کافی نیست — از os.path.split() و os.path.join() استفاده کنید — اما این مقدار گاهی مفید است. همچنین از طریق os.path نیز در دسترس است.

os.altsep

یک نویسه جایگزین که توسط سیستم‌عامل برای جداسازی کامپوننت‌های مسیرنام استفاده می‌شود، یا None اگر تنها یک نویسه جداکننده وجود داشته باشد. این مقدار در سیستم‌های ویندوزی که در آن‌ها sep یک بک‌اسلش (backslash) است، روی '/' تنظیم شده است. همچنین از طریق os.path در دسترس است.

os.extsep

نویسه‌ای که نام پایه‌ی پرونده را از پسوند جدا می‌کند؛ برای مثال، '.' در os.py. همچنین از طریق os.path نیز در دسترس است.

os.pathsep

نویسه‌ای که به‌طور معمول توسط سیستم‌عامل برای جدا کردن اجزای مسیر جستجو (مانند PATH) استفاده می‌شود، مانند ':' برای POSIX یا ';' برای Windows. همچنین از طریق os.path در دسترس است.

os.defpath

مسیر جستجوی پیش‌فرضی که exec*p* و spawn*p* از آن استفاده می‌کنند، در صورتی که محیط فاقد کلید 'PATH' باشد. همچنین از طریق os.path در دسترس است.

os.linesep

رشته‌ای که برای جدا کردن (یا به‌طور دقیق‌تر، پایان دادن) سطرها در سکوی فعلی استفاده می‌شود. این ممکن است یک نویسه باشد، مانند '\n' برای POSIX، یا چند نویسه باشد، برای مثال '\r\n' برای Windows. هنگام نوشتن پرونده‌هایی که در حالت متنی باز شده‌اند (حالت پیش‌فرض)، از os.linesep به‌عنوان پایان‌دهنده خط استفاده نکنید؛ در عوض، در تمام سکوها از یک '\n' استفاده کنید.

os.devnull

مسیر پرونده دستگاه null. برای مثال: '/dev/null' برای POSIX، 'nul' برای ویندوز. همچنین از طریق os.path نیز در دسترس است.

os.RTLD_LAZY
os.RTLD_NOW
os.RTLD_GLOBAL
os.RTLD_LOCAL
os.RTLD_NODELETE
os.RTLD_NOLOAD
os.RTLD_DEEPBIND

پرچم‌هایی برای استفاده با توابع setdlopenflags() و getdlopenflags(). برای آگاهی از معنای پرچم‌های مختلف، صفحه‌ی راهنمای یونیکس dlopen(3) را ببینید.

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

اعداد تصادفی

os.getrandom(size, flags=0)

حداکثر size بایت تصادفی را دریافت کنید. این تابع ممکن است بایت‌های کمتری نسبت به تعداد درخواست‌شده برگرداند.

می‌توان از این بایت‌ها برای بذردهی به تولیدگرهای اعداد تصادفی فضای کاربر یا برای اهداف رمزنگاری استفاده کرد.

getrandom() به آنتروپی گردآوری‌شده از راه‌اندازهای دستگاه و دیگر منابع نویز محیطی متکی است. خواندن مقادیر زیادی از داده به‌طور غیرضروری، تأثیر منفی بر سایر کاربران دستگاه‌های /dev/random و /dev/urandom خواهد داشت.

آرگومان flags یک نقاب بیتی است که می‌تواند شامل صفر یا چند مقدار از مقادیر زیر باشد که با OR بیتی با هم ترکیب شده‌اند: os.GRND_RANDOM و GRND_NONBLOCK.

همچنین صفحه‌ی راهنمای getrandom() در لینوکس را ببینید.

دسترس‌پذیری: Linux >= 3.17.

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

os.urandom(size, /)

یک رشته‌بایت (bytestring) از size بایت تصادفی مناسب برای استفاده در رمزنگاری برمی‌گرداند.

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

در لینوکس، اگر فراخوانی سیستمی getrandom() در دسترس باشد، در حالت مسدودکننده استفاده می‌شود: تا زمانی مسدود می‌ماند که استخر آنتروپی urandom سیستم مقداردهی اولیه شده باشد (۱۲۸ بیت آنتروپی توسط کرنل جمع‌آوری شده باشد). برای دیدن دلایل، PEP 524 را ببینید. در لینوکس، می‌توان از تابع getrandom() برای دریافت بایت‌های تصادفی در حالت غیرمسدودکننده (با استفاده از پرچم GRND_NONBLOCK) یا برای پایش تا زمان مقداردهی اولیه‌ی استخر آنتروپی urandom سیستم استفاده کرد.

در سیستم‌های شبه‌یونیکس، بایت‌های تصادفی از دستگاه /dev/urandom خوانده می‌شوند. اگر دستگاه /dev/urandom در دسترس نباشد یا قابل خواندن نباشد، استثنای NotImplementedError پرتاب می‌شود.

در ویندوز، از BCryptGenRandom() استفاده خواهد شد.

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

ماژول secrets توابع سطح بالاتری را فراهم می‌کند. برای استفاده از رابطی آسان برای تولیدکننده‌ی اعداد تصادفی ارائه‌شده توسط سکوی شما، لطفاً random.SystemRandom را ببینید.

تغییر یافته در نسخه‌ی 3.5: در لینوکس 3.17 و جدیدتر، اکنون در صورت دسترسی از فراخوانی سیستمی getrandom() استفاده می‌شود. در OpenBSD 5.6 و جدیدتر، اکنون از تابع getentropy() در C استفاده می‌شود. این توابع از استفاده از یک توصیف‌گر پرونده داخلی اجتناب می‌کنند.

تغییر یافته در نسخه‌ی 3.5.2: در لینوکس، اگر فراخوانی سیستمی getrandom() مسدود شود (استخر آنتروپی urandom هنوز مقداردهی اولیه نشده است)، به خواندن /dev/urandom بازمی‌گردد.

تغییر یافته در نسخه‌ی 3.6: در لینوکس، اکنون از getrandom() در حالت مسدودکننده برای افزایش امنیت استفاده می‌شود.

تغییر یافته در نسخه‌ی 3.11: در ویندوز، به‌جای CryptGenRandom() که منسوخ شده است، از BCryptGenRandom() استفاده می‌شود.

os.GRND_NONBLOCK

به‌طور پیش‌فرض، هنگام خواندن از /dev/random، getrandom() در صورتی مسدود می‌شود که هیچ بایت تصادفی در دسترس نباشد، و هنگام خواندن از /dev/urandom، در صورتی مسدود می‌شود که استخر آنتروپی (entropy pool) هنوز مقداردهی اولیه نشده باشد.

اگر پرچم GRND_NONBLOCK تنظیم شده باشد، getrandom() در این موارد مسدود نمی‌شود، بلکه بلافاصله BlockingIOError را پرتاب می‌کند.

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

os.GRND_RANDOM

اگر این بیت تنظیم شده باشد، بایت‌های تصادفی از استخر /dev/random به‌جای استخر /dev/urandom برداشت می‌شوند.

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