الاسم¶

getutent, getutid, getutline, pututline, setutent, endutent, utmpname - الوصول إلى مدخلات ملف utmp

المكتبة¶

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

موجز¶

#include <utmp.h>

struct utmp *getutent(void);
struct utmp *getutid(const struct utmp *ut);
struct utmp *getutline(const struct utmp *ut);

struct utmp *pututline(const struct utmp *ut);

void setutent(void);
void endutent(void);

int utmpname(const char *path);

الوصف¶

يجب على التطبيقات الجديدة استخدام إصدارات "utmpx" المحددة بواسطة POSIX.1 من هذه الدوال؛ انظر المعايير.

تضبط utmpname() اسم مسار ملف تنسيق utmp لدوال utmp الأخرى للوصول إليه. إذا لم تُستخدم utmpname() لضبط اسم المسار قبل استخدام الدوال الأخرى، فإنها تفترض _PATH_UTMP، كما هو معرف في <paths.h>.

تعيد setutent() مؤشر الملف إلى بداية ملف utmp. من الجيد عمومًا استدعاؤها قبل أي من الدوال الأخرى.

تغلق endutent() ملف utmp. يجب استدعاؤها عندما ينتهي كود المستخدم من الوصول إلى الملف باستخدام الدوال الأخرى.

تقرأ getutent() سطرًا من موضع الملف الحالي في ملف utmp. تُرجع مؤشرًا إلى بنية تحتوي على حقول السطر. يظهر تعريف هذه البنية في utmp(5).

تبحث getutid() للأمام من موضع الملف الحالي في ملف utmp بناءً على ut. إذا كان ut->ut_type واحدًا من RUN_LVL أو BOOT_TIME أو NEW_TIME أو OLD_TIME، فستجد getutid() أول مدخل يتطابق حقل ut_type فيه مع ut->ut_type. إذا كان ut->ut_type واحدًا من INIT_PROCESS أو LOGIN_PROCESS أو USER_PROCESS أو DEAD_PROCESS، فستجد getutid() أول مدخل يتطابق حقل ut_id فيه مع ut->ut_id.

تبحث getutline() للأمام من موضع الملف الحالي في ملف utmp. تفحص المدخلات التي يكون ut_type فيها USER_PROCESS أو LOGIN_PROCESS وتُعيد أول مدخل يتطابق حقل ut_line فيه مع ut->ut_line.

تكتب pututline() بنية utmp ut في ملف utmp. تستخدم getutid() للبحث عن المكان المناسب في الملف لإدراج المدخل الجديد. إذا لم تجد فتحة مناسبة لـ ut، فستلحق pututline() المدخل الجديد بنهاية الملف.

قيمة الإرجاع¶

تُعيد getutent() و getutid() و getutline() مؤشرًا إلى struct utmp عند النجاح، و NULL عند الفشل (والذي يتضمن حالة "السجل غير موجود"). تُخصص هذه struct utmp في تخزين ثابت، وقد تُستبدل باستدعاءات لاحقة.

عند النجاح، تُعيد pututline() ut؛ عند الفشل، تُعيد NULL.

تُعيد utmpname() 0 إذا خُزن الاسم الجديد بنجاح، أو -1 عند الفشل.

عند الفشل، تضبط هذه الدوال errno للإشارة إلى الخطأ.

الأخطاء¶

ENOMEM

نفدت الذاكرة.

ESRCH

السجل غير موجود.

يمكن أن تفشل setutent() و pututline() ودوال getut*() أيضًا للأسباب الموصوفة في open(2).

الملفات¶

/var/run/utmp

قاعدة بيانات المستخدمين المسجلين حاليًا

/var/log/wtmp

قاعدة بيانات لعمليات تسجيل دخول المستخدمين السابقة

السمات¶

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

في الجدول أعلاه، يشير utent في race:utent إلى أنه إذا استُخدمت أي من الدوال setutent()، getutent()، getutid()، getutline()، pututline()، utmpname()، أو endutent() بالتوازي في خيوط مختلفة من برنامج، فقد تحدث سباقات بيانات.

المعايير¶

لا شيء.

التاريخ¶

XPG2، SVr4.

