Scroll to navigation

statx(2) System Calls Manual statx(2)

الاسم

statx - جلب حالة الملف (موسع)

المكتبة

مكتبة سي المعيارية (libc، -lc)

موجز

#define _GNU_SOURCE          /* انظر feature_test_macros(7) */
#include <fcntl.h>           /* تعريف ثوابت AT_* */
#include <sys/stat.h>
int statx(int dirfd, const char *restrict pathname, int flags,
          unsigned int mask, struct statx *restrict statxbuf);

الوصف

تُعيد هذه الدالة معلومات حول ملف ما، وتخزنها في المخزن المؤقت الذي يشير إليه statxbuf. المخزن المؤقت المُعاد هو هيكل من النوع التالي:


struct statx {


    __u32 stx_mask;        /* قناع من البتات يشير إلى


                              الحقول المملوءة */


    __u32 stx_blksize;     /* حجم الكتلة لعمليات إدخال/إخراج نظام الملفات */


    __u64 stx_attributes;  /* مؤشرات سمات ملف إضافية */


    __u32 stx_nlink;       /* عدد الروابط الصلبة */


    __u32 stx_uid;         /* معرف مستخدم المالك */


    __u32 stx_gid;         /* معرف مجموعة المالك */


    __u16 stx_mode;        /* نوع الملف ووضعه */


    __u64 stx_ino;         /* رقم أينود (Inode) */


    __u64 stx_size;        /* الحجم الإجمالي بالبايت */


    __u64 stx_blocks;      /* عدد الكتل المخصصة سعة 512B */


    __u64 stx_attributes_mask;


                           /* قناع لتوضيح ما هو مدعوم


                              في stx_attributes */


    /* الحقول التالية هي طوابع زمنية للملف */


    struct statx_timestamp stx_atime;  /* آخر وصول */


    struct statx_timestamp stx_btime;  /* الإنشاء */


    struct statx_timestamp stx_ctime;  /* آخر تغيير للحالة */


    struct statx_timestamp stx_mtime;  /* آخر تعديل */


    /* إذا كان هذا الملف يمثل جهازًا، فإن الحقلين


       التاليين يحتويان على معرف الجهاز */


    __u32 stx_rdev_major;  /* المعرف الرئيسي */


    __u32 stx_rdev_minor;  /* المعرف الثانوي */


    /* يحتوي الحقلان التاليان على معرف الجهاز


       الذي يحتوي على نظام الملفات حيث يوجد الملف */


    __u32 stx_dev_major;   /* المعرف الرئيسي */


    __u32 stx_dev_minor;   /* المعرف الثانوي */


    __u64 stx_mnt_id;      /* معرف الوصل */


    /* قيود محاذاة الإدخال/الإخراج المباشر */


    __u32 stx_dio_mem_align;


    __u32 stx_dio_offset_align;
};

الطوابع الزمنية للملف هي هياكل من النوع التالي:


struct statx_timestamp {


    __s64 tv_sec;    /* الثواني منذ العصر (توقيت يونكس) */


    __u32 tv_nsec;   /* النانو ثانية منذ tv_sec */
};

(لاحظ أن المساحة المحجوزة والحشو قد حُذفا.)

استدعاء statx():

للوصول إلى حالة ملف ما، لا يلزم وجود أذونات على الملف نفسه، ولكن في حالة statx() مع مسار، يلزم وجود إذن تنفيذ (بحث) على جميع الأدلة الموجودة في pathname التي تؤدي إلى الملف.

يستخدم statx() كلاً من pathname و dirfd و flags لتحديد الملف المستهدف بإحدى الطرق التالية:

مسار مطلق
إذا بدأ pathname بشرطة مائلة، فإنه يكون مسارًا مطلقًا يحدد الملف المستهدف. وفي هذه الحالة، يُتجاهل dirfd.
مسار نسبي
إذا كان pathname سلسلة نصية تبدأ بمحرف غير الشرطة المائلة وكان dirfd هو AT_FDCWD، فإن pathname يكون مسارًا نسبيًا يُفسر بالنسبة لدليل العمل الحالي للعملية.
مسار نسبي بالنسبة لدليل
إذا كان pathname سلسلة نصية تبدأ بمحرف غير الشرطة المائلة وكان dirfd واصف ملف يشير إلى دليل، فإن pathname يكون مسارًا نسبيًا يُفسر بالنسبة للدليل الذي يشير إليه dirfd. (انظر openat(2) لشرح سبب فائدة ذلك.)
بواسطة واصف الملف
إذا كان pathname سلسلة فارغة وحُددت علامة AT_EMPTY_PATH في flags (انظر أدناه)، فإن الملف المستهدف هو الملف الذي يشير إليه واصف الملف dirfd.

