stat --- تفسیر نتایج stat()¶

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

ماژول stat ثابت‌ها و توابعی را برای تفسیر نتایج os.stat()، os.fstat() و os.lstat() (در صورت وجود) تعریف می‌کند. برای جزئیات کامل درباره‌ی فراخوانی‌های stat()، fstat() و lstat()، به مستندات سیستم خود مراجعه کنید.

ماژول stat توابع زیر را برای بررسی انواع خاصی از پرونده تعریف می‌کند:

stat.S_ISDIR(mode)¶

اگر حالت مربوط به یک پوشه باشد، مقدار غیرصفر برمی‌گرداند.

stat.S_ISCHR(mode)¶

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

stat.S_ISBLK(mode)¶

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

stat.S_ISREG(mode)¶

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

stat.S_ISFIFO(mode)¶

اگر حالت از یک FIFO (پایپ نام‌دار) باشد، مقدار غیرصفر برمی‌گرداند.

stat.S_ISLNK(mode)¶

اگر حالت از یک پیوند نمادین باشد، مقدار غیرصفر برمی‌گرداند.

stat.S_ISSOCK(mode)¶

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

stat.S_ISDOOR(mode)¶

اگر حالت از یک در (door) باشد، مقدار غیرصفر برمی‌گرداند.

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

stat.S_ISPORT(mode)¶

اگر حالت از یک پورت رویداد (event port) باشد، غیرصفر برمی‌گرداند.

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

stat.S_ISWHT(mode)¶

اگر حالت از یک whiteout باشد، غیرصفر برمی‌گرداند.

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

دو تابع اضافی برای دستکاری عمومی‌تر حالت پرونده تعریف شده‌اند:

stat.S_IMODE(mode)¶

برگرداندن بخشی از حالت پرونده قابل تنظیم با os.chmod()---یعنی، بیت‌های دسترسی پرونده، به‌همراه بیت چسبنده (sticky bit)، بیت‌های set-group-id و set-user-id (در سیستم‌هایی که از آن‌ها پشتیبانی می‌کنند).

stat.S_IFMT(mode)¶

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

معمولاً برای آزمایش نوع یک پرونده از توابع os.path.is*() استفاده می‌کنید؛ توابع این بخش زمانی مفید هستند که چندین آزمایش روی یک پرونده انجام می‌دهید و می‌خواهید از سربار فراخوانی سیستمی stat() برای هر آزمایش اجتناب کنید. این توابع همچنین هنگام بررسی اطلاعات مربوط به یک پرونده که توسط os.path پشتیبانی نمی‌شود، مانند آزمایش‌های مربوط به دستگاه‌های بلوکی و نویسه‌ای، مفید هستند.

مثال:

import os, sys
from stat import *

def walktree(top, callback):
    '''recursively descend the directory tree rooted at top,
       calling the callback function for each regular file'''

    for f in os.listdir(top):
        pathname = os.path.join(top, f)
        mode = os.lstat(pathname).st_mode
        if S_ISDIR(mode):
            # It's a directory, recurse into it
            walktree(pathname, callback)
        elif S_ISREG(mode):
            # It's a file, call the callback function
            callback(pathname)
        else:
            # Unknown file type, print a message
            print('Skipping %s' % pathname)

def visitfile(file):
    print('visiting', file)

if __name__ == '__main__':
    walktree(sys.argv[1], visitfile)

یک تابع کمکی اضافی برای تبدیل حالت پرونده به رشته‌ای قابل‌خواندن برای انسان ارائه شده است:

stat.filemode(mode)¶

حالت یک پرونده را به رشته‌ای به قالب '-rwxrwxrwx' تبدیل می‌کند.

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

تغییر یافته در نسخه‌ی 3.4: این تابع از S_IFDOOR، S_IFPORT و S_IFWHT پشتیبانی می‌کند.

همه‌ی متغیرهای زیر صرفاً اندیس‌های نمادینی به تاپل ۱۰تایی هستند که توسط os.stat()، os.fstat() یا os.lstat() بازگردانده می‌شود.

stat.ST_MODE¶

حالت محافظت آی‌نود .

stat.ST_INO¶

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

stat.ST_DEV¶

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

stat.ST_NLINK¶

تعداد پیوندها به آی‌نود .

stat.ST_UID¶

شناسه کاربری مالک.

stat.ST_GID¶

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

stat.ST_SIZE¶

اندازه‌ی یک پرونده ساده بر حسب بایت؛ مقدار داده‌ای که در برخی پرونده‌های خاص در انتظار است.

stat.ST_ATIME¶

زمان آخرین دسترسی.

stat.ST_MTIME¶

زمان آخرین تغییر.

stat.ST_CTIME¶

"ctime" همان‌طور که توسط سیستم‌عامل گزارش می‌شود. در برخی سیستم‌ها (مانند Unix)، زمان آخرین تغییر فراداده است و در برخی دیگر (مانند Windows)، زمان ایجاد است (برای جزئیات، مستندات پلتفرم را ببینید).

