listxattr(2)

الاسم
listxattr, llistxattr, flistxattr - سرد أسماء السمات الموسعة

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

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

ssize_t listxattr(const char *path, char *_Nullable list, size_t size);
ssize_t llistxattr(const char *path, char *_Nullable list, size_t size);
ssize_t flistxattr(int fd, char *_Nullable list, size_t size);

الوصف
السمات الممتدة هي أزواج الاسم:القيمة المرتبطة بالفهارس (الملفات، المجلدات، الروابط الرمزية، إلخ). وهي امتدادات للسمات العادية المرتبطة بكافة الفهارس في النظام (أي بيانات stat(2)). يمكن العثور على نظرة شاملة لمفاهيم السمات الممتدة في xattr(7).

تسترد الدالة listxattr() قائمة أسماء السمات الموسعة المرتبطة بالمسار path المعطى في نظام الملفات. توضع القائمة المستردة في list، وهي مخزن مؤقت مخصص من قبل المستدعي ويُحدد حجمه (بالبايت) في الوسيط size. القائمة هي مجموعة من الأسماء (منتهية بقيمة خالية) واحدة تلو الأخرى. قد تُحذف من القائمة أسماء السمات الموسعة التي لا تملك العملية المستدعية صلاحية الوصول إليها. يُعاد طول قائمة أسماء السمات list.

تطابق llistxattr() الدالة listxattr()، باستثناء حالة الارتباط الرمزي، حيث تُسترجع قائمة أسماء السمات الموسعة المرتبطة بالارتباط نفسه، وليس الملف الذي يشير إليه.

تطابق flistxattr() الدالة listxattr()، لكن يُستجوب الملف المفتوح المشار إليه بواسطة fd (كما تُعيده open(2)) بدلاً من path.

السمة الموسعة المفردة name هي سلسلة منتهية بقيمة خالية. يتضمن الاسم بادئة نطاق أسماء؛ قد توجد عدة نطاقات أسماء منفصلة مرتبطة بعقدة فهرسة فردية.

إذا حُدد size بقيمة صفر، تُعيد هذه الاستدعاءات الحجم الحالي لقائمة أسماء السمات الموسعة (وتترك list دون تغيير). يمكن استخدام هذا لتحديد حجم المخزن المؤقت الذي ينبغي توفيره في استدعاء لاحق. (لكن، ضع في اعتبارك أن هناك احتمالاً أن تتغير مجموعة السمات الموسعة بين الاستدعاءين، لذا لا يزال من الضروري التحقق من حالة الإرجاع من الاستدعاء الثاني.)

  مثال
تُعاد قائمة الأسماء على شكل مصفوفة غير مرتبة من سلاسل الأحرف المنتهية بـ null (يُفصل بين أسماء السمات بايتات null ('\0'))، على النحو التالي:

    user.name1\0system.name1\0user.name2\0

أنظمة الملفات التي تنفذ قوائم التحكم بالوصول POSIX باستخدام السمات الموسعة قد تُعيد قائمة list هكذا:

    system.posix_acl_access\0system.posix_acl_default\0

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

الأخطاء

E2BIG
    حجم قائمة أسماء السمات الموسعة أكبر من الحجم الأقصى المسموح به؛ لا يمكن استرجاع القائمة. قد يحدث هذا في أنظمة الملفات التي تدعم عدداً غير محدود من السمات الموسعة لكل ملف، مثل XFS على سبيل المثال. انظر الأخطاء.

ENOTSUP
    السمات الموسعة غير مدعومة من قبل نظام الملفات، أو أنها معطلة.

ERANGE
    حجم size للمخزن المؤقت list صغير جداً لاستيعاب النتيجة.

بالإضافة إلى ذلك، يمكن أن تحدث أيضًا الأخطاء الموثقة في stat(2).

المعايير
لينكس.

التاريخ
لينكس 2.4، glibc 2.3.

العلل
كما هو مذكور في xattr(7)، يفرض نظام VFS حدًا أقصى قدره 64 كيلوبايت لحجم قائمة أسماء السمات الموسعة التي تُرجعها الدالة listxattr(). وإذا تجاوز الحجم الإجمالي لأسماء السمات المرتبطة بملف ما هذا الحد، فلن يكون من الممكن بعد ذلك استرداد قائمة أسماء السمات.

