getdents(2)

الاسم
getdents, getdents64 - الحصول على مدخلات الدليل

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

موجز
#include <sys/syscall.h>      /* تعريف ثوابت SYS_* */
#include <unistd.h>

long syscall(SYS_getdents, unsigned int fd, struct linux_dirent *dirp,
             unsigned int count);

#define _GNU_SOURCE           /* See feature_test_macros(7) */
#include <dirent.h>

ssize_t getdents64(size_t count;
                   int fd, void dirp[count], size_t count);

ملاحظة: لا توفر glibc غلافًا لـ getdents()، مما يستلزم استخدام syscall(2).

ملاحظة: لا يوجد تعريف لـ struct linux_dirent في glibc؛ انظر NOTES.

الوصف
هذه ليست الواجهات التي تهمك. انظر إلى readdir(3) لواجهة مكتبة C المتوافقة مع POSIX.

  getdents()
يقرأ استدعاء النظام getdents() عدة بنى linux_dirent من الدليل المشار إليه بواصف الملف المفتوح fd إلى المخزن المؤقت المشار إليه بـ dirp. تحدد الوسيطة count حجم ذلك المخزن المؤقت.

يُصرح عن بنية linux_dirent كما يلي:

    struct linux_dirent {
        unsigned long  d_ino;     /* Inode number */
        unsigned long  d_off;     /* Not an offset; see below */
        unsigned short d_reclen;  /* Length of this linux_dirent */
        char           d_name[];  /* Filename (null-terminated) */
                          /* length is actually (d_reclen - 2 -
                             offsetof(struct linux_dirent, d_name)) */
        /*
        char           pad;       // Zero padding byte
        char           d_type;    // File type (only since Linux
                                  // 2.6.4); offset is (d_reclen - 1)
        */
    }

d_ino هو رقم عقدة (inode). d_off هو قيمة خاصة بنظام الملفات ليس لها معنى محدد لمساحة المستخدم، رغم أنها كانت في أنظمة الملفات القديمة المسافة من بداية الدليل إلى بداية linux_dirent التالي؛ انظر readdir(3). d_reclen هو حجم هذا linux_dirent بالكامل. d_name هو اسم ملف منتهي بقيمة فارغة.

d_type هو بايت في نهاية البنية يشير إلى نوع الملف. يحتوي على إحدى القيم التالية (المعرفة في <dirent.h>):

DT_BLK
    هذا جهاز كتلي.

DT_CHR
    هذا جهاز محرفي.

DT_DIR
    هذا دليل.

DT_FIFO
    هذا أنبوب مسمى (FIFO).

DT_LNK
    هذا رابط رمزي.

DT_REG
    هذا ملف عادي.

DT_SOCK
    هذا مقبس نطاق UNIX.

DT_UNKNOWN
    نوع الملف غير معروف.

حقل d_type مطبق منذ Linux 2.6.4. يشغل مساحة كانت سابقًا بايت حشو مملوء بصفر في بنية linux_dirent. وبالتالي، على النوى حتى Linux 2.6.3 وما يشملها، تؤدي محاولة الوصول إلى هذا الحقل دائمًا إلى القيمة 0 (DT_UNKNOWN).

حاليًا، بعض أنظمة الملفات فقط (من بينها: Btrfs، و ext2، و ext3، و ext4) لديها دعم كامل لإعادة نوع الملف في d_type. يجب على جميع التطبيقات التعامل بشكل صحيح مع عودة DT_UNKNOWN.

  getdents64()
لم يعالج استدعاء النظام الأصلي getdents() أنظمة الملفات الكبيرة وإزاحات الملفات الكبيرة. وبالتالي، أضاف Linux 2.4 getdents64()، بأنواع أوسع لحقلي d_ino و d_off. بالإضافة إلى ذلك، يدعم getdents64() حقل d_type صريح.

استدعاء النظام getdents64() يشبه getdents()، باستثناء أن وسيطته الثانية هي مؤشر إلى مخزن مؤقت يحتوي على بنى من النوع التالي:

    struct linux_dirent64 {
        ino64_t        d_ino;    /* 64-bit inode number */
        off64_t        d_off;    /* Not an offset; see getdents() */
        unsigned short d_reclen; /* Size of this dirent */
        unsigned char  d_type;   /* File type */
        char           d_name[]; /* Filename (null-terminated) */
    };

