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 *_Nullable restrict path,
          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;


    __u64 stx_subvol;      /* معرف المجلد الفرعي */


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


    __u32 stx_atomic_write_unit_min;


    __u32 stx_atomic_write_unit_max;


    __u32 stx_atomic_write_segments_max;


    /* محاذاة إزاحة الملف لقراءات الدخل/الخرج المباشر */


    __u32 stx_dio_read_offset_align;


    /* الحد الأقصى الأمثل لوحدة الكتابة الذرية للدخل/الخرج المباشر */


    __u32 stx_atomic_write_unit_max_opt;
};

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


struct statx_timestamp {


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


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

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

استدعاء statx():

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

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

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

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

إذا كان path سلسلة فارغة (أو NULL منذ لينكس 6.11)، فسيجري العمل على الملف الذي يشير إليه dirfd (والذي ربما جُلب باستخدام علامة O_PATH في open(2)). في هذه الحالة، يمكن لـ dirfd أن يشير إلى أي نوع من الملفات، وليس فقط الأدلة.
إذا كان dirfd هو AT_FDCWD، فإن الاستدعاء يعمل على دليل العمل الحالي.
لا تقم بالوصل الآلي لمكون النهاية ("basename") في path إذا كان دليلاً يمثل نقطة وصل آلي. يتيح ذلك للمستدعِي جمع سمات نقطة الوصل الآلي (بدلاً من الموقع الذي سيُوصل إليه). ليس لهذه العلامة أي تأثير إذا وُصلت نقطة الوصل بالفعل.
يمكن استخدام العلامة AT_NO_AUTOMOUNT في الأدوات التي تفحص الأدلة لمنع الوصل الآلي الجماعي لدليل يحتوي على نقاط وصل آلي.
كل من stat(2) و lstat(2) و fstatat(2) تعمل كما لو أن AT_NO_AUTOMOUNT كانت مضبوطة.
إذا كان path وصلة رمزية، فلا تتبعها: بدلاً من ذلك، أعِد معلومات حول الوصلة نفسها، كما يفعل 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؛ يختلف الدعم حسب نظام الملفات)
STATX_MNT_ID_UNIQUE طلب stx_mnt_id فريد (منذ لينكس 6.8)
STATX_SUBVOL طلب stx_subvol
(منذ لينكس 6.10؛ يختلف الدعم حسب نظام الملفات)
STATX_WRITE_ATOMIC طلب stx_atomic_write_unit_min،
stx_atomic_write_unit_max،
stx_atomic_write_segments_max،
و stx_atomic_write_unit_max_opt.
(منذ لينكس 6.11؛ يختلف الدعم حسب نظام الملفات)
STATX_DIO_READ_ALIGN طلب stx_dio_read_offset_align.
(منذ لينكس 6.14؛ يختلف الدعم حسب نظام الملفات)

لاحظ أن النواة، بصفة عامة، لا ترفض القيم الموجودة في 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) ونظام الملفات.
طابع وقت آخر وصول للملف.
طابع وقت إنشاء الملف.
طابع وقت آخر تغيير لحالة الملف.
طابع وقت آخر تعديل للملف.
الجهاز الذي يقع عليه هذا الملف (الآينود).
الجهاز الذي يمثله هذا الملف (الآينود) إذا كان الملف من نوع جهاز كتلي أو جهاز محرفي.
عند استخدام STATX_MNT_ID، هذا هو معرف الوصل (mount ID) لعملية الوصل التي تحتوي على الملف. هذا هو نفس الرقم الذي يُبلغ عنه بواسطة name_to_handle_at(2) ويقابل الرقم الموجود في الحقل الأول في أحد السجلات في /proc/self/mountinfo.
عند استخدام STATX_MNT_ID_UNIQUE، هذا هو معرف الوصل الفريد لعملية الوصل التي تحتوي على الملف. هذا هو الرقم الذي يُبلغ عنه بواسطة listmount(2) وهو المعرف المستخدم للاستعلام عن عملية الوصل باستخدام statmount(2). ويُضمن عدم إعادة استخدامه أثناء تشغيل النظام.
المحاذاة (بالبايت) المطلوبة لذاكرة المستعمل لعمليات الإدخال والإخراج المباشرة (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 غير صفرية، والعكس صحيح.
المحاذاة (بالبايت) المطلوبة لإزاحات الملف وأطوال قطع الإدخال والإخراج لعمليات قراءة الإدخال والإخراج المباشر (O_DIRECT) على هذا الملف. إذا كانت صفراً، فإن الحد في stx_dio_offset_align ينطبق على القراءات أيضًا. إذا لم تكن صفراً، يجب أن تكون هذه القيمة أصغر من أو تساوي stx_dio_offset_align التي يجب أن يوفرها نظام الملفات إذا طلبها التطبيق. لا تتأثر محاذاة الذاكرة في stx_dio_mem_align بهذه القيمة.
STATX_DIO_READ_ALIGN (أي stx_dio_offset_align) مدعوم بواسطة xfs على الملفات العادية منذ لينكس 6.14.
رقم الجزء الفرعي (subvolume) للملف الحالي.
الأجزاء الفرعية هي أدلة متطورة، أي أنها تشكل هيكلاً شجرياً يمكن تصفحه بشكل تعاودي. يختلف الدعم حسب نظام الملفات؛ فهو مدعوم في bcachefs و btrfs منذ لينكس 6.10.
الأحجام الدنيا والقصوى (بالبايت) المدعومة للإدخال والإخراج المباشر (O_DIRECT) على الملف لتتم كتابته مع حماية من الكتابة المبتورة (torn-write protection). ويُضمن أن تكون كل قيمة من هذه القيم هي أس للرقم 2.
STATX_WRITE_ATOMIC (أي stx_atomic_write_unit_min و stx_atomic_write_unit_max و stx_atomic_write_segments_max) مدعوم على الأجهزة الكتلية منذ لينكس 6.11. ويختلف الدعم على الملفات العادية حسب نظام الملفات؛ فهو مدعوم في xfs و ext4 منذ لينكس 6.13.
الحجم الأقصى (بالبايت) المحسن للكتابات الصادرة مع حماية الكتابة المبتورة. إذا لم تكن صفراً، فلن تتجاوز هذه القيمة القيمة الموجودة في stx_atomic_write_unit_max ولن تقل عن القيمة في stx_atomic_write_unit_min. وتشير القيمة صفر إلى أن stx_atomic_write_unit_max هي الحد المحسن. قد تلاحظ كتابات أبطأ عندما يتجاوز حجم الكتابة stx_atomic_write_unit_max_opt (عندما لا تكون صفراً).
العدد الأقصى للعناصر في مصفوفة من المتجهات لكتابة مفعل فيها حماية الكتابة المبتورة. انظر راية RWF_ATOMIC لـ pwritev2(2).

لمزيد من المعلومات حول الحقول المذكورة أعلاه، انظر 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 للإشارة إلى الخطأ.

الأخطاء

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

8 فبراير 2026 صفحات دليل لينكس 6.18