scandir(3)

الاسم
scandir, scandirat, alphasort, versionsort - مسح دليل للبحث عن مدخلات مطابقة

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

موجز
#include <dirent.h>

int scandir(const char *restrict dirp,
            struct dirent ***restrict namelist,
            typeof(int (const struct dirent *)) *filter,
typeof(int (const struct dirent **, const struct dirent **))
                *compar);

int alphasort(const struct dirent **a, const struct dirent **b);
int versionsort(const struct dirent **a, const struct dirent **b);

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

int scandirat(int dirfd, const char *restrict dirp,
            struct dirent ***restrict namelist,
            typeof(int (const struct dirent *)) *filter,
typeof(int (const struct dirent **, const struct dirent **))
                *compar);

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

scandir(), alphasort():
    /* منذ glibc 2.10: */ _POSIX_C_SOURCE >= 200809L
        || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE

versionsort():
    _GNU_SOURCE

scandirat():
    _GNU_SOURCE

الوصف
تفحص الدالة scandir() الدليل dirp، وتستدعي filter() على كل مدخل دليل. تُخزَّن المدخلات التي تُرجع filter() قيمة غير صفرية في سلاسل محارف مخصصة عبر malloc(3)، وتُرتَّب باستخدام qsort(3) مع دالة المقارنة compar()، وتُجمَع في مصفوفة namelist المخصصة عبر malloc(3). إذا كان filter NULL، تُحدد جميع المدخلات.

يمكن استخدام الدالتين alphasort() و versionsort() كدالة مقارنة compar(). ترتب الأولى مدخلات الدليل باستخدام strcoll(3)، والثانية باستخدام strverscmp(3) على السلاسل (*a)->d_name و (*b)->d_name.

  scandirat()
تعمل الدالة scandirat() بنفس طريقة scandir() تمامًا، باستثناء الاختلافات الموصوفة هنا.

إذا كان dirp نسبيًا، فسيُفسَّر بالنسبة إلى الدليل المشار إليه بواصف الملف dirfd (بدلاً من دليل العمل الحالي للعملية المستدعية، كما تفعل scandir() لمسار نسبي).

إذا كان dirp نسبيًا و dirfd هو القيمة الخاصة AT_FDCWD، فسيُفسَّر dirp بالنسبة إلى دليل العمل الحالي للعملية المستدعية (مثل scandir()).

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

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

قيمة الإرجاع
تُرجع الدالة scandir() عدد مدخلات الدليل المحددة. عند حدوث خطأ، تُرجع -1، مع تعيين errno للإشارة إلى الخطأ.

تُرجع الدالتان alphasort() و versionsort() عددًا صحيحًا أقل من، أو يساوي، أو أكبر من الصفر إذا كانت الوسيطة الأولى تُعتبر على التوالي أقل من، أو تساوي، أو أكبر من الثانية.

الأخطاء

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

ENOENT
    المسار في dirp غير موجود.

ENOMEM
    الذاكرة غير كافية لإكمال العملية.

ENOTDIR
    المسار في dirp ليس دليلاً.

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

السمات
للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر attributes(7).
الواجهة | السمة | القيمة
scandir()، scandirat() | سلامة الخيوط | MT-Safe
alphasort()، versionsort() | سلامة الخيوط | المنطقة (locale) آمنة لتعدد المسالك (MT-Safe)

المعايير

alphasort()
scandir()
    POSIX.1-2008.

versionsort()
scandirat()
    GNU.

التاريخ

alphasort()
scandir()
    4.3BSD، POSIX.1-2008.

versionsort()
    glibc 2.1.

scandirat()
    glibc 2.15.

ملاحظات
منذ glibc 2.1، تستدعي alphasort() الدالة strcoll(3)؛ سابقًا كانت تستخدم strcmp(3).

قبل glibc 2.10، كانت الوسيطتان للدالتين alphasort() و versionsort() مكتوبتين كـ const void *. عندما تم توحيد alphasort() في POSIX.1-2008، تم تحديد نوع الوسيطة كـ const struct dirent ** الآمن من حيث النوع، وغيّر glibc 2.10 تعريف alphasort() (و versionsort() غير القياسية) لمطابقة المعيار.

أمثلة
يطبع البرنامج أدناه قائمة بالملفات في الدليل الحالي بترتيب عكسي.

  مصدر البرنامج
    #define _DEFAULT_SOURCE
    #include <dirent.h>
    #include <stdio.h>
    #include <stdlib.h>

    int
    main(void)
    {
        struct dirent **namelist;
        int n;

        n = scandir(".", &namelist, NULL, alphasort);
        if (n == -1) {
            perror("scandir");
            exit(EXIT_FAILURE);
        }

        while (n--) {
            printf("%s\n", namelist[n]->d_name);
            free(namelist[n]);
        }
        free(namelist);

        exit(EXIT_SUCCESS);
    }

انظر أيضًا
closedir(3)، fnmatch(3)، opendir(3)، readdir(3)، rewinddir(3)، seekdir(3)، strcmp(3)، strcoll(3)، strverscmp(3)، telldir(3)

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

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

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