stat(2)

الاسم
stat, fstat, lstat, fstatat - الحصول على حالة الملف

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

موجز
#include <sys/stat.h>

int stat(const char *restrict path,
         struct stat *restrict statbuf);
int fstat(int fd, struct stat *statbuf);
int lstat(const char *restrict path,
         struct stat *restrict statbuf);

#include <fcntl.h>           /* تعريف ثوابت AT_* */
#include <sys/stat.h>

int fstatat(int dirfd, const char *restrict path,
         struct stat *restrict statbuf, int flags);

    متطلبات ماكروات اختبار الميزات لـ glibc (انظر feature_test_macros(7)):

lstat():
    /* منذ glibc 2.20 */ _DEFAULT_SOURCE
        || _XOPEN_SOURCE >= 500
        || /* منذ glibc 2.10: */ _POSIX_C_SOURCE >= 200112L
        || /* إصدار glibc 2.19 وما قبله */ _BSD_SOURCE

fstatat():
    منذ glibc 2.10:
        _POSIX_C_SOURCE >= 200809L
    قبل glibc 2.10:
        _ATFILE_SOURCE

الوصف
تعيد هذه الدوال معلومات حول ملف، في المخزن المؤقت المشار إليه بـ statbuf. لا تتطلب أذونات على الملف نفسه، ولكن—في حالة stat() و fstatat() و lstat()—يتطلب إذن تنفيذ (بحث) على جميع الأدلة في path التي تؤدي إلى الملف.

stat() و fstatat() تسترجعان معلومات حول الملف المشار إليه بـ path؛ الاختلافات لـ fstatat() موصوفة أدناه.

lstat() مطابق لـ stat()، باستثناء أنه إذا كان path رابطًا رمزيًا، فإنه يعيد معلومات حول الرابط نفسه، وليس الملف الذي يشير إليه الرابط.

fstat() مطابق لـ stat()، باستثناء أن الملف الذي سيُسترجع معلومات عنه يُحدد بواسطة واصف الملف fd.

  هيكل stat
تعيد جميع استدعاءات النظام هذه هيكل stat (انظر stat(3type)).

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

  fstatat()
استدعاء النظام fstatat() هو واجهة أكثر عمومية للوصول إلى معلومات الملف والتي لا تزال قادرة على توفير سلوك كل من stat() و lstat() و fstat() بدقة.

إذا كان path نسبيًا، فإنه يُفسر بالنسبة للدليل المشار إليه بواسطة واصف الملف dirfd (بدلاً من دليل العمل الحالي للمستدعِي، كما تفعل stat() و lstat() لاسم مسار نسبي).

إذا كان path نسبيًا و dirfd هو القيمة الخاصة AT_FDCWD، فإن path يُفسر بالنسبة لدليل العمل الحالي للمستدعِي (مثل stat() و lstat()).

إذا كان المسار path مطلقاً، فُيتجاهل dirfd.

يمكن أن تكون flags إما 0، أو تتضمن علماً واحداً أو أكثر من الأعلام التالية مجمعة بـ OR:

AT_EMPTY_PATH (منذ لينكس 2.6.39)
    إذا كان path سلسلة فارغة (أو NULL، منذ Linux 6.11) فسيُعمل على الملف المشار إليه بـ dirfd (والذي قد يكون قد وُصل إليه باستخدام علم open(2) O_PATH). في هذه الحالة، يمكن أن يشير dirfd إلى أي نوع من الملفات، وليس فقط دليل، وسلوك fstatat() مشابه لسلوك fstat(). إذا كان dirfd هو AT_FDCWD، فإن الاستدعاء يعمل على دليل العمل الحالي. هذا العلم خاص بـ Linux؛ عرّف _GNU_SOURCE للحصول على تعريفه.

AT_NO_AUTOMOUNT (منذ Linux 2.6.38)
    لا تَقُم بالوصل الآلي للمكون الطرفي ("basename") لـ path. منذ Linux 3.1 يُتجاهل هذا العلم. ومنذ Linux 4.11 يكون هذا العلم ضمنياً.