قيمة الإرجاع
عند النجاح، يُعاد عدد البايتات المقروءة. عند نهاية الدليل، تُعاد 0. عند الخطأ، يُعاد -1، ويُضبط errno للإشارة إلى الخطأ.

الأخطاء

EBADF
    وصف ملف (file descriptor) غير صالح fd.

EFAULT
    تشير المعطيات (arguments) إلى خارج فضاء عناوين العملية المستدعية.

EINVAL
    مخزن النتائج المؤقت صغير جدًا.

ENOENT
    لا يوجد دليل كهذا.

ENOTDIR
    واصف الملف لا يشير إلى مجلد.

المعايير
لا شيء.

التاريخ

getdents()
    SVr4.

getdents64()
    glibc 2.30.

ملاحظات
لا توفر glibc غلافًا لـ getdents()؛ استدع getdents() باستخدام syscall(2). في هذه الحالة، ستحتاج إلى تعريف بنية linux_dirent بنفسك.

يقبل استدعاء النظام getdents64() وسيطة unsigned int count ويفترض أن count لا يتجاوز INT_MAX. تضبط دالة الغلاف في glibc count إلى INT_MAX إذا تجاوز INT_MAX. تعرّف glibc بنية dirent64، والتي تشبه linux_dirent64 ولكن مع d_name بحجم 256 بايت.

ربما، تريد استخدام readdir(3) بدلاً من استدعاءات النظام هذه.

تحل هذه الاستدعاءات محل readdir(2).

أمثلة
يوضح البرنامج أدناه استخدام getdents(). يُظهر الإخراج التالي مثالاً لما نراه عند تشغيل هذا البرنامج على دليل ext2:

    $ ./a.out /testfs/
    --------------- nread=120 ---------------
    inode#    file type  d_reclen  d_off   d_name
           2  directory    16         12  .
           2  directory    16         24  ..
          11  directory    24         44  lost+found
          12  regular      16         56  a
      228929  directory    16         68  sub
       16353  directory    16         80  sub2
      130817  directory    16       4096  sub3

  مصدر البرنامج
    #define _GNU_SOURCE
    #include <dirent.h>     /* Defines DT_* constants */
    #include <err.h>
    #include <fcntl.h>
    #include <stdint.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <sys/syscall.h>
    #include <sys/types.h>
    #include <unistd.h>

    struct linux_dirent {
        unsigned long  d_ino;
        off_t          d_off;
        unsigned short d_reclen;
        char           d_name[];
    };

    #define BUF_SIZE 1024

    int
    main(int argc, char *argv[])
    {
        int                  fd;
        char                 d_type;
        char                 buf[BUF_SIZE];
        long                 nread;
        struct linux_dirent  *d;

        fd = open(argc > 1 ? argv[1] : ".", O_RDONLY | O_DIRECTORY);
        if (fd == -1)
            err(EXIT_FAILURE, "open");

        for (;;) {
            nread = syscall(SYS_getdents, fd, buf, BUF_SIZE);
            if (nread == -1)
                err(EXIT_FAILURE, "getdents");

            if (nread == 0)
                break;

            printf("--------------- nread=%ld ---------------\n", nread);
            printf("inode#    file type  d_reclen  d_off   d_name\n");
            for (size_t bpos = 0; bpos < nread;) {
                d = (struct linux_dirent *) (buf + bpos);
                printf("%8lu  ", d->d_ino);
                d_type = *(buf + bpos + d->d_reclen - 1);
                printf("%-10s ", (d_type == DT_REG) ?  "regular" :
                                 (d_type == DT_DIR) ?  "directory" :
                                 (d_type == DT_FIFO) ? "FIFO" :
                                 (d_type == DT_SOCK) ? "socket" :
                                 (d_type == DT_LNK) ?  "symlink" :
                                 (d_type == DT_BLK) ?  "block dev" :
                                 (d_type == DT_CHR) ?  "char dev" : "???");
                printf("%4d %10jd  %s\n", d->d_reclen,
                       (intmax_t) d->d_off, d->d_name);
                bpos += d->d_reclen;
            }
        }

        exit(EXIT_SUCCESS);
    }

انظر أيضًا
readdir(2), readdir(3), inode(7)

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

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

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