adjtimex(2)

الاسم
adjtimex, clock_adjtime, ntp_adjtime - ضبط ساعة النواة

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

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

int adjtimex(struct timex *buf);

int clock_adjtime(clockid_t clk_id, struct timex *buf);

int ntp_adjtime(struct timex *buf);

الوصف
يستخدم لينكس خوارزمية ضبط الساعة لديفيد إل. ميلز (انظر RFC 5905). يقرأ استدعاء النظام adjtimex() معلمات الضبط لهذه الخوارزمية ويضبطها اختيارياً. يأخذ مؤشراً لبنية timex، ويُحدّث معلمات النواة من قيم الحقول (المحددة)، ويعيد نفس البنية مُحدّثة بقيم النواة الحالية. تُصرّح هذه البنية كما يلي:

    struct timex {
        int  modes;      /* Mode selector */
        long offset;     /* Time offset; nanoseconds, if STA_NANO
                            status flag is set, otherwise
                            microseconds */
        long freq;       /* Frequency offset; see NOTES for units */
        long maxerror;   /* Maximum error (microseconds) */
        long esterror;   /* Estimated error (microseconds) */
        int  status;     /* Clock command/status */
        long constant;   /* PLL (phase-locked loop) time constant */
        long precision;  /* Clock precision
                            (microseconds, read-only) */
        long tolerance;  /* Clock frequency tolerance (read-only);
                            see NOTES for units */
        struct timeval time;
                         /* Current time (read-only, except for
                            ADJ_SETOFFSET); upon return, time.tv_usec
                            contains nanoseconds, if STA_NANO status
                            flag is set, otherwise microseconds */
        long tick;       /* Microseconds between clock ticks */
        long ppsfreq;    /* PPS (pulse per second) frequency
                            (read-only); see NOTES for units */
        long jitter;     /* PPS jitter (read-only); nanoseconds, if
                            STA_NANO status flag is set, otherwise
                            microseconds */
        int  shift;      /* PPS interval duration
                            (seconds, read-only) */
        long stabil;     /* PPS stability (read-only);
                            see NOTES for units */
        long jitcnt;     /* PPS count of jitter limit exceeded
                            events (read-only) */
        long calcnt;     /* PPS count of calibration intervals
                            (read-only) */
        long errcnt;     /* PPS count of calibration errors
                            (read-only) */
        long stbcnt;     /* PPS count of stability limit exceeded
                            events (read-only) */
        int tai;         /* TAI offset, as set by previous ADJ_TAI
                            operation (seconds, read-only,
                            since Linux 2.6.26) */
        /* Further padding bytes to allow for future expansion */
    };

يحدد حقل modes أي المعلمات، إن وجدت، سيتم ضبطها. (كما هو موصوف لاحقًا في هذه الصفحة، الثوابت المستخدمة لـ ntp_adjtime() متكافئة ولكن بأسماء مختلفة.) إنه قناع بت يحتوي على تركيبة OR بتية لواحد أو أكثر من البتات التالية:

ADJ_OFFSET
    ضبط إزاحة الوقت من buf.offset. منذ لينكس 2.6.26، تُقيد القيمة المُقدمة إلى النطاق (-0.5s, +0.5s). في النوى الأقدم، يحدث خطأ EINVAL إذا كانت القيمة المُقدمة خارج النطاق.

ADJ_FREQUENCY
    ضبط إزاحة التردد من buf.freq. منذ لينكس 2.6.26، تُقيد القيمة المُقدمة إلى النطاق (-32768000, +32768000). في النوى الأقدم، يحدث خطأ EINVAL إذا كانت القيمة المُقدمة خارج النطاق.

ADJ_MAXERROR
    ضبط الخطأ الزمني الأقصى من buf.maxerror.

ADJ_ESTERROR
    ضبط الخطأ الزمني المقدر من buf.esterror.

ADJ_STATUS
    ضبط بتات حالة الساعة من buf.status. وصف هذه البتات مُقدم أدناه.