يمكن استخدام flags للتأثير على البحث المستند إلى المسار. تُبنى قيمة flags عبر إجراء عملية OR لواحد أو أكثر من الثوابت التالية:

إذا كان pathname سلسلة فارغة، فتُجرى العملية على الملف الذي يشير إليه dirfd (والذي قد يكون قد حُصل عليه باستخدام علامة O_PATH في open(2)). في هذه الحالة، يمكن أن يشير dirfd إلى أي نوع من الملفات، وليس فقط الدليل.
إذا كان dirfd هو AT_FDCWD، فإن الاستدعاء يعمل على دليل العمل الحالي.
لا تصله آليًا للمكون الطرفي ("basename") لـ pathname إذا كان دليلاً يمثل نقطة وصل آلي. يتيح ذلك للمستدعِي جمع سمات نقطة الوصل الآلي (بدلاً من الموقع الذي ستُوصل فيه). ليس لهذه العلامة أي تأثير إذا كانت نقطة الوصل قد وُصلت بالفعل.
يمكن استخدام العلامة AT_NO_AUTOMOUNT في الأدوات التي تفحص الأدلة لمنع الوصل الآلي الجماعي لدليل يحتوي على نقاط وصل آلي.
كل من stat(2) و lstat(2) و fstatat(2) تعمل كما لو أن AT_NO_AUTOMOUNT كانت مضبوطة.
إذا كان pathname رابطًا رمزيًا، فلا تتبعه: وبدلاً من ذلك، ارجع معلومات عن الرابط نفسه، مثل lstat(2).

يمكن أيضًا استخدام flags للتحكم في نوع المزامنة التي ستقوم بها النواة عند الاستعلام عن ملف في نظام ملفات بعيد. يتم ذلك عن طريق إجراء عملية OR مع إحدى القيم التالية:

افعل ما يفعله stat(2). هذا هو الخيار المبدئي وهو خاص جداً بنوع نظام الملفات.
اجبر المزامنة للسمات مع الخادم. قد يتطلب هذا من نظام ملفات الشبكة إجراء إعادة كتابة للبيانات للحصول على طوابع زمنية صحيحة.
لا تقم بمزامنة أي شيء، بل خذ فقط ما هو موجود في خبيئة النظام إن أمكن. قد يعني هذا أن المعلومات المعادة تقريبية، ولكن في نظام ملفات الشبكة، قد لا يتطلب الأمر رحلة ذهاب وإياب إلى الخادم - حتى لو لم تكن هناك إجارة (lease) قائمة.

تُستخدم المعامل mask في الدالة statx() لإخبار النواة بالحقول التي يهتم بها المستدعِي. mask هو مزيج ORed من الثوابت التالية:


STATX_TYPE طلب stx_mode & S_IFMT
STATX_MODE طلب stx_mode & ~S_IFMT
STATX_NLINK طلب stx_nlink
STATX_UID طلب stx_uid
STATX_GID طلب stx_gid
STATX_ATIME طلب stx_atime
STATX_MTIME طلب stx_mtime
STATX_CTIME طلب stx_ctime
STATX_INO طلب stx_ino
STATX_SIZE طلب stx_size
STATX_BLOCKS طلب stx_blocks
STATX_BASIC_STATS [كل ما سبق]
STATX_BTIME طلب stx_btime
STATX_ALL نفس STATX_BASIC_STATS | STATX_BTIME.
هذا مهجور ولا ينبغي استخدامه.
STATX_MNT_ID طلب stx_mnt_id (منذ لينكس 5.8)
STATX_DIOALIGN يريد stx_dio_mem_align و stx_dio_offset_align
(منذ لينكس 6.1؛ يختلف الدعم حسب نظام الملفات)

لاحظ أن النواة، بصفة عامة، لا ترفض القيم الموجودة في mask بخلاف ما ذُكر أعلاه. (للاطلاع على استثناء، راجع EINVAL في قسم الأخطاء). بدلاً من ذلك، تكتفي النواة بإبلاغ المستدعِي بالقيم التي تدعمها هذه النواة ونظام الملفات عبر الحقل statx.stx_mask. بناءً على ذلك، لا تضبط mask ببساطة على UINT_MAX (تعيين جميع البتات)، فمن المحتمل استخدام بت واحد أو أكثر في المستقبل لتحديد توسعة للمخزن المؤقت.

المعلومات المُعادة

تُعاد معلومات الحالة الخاصة بالملف المستهدف في بنية I التي يشير إليها I. وتتضمن هذه البنية الحقل stx_mask الذي يوضح المعلومات الأخرى التي أُعيدت. يمتلك stx_mask تنسيق المعامل mask نفسه، وتُضبط البتات فيه للإشارة إلى الحقول التي مُلئت.