في XPG2 وSVID 2، وُثقت الدالة pututline() لترجع void، وهذا ما تفعله على العديد من الأنظمة (AIX، HP-UX). تقدم HP-UX دالة جديدة _pututline() بالنموذج الأولي المذكور أعلاه لـ pututline().

جميع هذه الدوال أصبحت مهملة الآن على الأنظمة غير اللينكسية. لا تحتوي POSIX.1-2001 وPOSIX.1-2008، باتباع SUSv1، على أي من هذه الدوال، بل تستخدم بدلاً من ذلك

#include <utmpx.h>

struct utmpx *getutxent(void);
struct utmpx *getutxid(const struct utmpx *);
struct utmpx *getutxline(const struct utmpx *);
struct utmpx *pututxline(const struct utmpx *);
void setutxent(void);
void endutxent(void);

تُوفر glibc هذه الدوال، وتؤدي نفس المهمة كمعادلاتها بدون "x"، لكنها تستخدم struct utmpx، المُعرَّف على لينكس ليكون مماثلاً لـ struct utmp. للاكتمال، توفر glibc أيضًا utmpxname()، على الرغم من أن هذه الدالة غير محددة بواسطة POSIX.1.

على بعض الأنظمة الأخرى، هيكل utmpx هو مجموعة شاملة لهيكل utmp، مع حقول إضافية، وإصدارات أكبر من الحقول الموجودة، وتُحتفظ بملفات متوازية، غالبًا /var/*/utmpx و/var/*/wtmpx.

من ناحية أخرى، لا تستخدم glibc على لينكس ملف utmpx موازٍ لأن هيكل utmp الخاص بها كبير بما يكفي بالفعل. الدوال "x" المذكورة أعلاه هي مجرد أسماء مستعارة لنظيراتها بدون "x" (على سبيل المثال، getutxent() هو اسم بديل لـ getutent()).

ملاحظات¶

#include <utmp.h>

int getutent_r(struct utmp *ubuf, struct utmp **ubufp);
int getutid_r(struct utmp *ut,
              struct utmp *ubuf, struct utmp **ubufp);
int getutline_r(struct utmp *ut,
                struct utmp *ubuf, struct utmp **ubufp);

    _GNU_SOURCE


        || /* Since glibc 2.19: */ _DEFAULT_SOURCE


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

أمثلة¶

يُضيف المثال التالي ويزيل سجل utmp، بافتراض أنه يُشغّل من داخل طرفية زائفة. للاستخدام في تطبيق حقيقي، يجب عليك التحقق من قيم الإرجاع للدالتين getpwuid(3) و ttyname(3).

#include <err.h>
#include <pwd.h>
#include <stdlib.h>
#include <string.h>
#include <time.h>
#include <unistd.h>
#include <utmp.h>
int
main(void)
{


    struct utmp entry;


    if (system("echo before adding entry:;who") == -1)


        err(EXIT_FAILURE, "system");


    entry.ut_type = USER_PROCESS;


    entry.ut_pid = getpid();


    strcpy(entry.ut_line, ttyname(STDIN_FILENO) + strlen("/dev/"));


    /* only correct for ptys named /dev/tty[pqr][0-9a-z] */


    strcpy(entry.ut_id, ttyname(STDIN_FILENO) + strlen("/dev/tty"));


    entry.ut_time = time(NULL);


    strcpy(entry.ut_user, getpwuid(getuid())->pw_name);


    memset(entry.ut_host, 0, UT_HOSTSIZE);


    entry.ut_addr = 0;


    setutent();


    if (pututline(&entry) == NULL)


        err(EXIT_FAILURE, "pututline");


    if (system("echo after adding entry:;who") == -1)


        err(EXIT_FAILURE, "system");


    entry.ut_type = DEAD_PROCESS;


    memset(entry.ut_line, 0, UT_LINESIZE);


    entry.ut_time = 0;


    memset(entry.ut_user, 0, UT_NAMESIZE);


    setutent();


    if (pututline(&entry) == NULL)


        err(EXIT_FAILURE, "pututline");


    if (system("echo after removing entry:;who") == -1)


        err(EXIT_FAILURE, "system");


    endutent();


    exit(EXIT_SUCCESS);
}

انظر أيضًا¶

getutmp(3), utmp(5)

ترجمة¶

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

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

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