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

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

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

تغییر یافته در نسخه‌ی 3.4: ماژول stat بر پایه‌ی یک پیاده‌سازی C است.

ماژول 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_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.

توجه

S_IFDOOR، S_IFPORT یا S_IFWHT زمانی که پلتفرم از انواع پرونده پشتیبانی نمی‌کند، به‌صورت ۰ تعریف شده‌اند.

پرچم‌های زیر همچنین می‌توانند در آرگومان 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_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_SNAPSHOT

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

این پرونده یک فیرملینک (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_MOUNT_POINT

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