ADJ_TIMECONST
    ضبط ثابت وقت PLL من buf.constant. إذا كانت علامة الحالة STA_NANO (انظر أدناه) غير مضبوطة، تضيف النواة 4 إلى هذه القيمة.

ADJ_SETOFFSET (منذ لينكس 2.6.39)
    إضافة buf.time إلى الوقت الحالي. إذا تضمن buf.status العلم ADJ_NANO، فإن buf.time.tv_usec يُفسر كقيمة نانوثانية؛ وإلا يُفسر كميكروثانية.

    قيمة buf.time هي مجموع حقليها، لكن الحقل buf.time.tv_usec يجب أن يكون دائماً غير سالب. يوضح المثال التالي كيفية تسوية timeval بدقة نانوثانية.

        while (buf.time.tv_usec < 0) {
            buf.time.tv_sec  -= 1;
            buf.time.tv_usec += 1000000000;
        }

ADJ_MICRO (منذ لينكس 2.6.26)
    اختيار دقة ميكروثانية.

ADJ_NANO (منذ لينكس 2.6.26)
    اختيار دقة نانوثانية. يجب تحديد واحد فقط من ADJ_MICRO و ADJ_NANO.

ADJ_TAI (منذ لينكس 2.6.26)
    ضبط إزاحة TAI (الوقت الذري الدولي) من buf.constant.

    لا ينبغي استخدام ADJ_TAI مع ADJ_TIMECONST، لأن الوضع الأخير يستخدم أيضًا حقل buf.constant.

    للحصول على شرح كامل لـ TAI والفرق بين TAI وUTC، انظر BIPM (http://www.bipm.org/en/bipm/tai/tai.html)

ADJ_TICK
    ضبط قيمة النبضة من buf.tick.

بدلاً من ذلك، يمكن تحديد modes كأي من القيم التالية (قناع متعدد البتات)، وفي هذه الحالة لا ينبغي تحديد البتات الأخرى في modes:

ADJ_OFFSET_SINGLESHOT
    adjtime(3) بالطريقة القديمة: ضبط الوقت (تدريجيًا) بالقيمة المحددة في buf.offset، والتي تحدد تعديلاً بالميكروثانية.

ADJ_OFFSET_SS_READ (وظيفي منذ Linux 2.6.28)
    إرجاع (في buf.offset) المقدار المتبقي من الوقت الذي سيتم تعديله بعد عملية ADJ_OFFSET_SINGLESHOT سابقة. أُضيفت هذه الميزة في Linux 2.6.24، لكنها لم تعمل بشكل صحيح حتى Linux 2.6.28.

يُقيد المستخدمون العاديون بقيمة 0 أو ADJ_OFFSET_SS_READ لـ modes. فقط المستخدم المتمكن يمكنه ضبط أي معلمات.

حقل buf.status هو قناع بت يُستخدم لضبط و/أو استرداد بتات الحالة المرتبطة بتنفيذ NTP. بعض البتات في القناع قابلة للقراءة والضبط، بينما البعض الآخر للقراءة فقط.

STA_PLL (قراءة-كتابة)
    تمكين تحديثات حلقة قفل الطور (PLL) عبر ADJ_OFFSET.

STA_PPSFREQ (قراءة-كتابة)
    تمكين ضبط التردد لنبضة في الثانية (PPS).

STA_PPSTIME (قراءة-كتابة)
    تمكين ضبط الوقت لنبضة في الثانية (PPS).

STA_FLL (قراءة-كتابة)
    اختيار وضع حلقة قفل التردد (FLL).

STA_INS (قراءة-كتابة)
    إدراج ثانية كبيسة بعد الثانية الأخيرة من يوم UTC، وبالتالي تمديد الدقيقة الأخيرة من اليوم بثانية واحدة. سيحدث إدراج الثانية الكبيسة كل يوم، طالما بقيت هذه العلامة مضبوطة.

STA_DEL (قراءة-كتابة)
    حذف ثانية كبيسة عند الثانية الأخيرة من يوم UTC. سيحدث حذف الثانية الكبيسة كل يوم، طالما بقيت هذه العلامة مضبوطة.

STA_UNSYNC (قراءة-كتابة)
    الساعة غير متزامنة.

STA_FREQHOLD (قراءة-كتابة)
    تثبيت التردد. عادةً، تؤدي التعديلات التي تتم عبر ADJ_OFFSET إلى إجراء تعديلات تردد مخففة أيضًا. لذا، تصحح استدعاء واحد الإزاحة الحالية، ولكن مع تكرار الإزاحات في نفس الاتجاه، ستتراكم تعديلات التردد الصغيرة لإصلاح الانحراف طويل المدى.

    تمنع هذه العلامة إجراء تعديل التردد الصغير عند التصحيح لقيمة ADJ_OFFSET.

STA_PPSSIGNAL (للقراءة فقط)
    توجد إشارة نبضة في الثانية (PPS) صالحة.

STA_PPSJITTER (للقراءة فقط)
    تم تجاوز ارتعاش إشارة PPS.

STA_PPSWANDER (للقراءة فقط)
    تم تجاوز انحراف إشارة PPS.

STA_PPSERROR (للقراءة فقط)
    خطأ في معايرة إشارة PPS.

STA_CLOCKERR (للقراءة فقط)
    عطل في عتاد الساعة.

STA_NANO (للقراءة فقط؛ منذ لينكس 2.6.26)
    الدقة (0 = ميكروثانية، 1 = نانوثانية). تُضبط عبر ADJ_NANO، وتُمسح عبر ADJ_MICRO.

STA_MODE (منذ لينكس 2.6.26)
    الوضع (0 = حلقة مقفلة الطور، 1 = حلقة مقفلة التردد).

STA_CLK (للقراءة فقط؛ منذ لينكس 2.6.26)
    مصدر الساعة (0 = A، 1 = B)؛ غير مستخدم حالياً.

محاولات ضبط بتات status للقراءة فقط تُتجاهل بصمت.

  clock_adjtime ()
استدعاء النظام clock_adjtime() (المُضاف في لينكس 2.6.39) يتصرف مثل adjtimex() لكنه يأخذ وسيطة إضافية clk_id لتحديد الساعة المحددة التي سيعمل عليها.

  ntp_adjtime ()
دالة المكتبة ntp_adjtime() (الموصوفة في "واجهة برمجة تطبيقات النواة" لـ NTP، KAPI) هي واجهة أكثر قابلية للنقل لأداء نفس مهمة adjtimex(). باستثناء النقاط التالية، فهي مطابقة لـ adjtimex():

•   الثوابت المستخدمة في modes مسبوقة بـ "MOD_" بدلاً من "ADJ_"، ولها نفس اللواحق (وبالتالي، MOD_OFFSET، MOD_FREQUENCY، وهكذا)، باستثناء الاستثناءات المذكورة في النقاط التالية.

•   MOD_CLKA هو المرادف لـ ADJ_OFFSET_SINGLESHOT.

•   MOD_CLKB هو المرادف لـ ADJ_TICK.

•   لا يوجد مرادف لـ ADJ_OFFSET_SS_READ، والذي لم يُوصف في KAPI.

قيمة الإرجاع
عند النجاح، تُرجع adjtimex() و ntp_adjtime() حالة الساعة؛ أي إحدى القيم التالية:

TIME_OK
    الساعة متزامنة، لا يوجد تعديل ثانية كبيسة معلق.

TIME_INS
    يشير إلى أنه ستُضاف ثانية كبيسة في نهاية يوم UTC.

TIME_DEL
    يشير إلى أنه ستُحذف ثانية كبيسة في نهاية يوم UTC.

TIME_OOP
    إدراج ثانية كبيسة قيد التنفيذ.

TIME_WAIT
    اكتمل إدراج أو حذف ثانية كبيسة. سيتم إرجاع هذه القيمة حتى تقوم عملية ADJ_STATUS التالية بمسح العلامتين STA_INS و STA_DEL.

TIME_ERROR
    ساعة النظام غير متزامنة مع خادم موثوق. يتم إرجاع هذه القيمة عندما يتحقق أي مما يلي:

    •   إما STA_UNSYNC أو STA_CLOCKERR مضبوط.

    •   STA_PPSSIGNAL غير مضبوط وإما STA_PPSFREQ أو STA_PPSTIME مضبوط.

    •   كل من STA_PPSTIME و STA_PPSJITTER مضبوطان.

    •   STA_PPSFREQ مضبوط وإما STA_PPSWANDER أو STA_PPSJITTER مضبوط.

    الاسم الرمزي TIME_BAD هو مرادف لـ TIME_ERROR، تم توفيره للتوافق مع الإصدارات السابقة.

لاحظ أنه بدءًا من لينكس 3.4، تعمل الاستدعاءات بشكل غير متزامن وعادةً لا تعكس القيمة المرجعة تغيير حالة ناتج عن الاستدعاء نفسه.

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

الأخطاء

EFAULT
    buf لا يشير إلى ذاكرة قابلة للكتابة.

EINVAL (قبل لينكس 2.6.26)
    جرت محاولة لتعيين buf.freq إلى قيمة خارج النطاق (-33554432, +33554432).

EINVAL (قبل لينكس 2.6.26)
    جرت محاولة لتعيين buf.offset إلى قيمة خارج النطاق المسموح. قبل لينكس 2.0، كان النطاق المسموح (-131072, +131072). من لينكس 2.0 فصاعدًا، أصبح النطاق المسموح (-512000, +512000).

EINVAL
    جرت محاولة لتعيين buf.status إلى قيمة غير تلك المذكورة أعلاه.

EINVAL
    clk_id المعطى لـ clock_adjtime() غير صالح لأحد سببين. إما أن قيمة معرف الساعة الموجبة المشفرة بنمط System-V خارج النطاق، أو أن clk_id الديناميكي لا يشير إلى مثيل صالح لكائن ساعة. راجع clock_gettime(2) لمناقشة الساعات الديناميكية.

EINVAL
    جرت محاولة لتعيين buf.tick إلى قيمة خارج النطاق 900000/HZ إلى 1100000/HZ، حيث HZ هو تردد مقاطعة المؤقت للنظام.

ENODEV
    الجهاز القابل للتوصيل السريع (مثل USB على سبيل المثال) الممثل بواسطة clk_id ديناميكي اختفى بعد فتح جهاز الأحرف الخاص به. راجع clock_gettime(2) لمناقشة الساعات الديناميكية.

EOPNOTSUPP
    clk_id المعطى لا يدعم الضبط.

EPERM
    buf.modes ليس 0 ولا ADJ_OFFSET_SS_READ، والمستدعي لا يملك صلاحية كافية. تحت لينكس، مطلوب القدرة CAP_SYS_TIME.

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

المعايير

adjtimex()
clock_adjtime()
    لينكس.

واجهة برمجة التطبيقات المفضلة لبرنامج NTP الخفي هي ntp_adjtime().

ملاحظات
في البنية timex، freq و ppsfreq و stabil هي ppm (جزء في المليون) مع جزء كسري 16 بت، مما يعني أن القيمة 1 في أحد هذه الحقول تعني فعليًا 2^-16 ppm، و 2^16=65536 هي 1 ppm. هذا هو الحال لكل من قيم الإدخال (في حالة freq) وقيم الإخراج.

معالجة الثانية الكبيسة التي يتم تشغيلها بواسطة STA_INS و STA_DEL تتم بواسطة النواة في سياق المؤقت. وبالتالي، سيستغرق الأمر علامة واحدة في الثانية لإدراج أو حذف الثانية الكبيسة.

انظر أيضًا
clock_gettime(2), clock_settime(2), settimeofday(2), adjtime(3), ntp_gettime(3), capabilities(7), time(7), adjtimex(8), hwclock(8)

NTP "واجهة برمجة تطبيقات النواة" (http://www.slac.stanford.edu/comp/unix/package/rtems/src/ssrlApps/ntpNanoclock/api.htm)

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

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

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