الاسم¶

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

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 للقراءة فقط تُتجاهل بصمت.

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

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

TIME_OK

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

TIME_INS

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

TIME_DEL

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

TIME_OOP

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

TIME_WAIT

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

TIME_ERROR

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

الاسم الرمزي 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).

المعايير¶

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 "واجهة برمجة تطبيقات النواة"

ترجمة¶

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

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

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