أمثلة
يوضح البرنامج التالي استخدام listxattr() و getxattr(2). بالنسبة للملف الذي يُقدم اسم مساره كوسيط سطر أوامر، يسرد جميع سمات الملف الموسعة وقيمها.

لإبقاء الكود بسيطاً، يفترض البرنامج أن مفاتيح وقيم السمات ثابتة أثناء تنفيذ البرنامج. يجب أن يتوقع برنامج الإنتاج التغييرات أثناء تنفيذ البرنامج ويتعامل معها. على سبيل المثال، قد يزيد عدد البايتات المطلوبة لمفاتيح السمات بين الاستدعاءين لـ listxattr(). يمكن للتطبيق التعامل مع هذا الاحتمال باستخدام حلقة تعيد محاولة الاستدعاء (ربما حتى عدد أقصى محدد مسبقاً من المحاولات) مع مخزن مؤقت أكبر في كل مرة يفشل فيها مع الخطأ ERANGE. يمكن التعامل مع استدعاءات getxattr(2) بطريقة مماثلة.

سُجل المخرج التالي بإنشاء ملف أولاً، وتعيين بعض سمات الملف الموسعة، ثم سرد السمات باستخدام البرنامج المثال.

  مثال على الخرج
    $ touch /tmp/foo;
    $ setfattr -n user.fred -v chocolate /tmp/foo;
    $ setfattr -n user.frieda -v bar /tmp/foo;
    $ setfattr -n user.empty /tmp/foo;
    $ ./listxattr /tmp/foo;
    user.fred: chocolate
    user.frieda: bar
    user.empty: <no value>

  مصدر البرنامج (listxattr.c)
    #include <stdio.h>
    #include <stdlib.h>
    #include <string.h>
    #include <sys/xattr.h>

    int
    main(int argc, char *argv[])
    {
        char     *buf, *key, *val;
        ssize_t  buflen, keylen, vallen;

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

        /*
         * Determine the length of the buffer needed.
         */
        buflen = listxattr(argv[1], NULL, 0);
        if (buflen == -1) {
            perror("listxattr");
            exit(EXIT_FAILURE);
        }
        if (buflen == 0) {
            printf("%s has no attributes.\n", argv[1]);
            exit(EXIT_SUCCESS);
        }

        /*
         * Allocate the buffer.
         */
        buf = malloc(buflen);
        if (buf == NULL) {
            perror("malloc");
            exit(EXIT_FAILURE);
        }

        /*
         * Copy the list of attribute keys to the buffer.
         */
        buflen = listxattr(argv[1], buf, buflen);
        if (buflen == -1) {
            perror("listxattr");
            exit(EXIT_FAILURE);
        }

        /*
         * Loop over the list of zero terminated strings with the
         * attribute keys.  Use the remaining buffer length to determine
         * the end of the list.
         */
        key = buf;
        while (buflen > 0) {

            /*
             * Output attribute key.
             */
            printf("%s: ", key);

            /*
             * Determine length of the value.
             */
            vallen = getxattr(argv[1], key, NULL, 0);
            if (vallen == -1)
                perror("getxattr");

            if (vallen > 0) {

                /*
                 * Allocate value buffer.
                 * One extra byte is needed to append 0x00.
                 */
                val = malloc(vallen + 1);
                if (val == NULL) {
                    perror("malloc");
                    exit(EXIT_FAILURE);
                }

                /*
                 * Copy value to buffer.
                 */
                vallen = getxattr(argv[1], key, val, vallen);
                if (vallen == -1) {
                    perror("getxattr");
                } else {
                    /*
                     * Output attribute value.
                     */
                    val[vallen] = 0;
                    printf("%s", val);
                }

                free(val);
            } else if (vallen == 0) {
                printf("<no value>");
            }

            printf("\n");

            /*
             * Forward to next attribute key.
             */
            keylen = strlen(key) + 1;
            buflen -= keylen;
            key += keylen;
        }

        free(buf);
        exit(EXIT_SUCCESS);
    }

انظر أيضًا
getfattr(1), setfattr(1), getxattr(2), open(2), removexattr(2), setxattr(2), stat(2), symlink(7), xattr(7)

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

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

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