getspnam(3)

الاسم
getspnam, getspnam_r, getspent, getspent_r, setspent, endspent, fgetspent, fgetspent_r, sgetspent, sgetspent_r, putspent, lckpwdf, ulckpwdf - الحصول على مدخل ملف كلمة السر الظلي

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

موجز
/* General shadow password file API */
#include <shadow.h>

struct spwd *getspnam(const char *name);
struct spwd *getspent(void);

void setspent(void);
void endspent(void);

struct spwd *fgetspent(FILE *stream);
struct spwd *sgetspent(const char *s);

int putspent(const struct spwd *p, FILE *stream);

int lckpwdf(void);
int ulckpwdf(void);

/* GNU extension */
#include <shadow.h>

int getspent_r(size_t size;
               struct spwd *spbuf,
               char buf[size], size_t size,
               struct spwd **spbufp);
int getspnam_r(size_t size;
               const char *name, struct spwd *spbuf,
               char buf[size], size_t size,
               struct spwd **spbufp);

int fgetspent_r(size_t size;
               FILE *stream, struct spwd *spbuf,
               char buf[size], size_t size,
               struct spwd **spbufp);
int sgetspent_r(size_t size;
               const char *s, struct spwd *spbuf,
               char buf[size], size_t size,
               struct spwd **spbufp);

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

getspent_r(), getspnam_r(), fgetspent_r(), sgetspent_r():
    منذ glibc 2.19:
        _DEFAULT_SOURCE
    glibc 2.19 وما قبله:
        _BSD_SOURCE || _SVID_SOURCE

الوصف
منذ زمن بعيد، اعتُبر من الآمن وجود كلمات سر معمّاة مرئية علنًا في ملف كلمة السر. عندما أصبحت الحواسيب أسرع وأصبح الناس أكثر وعيًا بالأمن، لم يعد هذا مقبولًا. نفّذت جوليان فرانسيس هوغ مجموعة كلمة السر الظلي التي تُبقي كلمات السر المعمّاة في قاعدة بيانات كلمة السر الظلي (مثل ملف كلمة السر الظلي المحلي /etc/shadow، وNIS، وLDAP)، والتي لا يقرؤها إلا الجذر.

الدوال الموصوفة أدناه تشبه تلك الخاصة بقاعدة بيانات كلمة السر التقليدية (مثل، انظر getpwnam(3) وgetpwent(3)).

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

الدالة getspent() تُرجع مؤشرًا إلى المدخل التالي في قاعدة بيانات كلمة السر الظلي. يُهيّأ الموضع في دفق الإدخال بواسطة setspent(). عند الانتهاء من القراءة، قد يستدعي البرنامج endspent() ليُحرّر الموارد.

الدالة fgetspent() مشابهة لـ getspent() لكنها تستخدم الدفق المُزوّد بدلًا من الذي فُتح ضمنيًا بواسطة setspent().

الدالة sgetspent() تُحلل سلسلة المحارف المُزوّدة s إلى بنية spwd.

الدالة putspent() تكتب محتويات البنية المُزوّدة spwd *p كسطر نصي بتنسيق ملف كلمة السر الظلي إلى stream. تُكتب مدخلات سلسلة المحارف بقيمة NULL ومدخلات رقمية بقيمة -1 كسلسلة محارف فارغة.

الدالة lckpwdf() تهدف إلى الحماية من الوصول المتزامن المتعدد لقاعدة بيانات كلمة السر الظلي. تحاول الحصول على قفل، وتُرجع 0 عند النجاح، أو -1 عند الفشل (لم يُحصل القفل خلال 15 ثانية). الدالة ulckpwdf() تُحرر القفل مرة أخرى. لاحظ أنه لا توجد حماية ضد الوصول المباشر لملف كلمة السر الظلي. فقط البرامج التي تستخدم lckpwdf() ستلاحظ القفل.

هذه هي الدوال التي شكلت واجهة برمجة التطبيقات الظلية الأصلية. وهي متاحة على نطاق واسع.

  النسخ المعاد دخولها