تجدر الإشارة إلى أن النواة قد تُعيد حقولاً لم تُطلب، وقد تفشل في إعادة حقول طُلبت، اعتماداً على ما يدعمه نظام الملفات الأساسي. (الحقول التي تُعطى قيماً رغم عدم طلبها يمكن تجاهلها ببساطة). في كلتا الحالتين، لن يكون stx_mask مساوياً لـ mask.

إذا كان نظام الملفات لا يدعم حقلاً معيناً أو إذا كانت القيمة غير قابلة للتمثيل (على سبيل المثال، ملف ذو نوع غريب)، فعندئذٍ تُمسح بتة القناع المقابلة لذلك الحقل في stx_mask حتى لو طلبها المستخدم، وتُملأ قيمة صورية لأغراض التوافق إذا كانت متاحة (مثلاً، قد يُحدد معرف مستخدم (UID) ومعرف مجموعة (GID) صوريين عند الوصل في ظروف معينة).

قد يملأ نظام الملفات أيضًا حقولاً لم يطلبها المستدعِي إذا كانت قيمها متاحة لديه وكانت المعلومات متوفرة بدون تكلفة إضافية. إذا حدث هذا، فستُضبط البتات المقابلة في stx_mask.

ملاحظة: لأسباب تتعلق بالأداء والبساطة، قد تحتوي الحقول المختلفة في هيكل statx على معلومات حالة من لحظات مختلفة أثناء تنفيذ استدعاء النظام. على سبيل المثال، إذا غُيّر stx_mode أو stx_uid بواسطة عملية أخرى عبر استدعاء chmod(2) أو chown(2)، فقد يُعيد stat() حقل stx_mode القديم مع حقل stx_uid الجديد، أو stx_uid القديم مع stx_mode الجديد.

بصرف النظر عن stx_mask (الموضح أعلاه)، فإن الحقول في هيكل statx هي:

حجم الكتلة "المفضل" لعمليات الإدخال والإخراج الفعالة في نظام الملفات. (قد تؤدي الكتابة إلى ملف بقطع أصغر إلى عملية قراءة-تعديل-كتابة غير فعالة.)
معلومات حالة إضافية حول الملف (انظر أدناه لمزيد من المعلومات).
عدد الروابط الصلبة على الملف.
يحتوي هذا الحقل على معرف المستخدم لمالك الملف.
يحتوي هذا الحقل على معرف المجموعة المالكة للملف.
نوع الملف ووضعياته. انظر inode(7) للتفاصيل.
رقم الآينود (inode) للملف.
حجم الملف (إذا كان ملفاً عادياً أو رابطاً رمزياً) بالبايت. حجم الرابط الرمزي هو طول اسم المسار الذي يحتويه، بدون بايت فارغ (null) في نهايته.
عدد الكتل المخصصة للملف على الوسيط، بوحدات 512 بايت. (قد يكون هذا أقل من stx_size/512 عندما يحتوي الملف على فجوات.)
قناع يشير إلى البتات في stx_attributes التي يدعمها نظام الملفات الافتراضي (VFS) ونظام الملفات.
طابع وقت آخر وصول للملف.
طابع وقت إنشاء الملف.
طابع وقت آخر تغيير لحالة الملف.
طابع وقت آخر تعديل للملف.
الجهاز الذي يقع عليه هذا الملف (الآينود).
الجهاز الذي يمثله هذا الملف (الآينود) إذا كان الملف من نوع جهاز كتلي أو جهاز محرفي.
معرف الوصل للوصل الذي يحتوي على الملف. هذا هو نفس الرقم الذي يبلغ عنه name_to_handle_at(2) ويقابل الرقم في الحقل الأول في أحد السجلات في /proc/self/mountinfo.
المحاذاة (بالبايت) المطلوبة لذاكرة المستعمل لعمليات الإدخال والإخراج المباشرة (O_DIRECT) على هذا الملف، أو 0 إذا كان الإدخال والإخراج المباشر غير مدعوم على هذا الملف.
STATX_DIOALIGN (أي stx_dio_mem_align و stx_dio_offset_align) مدعوم على الأجهزة الكتلية منذ لينكس 6.1. ويختلف الدعم على الملفات العادية حسب نظام الملفات؛ فهو مدعوم في ext4 و f2fs و xfs منذ لينكس 6.1.
المحاذاة (بالبايت) المطلوبة لإزاحات الملف وأطوال قطع الإدخال والإخراج لعمليات الإدخال والإخراج المباشرة (O_DIRECT) على هذا الملف، أو 0 إذا لم يكن الإدخال والإخراج المباشر مدعوماً. لن تكون هذه القيمة غير صفرية إلا إذا كانت stx_dio_mem_align غير صفرية، والعكس صحيح.

لمزيد من المعلومات حول الحقول المذكورة أعلاه، انظر inode(7).

سمات الملف