تفسیر «اندازه‌ی پرونده» بسته به نوع پرونده تغییر می‌کند. برای پرونده‌های معمولی، این مقدار اندازه‌ی پرونده بر حسب بایت است. برای FIFOها و سوکت‌ها در بیشتر انواع یونیکس (از جمله، به‌طور خاص، لینوکس)، «اندازه» تعداد بایت‌هایی است که در زمان فراخوانی os.stat()، os.fstat() یا os.lstat() در انتظار خوانده شدن هستند؛ این موضوع گاهی می‌تواند مفید باشد، به‌ویژه برای پایش یکی از این پرونده‌های خاص پس از باز کردن به‌صورت غیرمسدودکننده. معنای فیلد اندازه برای سایر دستگاه‌های نویسه‌ای و بلوکی، بسته به پیاده‌سازی فراخوانی سیستمی زیربنایی، بیشتر متفاوت است.

متغیرهای زیر، پرچم‌های استفاده‌شده در فیلد ST_MODE را تعریف می‌کنند.

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

stat.S_IFSOCK¶

سوکت.

stat.S_IFLNK¶

پیوند نمادین.

stat.S_IFREG¶

پرونده معمولی.

stat.S_IFBLK¶

دستگاه بلوکی.

stat.S_IFDIR¶

پوشه.

stat.S_IFCHR¶

دستگاه نویسه‌ای.

stat.S_IFIFO¶

FIFO.

stat.S_IFDOOR¶

در.

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

stat.S_IFPORT¶

پورت رویداد.

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

stat.S_IFWHT¶

سفیدی مطلق (Whiteout).

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

پرچم‌های زیر همچنین می‌توانند در آرگومان mode تابع os.chmod() استفاده شوند:

stat.S_ISUID¶

تنظیم بیت UID.

stat.S_ISGID¶

بیت Set-group-ID. این بیت چندین کاربرد خاص دارد. برای یک پوشه، نشان می‌دهد که باید از رفتار BSD برای آن پوشه استفاده شود: پرونده‌های ایجادشده در آن، شناسه‌ی گروه خود را از پوشه به ارث می‌برند، نه از شناسه‌ی گروه مؤثر فرایند ایجادکننده، و بیت S_ISGID نیز برای پوشه‌های ایجادشده در آن تنظیم خواهد شد. برای پرونده‌ای که بیت اجرای گروهی (S_IXGRP) روی آن تنظیم نشده باشد، بیت Set-group-ID نشان‌دهنده‌ی قفل اجباری پرونده/رکورد است (همچنین S_ENFMT را ببینید).

stat.S_ISVTX¶

بیت چسبنده (Sticky bit). هنگامی که این بیت برای یک پوشه تنظیم شده باشد، به این معناست که یک پرونده در آن پوشه فقط توسط مالک پرونده، مالک پوشه، یا یک فرایند دارای امتیاز می‌تواند تغییر نام داده یا حذف شود.

stat.S_IRWXU¶

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

stat.S_IRUSR¶

مالک دارای اجازه‌ی خواندن است.

stat.S_IWUSR¶

مالک اجازه‌ی نوشتن دارد.

stat.S_IXUSR¶

مالک اجازه‌ی اجرا دارد.

stat.S_IRWXG¶

نقاب دسترسی‌های گروه.

stat.S_IRGRP¶

گروه اجازه‌ی خواندن دارد.

stat.S_IWGRP¶

گروه اجازه‌ی نوشتن دارد.

stat.S_IXGRP¶

گروه اجازه‌ی اجرا دارد.

stat.S_IRWXO¶

نقاب دسترسی‌های دیگران (خارج از گروه).

stat.S_IROTH¶

دیگران اجازه‌ی خواندن دارند.

stat.S_IWOTH¶

دیگران دسترسی نوشتن دارند.

stat.S_IXOTH¶

دیگران اجازه‌ی اجرا دارند.

stat.S_ENFMT¶

اعمال قفل پرونده System V. این پرچم با S_ISGID مشترک است: قفل پرونده/رکورد بر روی پرونده‌هایی که بیت اجرای گروهی (S_IXGRP) در آن‌ها فعال نیست، اعمال می‌شود.

stat.S_IREAD¶

مترادف S_IRUSR در Unix V7.

stat.S_IWRITE¶

مترادف Unix V7 برای S_IWUSR.

stat.S_IEXEC¶

مترادف Unix V7 برای S_IXUSR.

می‌توان از پرچم‌های زیر در آرگومان flags تابع os.chflags() استفاده کرد:

stat.UF_SETTABLE¶

تمام پرچم‌های قابل‌تنظیم توسط کاربر.

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

stat.UF_NODUMP¶

پرونده را برون‌ریزی نکنید.

stat.UF_IMMUTABLE¶

ممکن است پرونده تغییر نکرده باشد.

stat.UF_APPEND¶

فقط می‌توان به پرونده الحاق کرد.

stat.UF_OPAQUE¶

پوشه هنگامی که از طریق یک پشته‌ی اجتماع (union stack) مشاهده می‌شود، غیرشفاف است.