AT_SYMLINK_NOFOLLOW
    إذا كان path رابطاً رمزياً، فلا تقم بفك الإشارة إليه: بل أعد معلومات حول الرابط نفسه، مثل lstat(). (بشكل مبدئي، يقوم fstatat() بفك إشارة الروابط الرمزية، مثل stat().)

انظر openat(2) لشرح الحاجة إلى fstatat().

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

الأخطاء

EACCES
    رُفض إذن البحث لأحد الأدلة في بادئة مسار path. (انظر أيضًا path_resolution(7).)

EBADF
    fd ليس واصف ملف مفتوحًا صالحًا.

EBADF
    (fstatat()) path نسبي لكن dirfd ليس AT_FDCWD ولا واصف ملف صالح.

EFAULT
    عنوان سيء.

EINVAL
    (fstatat()) عُلم غير صالح محدد في flags.

ELOOP
    صُودف عدد كبير جداً من الروابط الرمزية أثناء اجتياز المسار.

ENAMETOOLONG
    المسار path طويل جداً.

ENOENT
    أحد مكونات path غير موجود أو أنه وصلة رمزية معلقة.

ENOENT
    path سلسلة فارغة ولم يُحدد AT_EMPTY_PATH في flags.

ENOMEM
    نفاد الذاكرة (أي ذاكرة نواة الحاسوب).

ENOTDIR
    أحد مكونات بادئة المسار لـ path ليس دليلاً.

ENOTDIR
    (fstatat()) path نسبي و dirfd هو واصف ملف يشير إلى ملف غير دليل.

EOVERFLOW
    يشير path أو fd إلى ملف لا يمكن تمثيل حجمه أو رقم inode أو عدد الكتل فيه في الأنواع off_t أو ino_t أو blkcnt_t على التوالي. يمكن أن يحدث هذا الخطأ عندما، على سبيل المثال، يستدعي تطبيق جُمّع على منصة 32 بت بدون -D_FILE_OFFSET_BITS=64 الدالة stat() على ملف يتجاوز حجمه (1<<31)-1 بايت.

المعايير
POSIX.1-2024.

التاريخ

stat()
fstat()
lstat()
    SVr4، 4.3BSD، POSIX.1-2001.

fstatat()
    POSIX.1-2008. لينكس 2.6.16،‏ glibc 2.4.

وفقًا لـ POSIX.1-2001، يجب على lstat() عند استدعائه على وصلة رمزية أن يرجع معلومات صالحة فقط في الحقل st_size ونوع الملف في الحقل st_mode من بنية stat. شددت المواصفة POSIX.1-2008 هذه المتطلبات، حيث ألزمت lstat() بإرجاع معلومات صالحة في جميع الحقول باستثناء بتات الوضع (mode bits) في st_mode.

قد يكون استخدام الحقلين st_blocks و st_blksize أقل قابلية للنقل. (أُدخل هذان الحقلان في BSD. ويختلف تفسيرهما بين الأنظمة، وربما يختلفان في النظام الواحد عند وجود عمليات وصل NFS.)

  الاختلافات بين مكتبة C والنواة
بمرور الوقت، أدت الزيادات في حجم بنية stat إلى ظهور ثلاث نسخ متتالية من stat(): وهي sys_stat() (الموضع __NR_oldstat)، و sys_newstat() (الموضع __NR_stat)، و sys_stat64() (الموضع __NR_stat64) على المنصات ذات 32-بت مثل i386. كانت النسختان الأوليان موجودتين بالفعل في لينكس 1.0 (وإن كانا بأسماء مختلفة)؛ أما الأخيرة فقد أُضيفت في لينكس 2.4. تنطبق ملاحظات مماثلة على fstat() و lstat().

نسخ بنية stat الداخلية في النواة التي تتعامل معها النسخ المختلفة هي على التوالي:

__old_kernel_stat
    البنية الأصلية، بحقول ضيقة نوعًا ما، وبدون حشو (padding).

stat
    حقل st_ino أكبر مع إضافة حشو إلى أجزاء مختلفة من البنية للسماح بالتوسع المستقبلي.