مماثلة للدوال القابلة لإعادة الدخول لقاعدة بيانات كلمة السر، تمتلك glibc أيضًا دوال قابلة لإعادة الدخول لقاعدة بيانات كلمة السر الظلية. الدالة getspnam_r() تشبه getspnam() لكنها تُخزّن بنية كلمة السر الظلية المسترجعة في المساحة المُشار إليها بواسطة spbuf. تحتوي بنية كلمة السر الظلية هذه على مؤشرات لسلاسل محارف، وتُخزّن هذه السلاسل المحارف في المخزن المؤقت buf بحجم size. يُخزّن مؤشر للنتيجة (في حالة النجاح) أو NULL (في حالة عدم العثور على إدخال أو حدوث خطأ) في *spbufp.

الدوال getspent_r() و fgetspent_r() و sgetspent_r() مشابهة بالمثل لنظيراتها غير المعاد دخولها.

تمتلك بعض الأنظمة غير glibc أيضًا دوال بهذه الأسماء، غالبًا بنماذج أولية مختلفة.

  البنية
تُعرَّف بنية كلمة السر الظلية في <shadow.h> كالتالي:

    struct spwd {
        char *sp_namp;     /* اسم الولوج */
        char *sp_pwdp;     /* كلمة السر المعماة */
        long  sp_lstchg;   /* تاريخ آخر تغيير
                              (محسوباً بالأيام منذ
                              1970-01-01 00:00:00 +0000 (UTC)) */
        long  sp_min;      /* الحد الأدنى لعدد الأيام بين التغييرات */
        long  sp_max;      /* الحد الأقصى لعدد الأيام بين التغييرات */
        long  sp_warn;     /* عدد الأيام قبل انتهاء صلاحية كلمة المرور
                              لتنبيه المستخدم لتغييرها */
        long  sp_inact;    /* عدد الأيام بعد انتهاء صلاحية كلمة المرور
                              حتى يُعطّل الحساب */
        long  sp_expire;   /* تاريخ انتهاء صلاحية الحساب
                              (محسوباً بالأيام منذ
                              1970-01-01 00:00:00 +0000 (UTC)) */
        unsigned long sp_flag;  /* محجوز */
    };

قيمة الإرجاع
الدوال التي تُرجع مؤشرًا تُرجع NULL إذا لم تكن هناك إدخالات متاحة أو إذا حدث خطأ أثناء المعالجة. الدوال التي لها int كقيمة إرجاع تُرجع 0 للنجاح و -1 للفشل، مع ضبط errno للإشارة إلى الخطأ.

بالنسبة للدوال غير المعاد دخولها، قد تشير قيمة الإرجاع إلى منطقة ثابتة، وقد تُستبدل باستدعاءات لاحقة لهذه الدوال.

الدوال المعاد دخولها تُرجع صفرًا عند النجاح. في حالة الخطأ، يُرجع رقم خطأ.

الأخطاء

EACCES
    لا يمتلك المستدعي صلاحية الوصول إلى ملف كلمة السر الظلية.

ERANGE
    المخزن المؤقت المُقدم صغير جدًا.

الملفات

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

/etc/.pwd.lock
    ملف القفل

يُعرِّف ملف التضمين <paths.h> الثابت _PATH_SHADOW لمسار اسم ملف كلمة السر الظلية.

السمات
للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر attributes(7).
الواجهة | السمة | القيمة
getspnam() | سلامة الخيوط | MT-Unsafe race:getspnam locale
getspent() | سلامة الخيوط | MT-Unsafe race:getspent race:spentbuf locale
setspent(), endspent(), getspent_r() | سلامة الخيوط | MT-Unsafe race:getspent locale
fgetspent() | سلامة الخيوط | MT-Unsafe race:fgetspent
sgetspent() | سلامة الخيوط | MT-Unsafe race:sgetspent
putspent(), getspnam_r(), sgetspent_r() | سلامة الخيوط | المنطقة (locale) آمنة لتعدد المسالك (MT-Safe)
lckpwdf(), ulckpwdf(), fgetspent_r() | سلامة الخيوط | MT-Safe

في الجدول أعلاه، يُشير getspent في race:getspent إلى أنه إذا استُخدمت أي من الدوال setspent()، getspent()، getspent_r()، أو endspent() بالتوازي في خيوط مختلفة من برنامج، فقد تحدث سباقات بيانات.

الإصدارات
تُوفّر العديد من الأنظمة الأخرى واجهة برمجة تطبيقات مماثلة.

المعايير
لا شيء.

انظر أيضًا
getgrnam(3)، getpwnam(3)، getpwnam_r(3)، shadow(5)

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

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

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