capget(2)

الاسم
capget, capset - ضبط/جلب قدرات الخيوط

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

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

int syscall(SYS_capget, cap_user_header_t hdrp,
            cap_user_data_t datap);
int syscall(SYS_capset, cap_user_header_t hdrp,
            const cap_user_data_t datap);

ملاحظة: لا توفر glibc أغلفة لنداءات النظام هذه، مما يستلزم استخدام syscall(2).

الوصف
استدعاءات النظام هاتان هما الواجهة الخام للنواة لجلب وضبط قدرات الخيوط. ليست هذه الاستدعاءات خاصة بلينكس فحسب، بل إن واجهة برمجة النواة عرضة للتغيير واستخدام هذه الاستدعاءات (خاصة تنسيق أنواع cap_user_*_t) يخضع للتوسع مع كل مراجعة للنواة، لكن البرامج القديمة ستستمر في العمل.

الواجهات المحمولة هي cap_set_proc(3) و cap_get_proc(3); إذا أمكن، ينبغي استخدام تلك الواجهات في التطبيقات; انظر الملاحظات.

  التفاصيل الحالية
الآن بعد أن حُذرت، إليك بعض تفاصيل النواة الحالية. تُعرف الهياكل على النحو التالي.

    #define _LINUX_CAPABILITY_VERSION_1  0x19980330
    #define _LINUX_CAPABILITY_U32S_1     1

            /* V2 added in Linux 2.6.25; deprecated */
    #define _LINUX_CAPABILITY_VERSION_2  0x20071026
    #define _LINUX_CAPABILITY_U32S_2     2

            /* V3 added in Linux 2.6.26 */
    #define _LINUX_CAPABILITY_VERSION_3  0x20080522
    #define _LINUX_CAPABILITY_U32S_3     2

    typedef struct __user_cap_header_struct {
       __u32 version;
       int pid;
    } *cap_user_header_t;

    typedef struct __user_cap_data_struct {
       __u32 effective;
       __u32 permitted;
       __u32 inheritable;
    } *cap_user_data_t;

الحقول effective و permitted و inheritable هي أقنعة بت للقدرات المعرفة في capabilities(7). لاحظ أن قيم CAP_* هي فهارس بت وتحتاج إلى إزاحة بت قبل إجراء عملية OR في حقول البت. لتعريف الهياكل لتمريرها إلى استدعاء النظام، عليك استخدام أسماء struct __user_cap_header_struct و struct __user_cap_data_struct لأن التعريفات بالنوع هي مؤشرات فقط.

النوى قبل لينكس 2.6.25 تفضل قدرات 32-بت مع الإصدار _LINUX_CAPABILITY_VERSION_1. أضاف لينكس 2.6.25 مجموعات قدرات 64-بت، مع الإصدار _LINUX_CAPABILITY_VERSION_2. لكن كان هناك خلل في واجهة برمجة التطبيقات، وأضاف لينكس 2.6.26 _LINUX_CAPABILITY_VERSION_3 لإصلاح المشكلة.

لاحظ أن قدرات 64-بت تستخدم datap[0] و datap[1]، بينما قدرات 32-بت تستخدم datap[0] فقط.

على النوى التي تدعم قدرات الملفات (دعم قدرات VFS)، تتصرف استدعاءات النظام هذه بشكل مختلف قليلاً. أُضيف هذا الدعم كخيار في لينكس 2.6.24، وأصبح ثابتًا (غير اختياري) في لينكس 2.6.33.

لاستدعاءات capget()، يمكن استكشاف قدرات أي عملية بتحديد معرف العملية الخاص بها بقيمة حقل hdrp->pid.

للتفاصيل حول البيانات، انظر capabilities(7).

  مع دعم قدرات VFS