stat.UF_NOUNLINK¶

پرونده را نمی‌توان تغییر نام داد یا حذف کرد.

stat.UF_COMPRESSED¶

این پرونده به‌صورت فشرده ذخیره می‌شود (macOS 10.6+).

stat.UF_TRACKED¶

برای مدیریت شناسه‌های سند (macOS) استفاده می‌شود

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

stat.UF_DATAVAULT¶

این پرونده برای خواندن یا نوشتن به یک حق دسترسی (entitlement) نیاز دارد (macOS 10.13+)

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

stat.UF_HIDDEN¶

این پرونده نباید در یک رابط کاربری گرافیکی (GUI) نمایش داده شود (macOS 10.5+).

stat.SF_SETTABLE¶

همه‌ی پرچم‌های قابل‌تغییر توسط ابرکاربر

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

stat.SF_SUPPORTED¶

همه‌ی پرچم‌های پشتیبانی‌شده‌ی ابرکاربر

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

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

stat.SF_SYNTHETIC¶

همه‌ی پرچم‌های مصنوعی فقط‌خواندنی برای ابرکاربر

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

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

stat.SF_ARCHIVED¶

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

stat.SF_IMMUTABLE¶

ممکن است پرونده تغییر نکرده باشد.

stat.SF_APPEND¶

فقط می‌توان به پرونده الحاق کرد.

stat.SF_RESTRICTED¶

این پرونده برای نوشتن در آن به یک حق دسترسی (entitlement) نیاز دارد (macOS 10.13+)

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

stat.SF_NOUNLINK¶

پرونده را نمی‌توان تغییر نام داد یا حذف کرد.

stat.SF_SNAPSHOT¶

این پرونده یک پرونده تصویر لحظه‌ای است.

stat.SF_FIRMLINK¶

این پرونده یک فیرملینک (firmlink) است (macOS 10.15+)

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

stat.SF_DATALESS¶

این پرونده یک شیء بدون داده است (macOS 10.15+)

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

برای اطلاعات بیشتر، صفحه man سیستم‌های *BSD یا macOS با عنوان chflags(2) را ببینید.

در ویندوز، ثابت‌های ویژگی پرونده زیر برای استفاده هنگام بررسی بیت‌های عضو st_file_attributes برگردانده‌شده از os.stat() در دسترس هستند. برای جزئیات بیشتر درباره معنای این ثابت‌ها، مستندات Windows API را ببینید.

stat.FILE_ATTRIBUTE_ARCHIVE¶

stat.FILE_ATTRIBUTE_COMPRESSED¶

stat.FILE_ATTRIBUTE_DEVICE¶

stat.FILE_ATTRIBUTE_DIRECTORY¶

stat.FILE_ATTRIBUTE_ENCRYPTED¶

stat.FILE_ATTRIBUTE_HIDDEN¶

stat.FILE_ATTRIBUTE_INTEGRITY_STREAM¶

stat.FILE_ATTRIBUTE_NORMAL¶

stat.FILE_ATTRIBUTE_NOT_CONTENT_INDEXED¶

stat.FILE_ATTRIBUTE_NO_SCRUB_DATA¶

stat.FILE_ATTRIBUTE_OFFLINE¶

stat.FILE_ATTRIBUTE_READONLY¶

stat.FILE_ATTRIBUTE_REPARSE_POINT¶

stat.FILE_ATTRIBUTE_SPARSE_FILE¶

stat.FILE_ATTRIBUTE_SYSTEM¶

stat.FILE_ATTRIBUTE_TEMPORARY¶

stat.FILE_ATTRIBUTE_VIRTUAL¶

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

در ویندوز، ثابت‌های زیر برای مقایسه با عضو st_reparse_tag برگردانده‌شده توسط os.lstat() در دسترس هستند. این‌ها ثابت‌های شناخته‌شده‌ای هستند، اما فهرستی جامع نیستند.

stat.IO_REPARSE_TAG_SYMLINK¶

stat.IO_REPARSE_TAG_MOUNT_POINT¶

stat.IO_REPARSE_TAG_APPEXECLINK¶

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

در لینوکس، ثابت‌های ویژگی‌های پرونده‌ی زیر برای استفاده هنگام آزمون بیت‌ها در اعضای stx_attributes و stx_attributes_mask که توسط os.statx() بازگردانده می‌شوند، در دسترس هستند. برای جزئیات بیشتر درباره‌ی معنی این ثابت‌ها به صفحه‌ی راهنمای statx(2) مراجعه کنید.

stat.STATX_ATTR_COMPRESSED¶

stat.STATX_ATTR_IMMUTABLE¶

stat.STATX_ATTR_APPEND¶

stat.STATX_ATTR_NODUMP¶

stat.STATX_ATTR_ENCRYPTED¶

stat.STATX_ATTR_AUTOMOUNT¶

stat.STATX_ATTR_MOUNT_ROOT¶

stat.STATX_ATTR_VERITY¶

stat.STATX_ATTR_DAX¶

stat.STATX_ATTR_WRITE_ATOMIC¶

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