يحتوي الحقل stx_attributes على مجموعة من الرايات المدمجة بمعامل OR والتي تشير إلى سمات إضافية للملف. لاحظ أن أي سمة لم يُشر إلى دعمها بواسطة stx_attributes_mask ليس لها قيمة قابلة للاستخدام هنا. تقابل البتات في stx_attributes_mask البتات في stx_attributes بت بـ بت.

الرايات هي كما يلي:

الملف مضغوط بواسطة نظام الملفات وقد يتطلب موارد إضافية للوصول إليه.
لا يمكن تعديل الملف: لا يمكن حذفه أو إعادة تسميته، ولا يمكن إنشاء روابط صلبة له ولا يمكن كتابة أي بيانات فيه. انظر chattr(1).
لا يمكن فتح الملف إلا في وضع الإلحاق للكتابة. الكتابة عبر الوصول العشوائي غير مسموح بها. انظر chattr(1).
الملف ليس مرشحاً للنسخ الاحتياطي عند تشغيل برنامج نسخ احتياطي مثل dump(8). انظر chattr(1).
يتطلب الأمر مفتاحاً ليعمّي نظام الملفات هذا الملف.
الملف مفعّل فيه خاصية fs-verity. لا يمكن الكتابة إليه، وستُحقّق جميع عمليات القراءة منه مقابل هاش تعمية يغطي الملف بأكمله (على سبيل المثال، عبر شجرة ميركل Merkle tree).
الملف في حالة DAX (وصول وحدة المعالجة المركزية المباشر). تحاول حالة DAX تقليل تأثيرات الخبيئة البرمجية لكل من عمليات الإدخال والإخراج وخرائط الذاكرة لهذا الملف. ويتطلب هذا نظام ملفات ضُبط ليدعم DAX.
تفترض DAX عموماً أن جميع عمليات الوصول تتم عبر تعليمات تحميل/تخزين وحدة المعالجة المركزية، مما يقلل العبء في الوصول الصغير، لكنه قد يؤثر سلباً على استهلاك المعالج في عمليات النقل الكبيرة.
يُجرى الإدخال والإخراج للملف مباشرة من وإلى دارات مساحة المستعمل، ويمكن إجراء إدخال وإخراج الذاكرة المخططة (memory mapped I/O) بخرائط ذاكرة مباشرة تتجاوز خبيئة صفحات النواة.
بينما تميل خاصية DAX إلى نقل البيانات بشكل متزامن، إلا أنها لا تعطي نفس ضمانات راية O_SYNC (انظر open(2))، حيث تُنقل البيانات والبيانات الواصفة (metadata) الضرورية معاً.
قد يدعم ملف DAX أن يُخطط باستخدام راية MAP_SYNC، مما يمكّن البرنامج من استخدام تعليمات تفريغ خبيئة المعالج لتثبيت عمليات تخزين المعالج بدون fsync(2) صريح. انظر mmap(2) لمزيد من المعلومات.
الملف هو جذر عملية الوصل.

قيمة الإرجاع

عند النجاح، يُعاد الصفر. وعند حدوث خطأ، يُعاد الرقم -1، ويُضبط errno للإشارة إلى الخطأ.

الأخطاء

رُفض إذن البحث لأحد الأدلة في بادئة مسار pathname. (انظر أيضًا path_resolution(7).)
مسار الملف pathname نسبي ولكن dirfd ليس AT_FDCWD ولا واصف ملف صالح.
pathname أو statxbuf قيمته NULL أو يشير إلى موقع خارج مساحة العناوين التي يمكن للعملية الوصول إليها.
راية غير صالحة محددة في flags.
راية محجوزة محددة في mask. (حالياً، توجد راية واحدة من هذا النوع، يشار إليها بالثابت STATX__RESERVED، بقيمة 0x80000000U.)
وُجدت روابط رمزية كثيرة جداً أثناء تتبع اسم المسار.
مسار الملف pathname طويل جداً.
أحد مكونات pathname غير موجود، أو pathname عبارة عن سلسلة نصية فارغة ولم يُحدد AT_EMPTY_PATH في flags.
نفاد الذاكرة (أي ذاكرة نواة الحاسوب).
أحد مكونات بادئة مسار pathname ليس دليلًا أو pathname مسار نسبي و dirfd واصف ملف يشير إلى ملف آخر غير الدليل.

المعايير

لينكس.

التاريخ

لينكس 4.11، glibc 2.28.

انظر أيضًا

ls(1)، stat(1)، access(2)، chmod(2)، chown(2)، name_to_handle_at(2)، readlink(2)، stat(2)، utime(2)، proc(5)، capabilities(7)، inode(7)، symlink(7)

ترجمة

تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي <zayed.alsaidi@gmail.com>

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: kde-l10n-ar@kde.org.

2 مايو 2024 صفحات دليل لينكس 6.9.1