الاسم

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

#include <sys/types.h>
#include <pwd.h>

struct passwd *getpwnam(const char *name);
struct passwd *getpwuid(uid_t uid);

int getpwnam_r(size_t size;
               const char *restrict name,
               struct passwd *restrict pwd,
               char buf[restrict size], size_t size,
               struct passwd **restrict result);
int getpwuid_r(size_t size;
               uid_t uid,
               struct passwd *restrict pwd,
               char buf[restrict size], size_t size,
               struct passwd **restrict result);

getpwnam_r(), getpwuid_r():

    _POSIX_C_SOURCE
        || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE

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

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

عُرف هيكل passwd في <pwd.h> كالتالي:

struct passwd {
    char   *pw_name;       /* اسم المستخدم */
    char   *pw_passwd;     /* كلمة سر المستخدم */
    uid_t   pw_uid;        /* معرف المستخدم */
    gid_t   pw_gid;        /* معرف المجموعة */
    char   *pw_gecos;      /* معلومات المستخدم */
    char   *pw_dir;        /* دليل المنزل */
    char   *pw_shell;      /* برنامج الصدفة */
};

انظر passwd(5) لمزيد من المعلومات حول هذه الحقول.

تحصل الدالتان getpwnam_r() وgetpwuid_r() على نفس المعلومات مثل getpwnam() وgetpwuid()، لكن تخزنان بنية passwd المسترجعة في المساحة المشار إليها بواسطة pwd. تُخزن حقول السلاسل المحارف المشار إليها بواسطة أعضاء بنية passwd في المخزن المؤقت buf بحجم size. يُخزن مؤشر إلى النتيجة (في حالة النجاح) أو NULL (في حالة عدم العثور على مدخل أو حدوث خطأ) في *result.

الاستدعاء

sysconf(_SC_GETPW_R_SIZE_MAX)

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

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

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

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

0 أو ENOENT أو ESRCH أو EBADF أو EPERM أو ...

لم يُعثر على name أو uid المعطى.

EINTR

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

EIO

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

EMFILE

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

ENFILE

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

ENOMEM

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

ERANGE

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

قاعدة بيانات كلمة السر للمستخدم تشير غالبًا إلى /etc/passwd. لكن، مع الأنظمة الحديثة تشير أيضًا إلى قواعد بيانات شبكية واسعة باستخدام NIS و LDAP وملفات محلية أخرى كما هو مُهيَّأ في /etc/nsswitch.conf.

/etc/passwd

ملف قاعدة بيانات كلمات السر المحلية

/etc/nsswitch.conf

قواعد بيانات النظام وملف تهيئة مبدّل خدمة الأسماء

للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر attributes(7).

لم يُحدد حقل pw_gecos في POSIX، ولكنه موجود في معظم التنفيذات.

POSIX.1-2008.

POSIX.1-2001، SVr4، 4.3BSD.

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

يحتوي الحقل pw_dir على اسم دليل العمل المبدئي للمستخدم. تستخدم برامج تسجيل الدخول قيمة هذا الحقل لتهيئة متغير البيئة HOME لصدفة تسجيل الدخول. يجب على التطبيق الذي يريد تحديد دليل المستخدم الرئيسي أن يفحص قيمة HOME (بدلاً من القيمة getpwuid(getuid())->pw_dir) لأن هذا يسمح للمستخدم بتعديل مفهومه عن "الدليل الرئيسي" أثناء جلسة تسجيل الدخول. لتحديد الدليل الرئيسي (المبدئي) لمستخدم آخر، من الضروري استخدام getpwnam("username")->pw_dir أو ما شابه.

البرنامج أدناه يوضح استخدام getpwnam_r() لإيجاد اسم المستخدم الكامل ومعرّف المستخدم لاسم المستخدم المُقدَّم كوسيط سطر أوامر.

#include <errno.h>
#include <pwd.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
int
main(int argc, char *argv[])
{
    struct passwd pwd;
    struct passwd *result;
    char *buf;
    long bufsize;
    int s;
    if (argc != 2) {
        fprintf(stderr, "Usage: %s username\n", argv[0]);
        exit(EXIT_FAILURE);
    }
    bufsize = sysconf(_SC_GETPW_R_SIZE_MAX);
    if (bufsize == -1)          /* Value was indeterminate */
        bufsize = 16384;        /* Should be more than enough */
    buf = malloc(bufsize);
    if (buf == NULL) {
        perror("malloc");
        exit(EXIT_FAILURE);
    }
    s = getpwnam_r(argv[1], &pwd, buf, bufsize, &result);
    if (result == NULL) {
        if (s == 0)
            printf("Not found\n");
        else {
            errno = s;
            perror("getpwnam_r");
        }
        exit(EXIT_FAILURE);
    }
    printf("Name: %s; UID: %jd\n", pwd.pw_gecos,
           (intmax_t) pwd.pw_uid);
    exit(EXIT_SUCCESS);
}

endpwent(3), fgetpwent(3), getgrnam(3), getpw(3), getpwent(3), getspnam(3), putpwent(3), setpwent(3), nsswitch.conf(5), passwd(5)

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

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

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