stat64
    حقل st_ino أكبر، وحقول st_uid و st_gid أكبر لاستيعاب توسعة لينكس-2.4 لـ UIDs و GIDs إلى 32 بت، وحقول أخرى متنوعة مُوسعة مع حشو إضافي في البنية. (استُنفدت بايتات الحشو المختلفة في نهاية المطاف في لينكس 2.6، مع ظهور معرفات الأجهزة (device IDs) ذات 32 بت ومكونات النانو ثانية لحقول الطوابع الزمنية.)

تخفي دالة الغلاف stat() في مكتبة glibc هذه التفاصيل عن التطبيقات، حيث تستدعي أحدث نسخة من استدعاء النظام الذي توفره النواة، وتُعيد حزم المعلومات المُرجعة إذا لزم الأمر للبرمجيات الثنائية القديمة.

على الأنظمة الحديثة ذات 64-بت، الأمر أبسط: يوجد استدعاء نظام stat() واحد وتتعامل النواة مع بنية stat تحتوي على حقول ذات أحجام كافية.

استدعاء النظام الأساسي الذي تستخدمه دالة الغلاف fstatat() في glibc يُسمى في الواقع fstatat64() أو newfstatat() في بعض المعماريات.

أمثلة
يستدعي البرنامج التالي lstat() ويعرض حقولاً مختارة في هيكل stat المُعاد.

    #include <stdint.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <sys/stat.h>
    #include <sys/sysmacros.h>
    #include <time.h>

    int
    main(int argc, char *argv[])
    {
        struct stat sb;

        if (argc != 2) {
            fprintf(stderr, "Usage: %s <path>\n", argv[0]);
            exit(EXIT_FAILURE);
        }

        if (lstat(argv[1], &sb) == -1) {
            perror("lstat");
            exit(EXIT_FAILURE);
        }

        printf("معرف الجهاز الحاوي:  [%x,%x]\n",
               major(sb.st_dev),
               minor(sb.st_dev));

        printf("نوع الملف:                ");

        switch (sb.st_mode & S_IFMT) {
        case S_IFBLK:  printf("جهاز كتلي\n");            break;
        case S_IFCHR:  printf("جهاز محرفي\n");        break;
        case S_IFDIR:  printf("دليل\n");               break;
        case S_IFIFO:  printf("FIFO/أنبوب\n");               break;
        case S_IFLNK:  printf("وصلة رمزية\n");                 break;
        case S_IFREG:  printf("ملف عادي\n");            break;
        case S_IFSOCK: printf("مقبس\n");                  break;
        default:       printf("غير معروف؟\n");                break;
        }

        printf("رقم الآي-نود:            %ju\n", (uintmax_t) sb.st_ino);

        printf("الوضع:                     %jo (ثماني)\n",
               (uintmax_t) sb.st_mode);

        printf("عدد الوصلات:               %ju\n", (uintmax_t) sb.st_nlink);
        printf("الملكية:                UID=%ju   GID=%ju\n",
               (uintmax_t) sb.st_uid, (uintmax_t) sb.st_gid);

        printf("حجم كتلة الإدخال/الإخراج المفضل: %jd بايت\n",
               (intmax_t) sb.st_blksize);
        printf("حجم الملف:                %jd بايت\n",
               (intmax_t) sb.st_size);
        printf("الكتل المخصصة:         %jd\n",
               (intmax_t) sb.st_blocks);

        printf("آخر تغيير للحالة:       %s", ctime(&sb.st_ctime));
        printf("آخر وصول للملف:         %s", ctime(&sb.st_atime));
        printf("آخر تعديل للملف:   %s", ctime(&sb.st_mtime));

        exit(EXIT_SUCCESS);
    }

انظر أيضًا
ls(1)، stat(1)، access(2)، chmod(2)، chown(2)، readlink(2)، statx(2)، utime(2)، stat(3type)، capabilities(7)، inode(7)، symlink(7)

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

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 (https://www.gnu.org/licenses/gpl-3.0.html) أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

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