getgrnam(3)

الاسم
getgrnam, getgrnam_r, getgrgid, getgrgid_r - الحصول على مدخلة ملف المجموعة

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

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

struct group *getgrnam(const char *name);
struct group *getgrgid(gid_t gid);

int getgrnam_r(size_t size;
               const char *restrict name, struct group *restrict grp,
               char buf[restrict size], size_t size,
               struct group **restrict result);
int getgrgid_r(size_t size;
               gid_t gid, struct group *restrict grp,
               char buf[restrict size], size_t size,
               struct group **restrict result);

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

getgrnam_r(), getgrgid_r():
    _POSIX_C_SOURCE
        || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE

الوصف
ترجع الدالة getgrnam() مؤشرًا إلى بنية تحتوي على الحقول المفصولة للسجل في قاعدة بيانات المجموعة (مثل ملف المجموعة المحلي /etc/group، وNIS، وLDAP) الذي يطابق اسم المجموعة name.

ترجع الدالة getgrgid() مؤشرًا إلى بنية تحتوي على الحقول المفصولة للسجل في قاعدة بيانات المجموعة الذي يطابق معرف المجموعة gid.

عُرف هيكل group في <grp.h> كالتالي:

    struct group {
        char   *gr_name;        /* اسم المجموعة */
        char   *gr_passwd;      /* كلمة سر المجموعة */
        gid_t   gr_gid;         /* معرف المجموعة */
        char  **gr_mem;         /* مصفوفة منتهية بـ NULL من المؤشرات
                                   إلى أسماء أعضاء المجموعة */
    };

لمزيد من المعلومات حول حقول هذا الهيكل، راجع group(5).

تحصل الدالتان getgrnam_r() وgetgrgid_r() على نفس المعلومات مثل getgrnam() وgetgrgid()، لكن تخزنان بنية group المسترجعة في المساحة المشار إليها بواسطة grp. تُخزن حقول السلاسل المحارف المشار إليها بواسطة أعضاء بنية group في المخزن المؤقت buf بحجم size. يُخزن مؤشر إلى النتيجة (في حالة النجاح) أو NULL (في حالة عدم العثور على مدخل أو حدوث خطأ) في *result.

الاستدعاء

    sysconf(_SC_GETGR_R_SIZE_MAX)

يرجع إما -1، دون تغيير errno، أو حجمًا مقترحًا مبدئيًا لـ buf. (إذا كان هذا الحجم صغيرًا جدًا، يفشل الاستدعاء بـ ERANGE، وفي هذه الحالة يمكن للمستدعي (caller) المحاولة مرة أخرى بذاكرة وسيطة أكبر.)

قيمة الإرجاع
ترجع الدالتان getgrnam() وgetgrgid() مؤشرًا إلى بنية group، أو NULL إذا لم يُعثر على المدخل المطابق أو حدث خطأ. إذا حدث خطأ، يُضبط errno للإشارة إلى الخطأ. إذا أراد المرء التحقق من errno بعد الاستدعاء، فيجب ضبطه على الصفر قبل الاستدعاء.

قد يشير القيمة المرجعة إلى منطقة ثابتة، وقد تُستبدل باستدعاءات لاحقة لـ getgrent(3) أو getgrgid() أو getgrnam(). (لا تمرر المؤشر المرتجع إلى free(3).)

عند النجاح، ترجع getgrnam_r() وgetgrgid_r() صفرًا، وتضبط *result على grp. إذا لم يُعثر على سجل مجموعة مطابق، ترجع هاتان الدالتان 0 وتخزنان NULL في *result. في حالة الخطأ، يُرجع رقم خطأ، ويُخزن NULL في *result.

الأخطاء

0 أو ENOENT أو ESRCH أو EBADF أو EPERM أو ...
    لم يُعثر على name أو gid المعطى.

EINTR
    اُلتُقطت إشارة؛ انظر signal(7).

EIO خطأ إدخال/إخراج.

EMFILE
    وُصل إلى الحد الأقصى لواصفات الملفات المفتوحة لكل عملية.

ENFILE
    وُصل إلى الحد الأقصى لإجمالي عدد الملفات المفتوحة على مستوى النظام.

ENOMEM
    ذاكرة غير كافية لتخصيص بنية group.

ERANGE
    مساحة المخزن المؤقت المقدمة غير كافية.

الملفات

/etc/group
    ملف قاعدة بيانات المجموعات المحلية

السمات
للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر attributes(7).
الواجهة | السمة | القيمة
getgrnam() | سلامة الخيوط | MT-Unsafe race:grnam locale
getgrgid() | سلامة الخيوط | MT-Unsafe race:grgid locale
getgrnam_r(), getgrgid_r() | سلامة الخيوط | المنطقة (locale) آمنة لتعدد المسالك (MT-Safe)

الإصدارات
الصياغة المذكورة أعلاه تحت "القيمة المرجعة" مأخوذة من POSIX.1. لا تعتبر "عدم العثور" خطأ، وبالتالي لا تحدد القيمة التي قد يحملها errno في هذه الحالة. لكن هذا يجعل التعرف على الأخطاء مستحيلًا. قد يجادل المرء بأنه وفقًا لـ POSIX، يجب ترك errno دون تغيير إذا لم يُعثر على مدخل. تُظهر التجارب على أنظمة شبيهة بـ UNIX المختلفة أن العديد من القيم المختلفة تظهر في هذه الحالة: 0، ENOENT، EBADF، ESRCH، EWOULDBLOCK، EPERM، وربما أخرى.

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

التاريخ
POSIX.1-2001، SVr4، 4.3BSD.

انظر أيضًا
endgrent(3), fgetgrent(3), getgrent(3), getpwnam(3), setgrent(3), group(5)

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

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

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