تستخدم قدرات VFS سمة موسعة للملف (انظر xattr(7)) للسماح بإرفاق القدرات بالملفات القابلة للتنفيذ. يُهمل نموذج الامتياز هذا دعم النواة لعملية واحدة تضبط قدرات أخرى بشكل غير متزامن. أي، على النوى التي لديها دعم قدرات VFS، عند استدعاء capset()، القيم المسموح بها فقط لـ hdrp->pid هي 0 أو، بشكل مكافئ، القيمة التي يُرجعها gettid(2).

  بدون دعم قدرات VFS
على النوى الأقدم التي لا توفر دعم قدرات VFS، يمكن لـ capset()، إذا كان لدى المستدعي قدرة CAP_SETPCAP، أن يُستخدم لتغيير ليس فقط قدرات المستدعي نفسه، بل أيضًا قدرات الخيوط الأخرى. يعمل الاستدعاء على قدرات الخيط المحدد بحقل pid من hdrp عندما يكون غير صفري، أو على قدرات خيط الاستدعاء إذا كان pid يساوي 0. إذا كان pid يشير إلى عملية أحادية الخيط، فيمكن تحديد pid كمعرف عملية تقليدي; العمل على خيط من عملية متعددة الخيوط يتطلب معرف خيط من النوع الذي يُرجعه gettid(2). لـ capset()، يمكن أن يكون pid أيضًا: -1، بمعنى تنفيذ التغيير على جميع الخيوط باستثناء المستدعي و init(1); أو قيمة أقل من -1، وفي هذه الحالة يُطبق التغيير على جميع أعضاء مجموعة العملية التي معرفها هو -pid.

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

تفشل الاستدعاءات مع الخطأ EINVAL، وتضبط حقل version من hdrp إلى القيمة المفضلة للنواة لـ _LINUX_CAPABILITY_VERSION_? عند تحديد قيمة version غير مدعومة. بهذه الطريقة، يمكن استكشاف ما هي المراجعة المفضلة الحالية للقدرات.

الأخطاء

EFAULT
    عنوان ذاكرة سيئ. يجب ألا يكون hdrp NULL. يمكن أن يكون datap NULL فقط عندما يحاول المستخدم تحديد تنسيق إصدار القدرات المفضل الذي تدعمه النواة.

EINVAL
    أحد الوسائط كان غير صالح.

EPERM
    جرت محاولة لإضافة قدرة إلى المجموعة المسموح بها، أو لضبط قدرة في المجموعة الفعالة غير موجودة في المجموعة المسموح بها.

EPERM
    جرت محاولة لإضافة قدرة إلى المجموعة القابلة للتوريث، وإما:

    •   تلك القدرة لم تكن في مجموعة الحدود للمستدعي; أو

    •   القدرة لم تكن في المجموعة المسموح بها للمستدعي وكان المستدعي يفتقر إلى قدرة CAP_SETPCAP في مجموعته الفعالة.

EPERM
    حاول المستدعي استخدام capset() لتعديل قدرات خيط غير نفسه، لكنه افتقر إلى الامتياز الكافي. بالنسبة للنوى التي تدعم قدرات VFS، هذا غير مسموح به أبدًا. بالنسبة للنوى التي تفتقر إلى دعم VFS، قدرة CAP_SETPCAP مطلوبة. (خطأ في النوى قبل لينكس 2.6.11 يعني أن هذا الخطأ يمكن أن يحدث أيضًا إذا حاول خيط بدون هذه القدرة تغيير قدراته الخاصة بتحديد حقل pid كقيمة غير صفرية (أي القيمة التي يُرجعها getpid(2)) بدلاً من 0.)

ESRCH
    لا يوجد خيط كهذا.

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

ملاحظات
الواجهة المحمولة لوظائف استعلام وضبط القدرات تُوفرها مكتبة libcap وهي متاحة هنا:
http://git.kernel.org/cgit/linux/kernel/git/morgan/libcap.git

انظر أيضًا
clone(2)، gettid(2)، capabilities(7)

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

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

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