gettimeofday(2)

الاسم
gettimeofday, settimeofday - الحصول / ضبط الوقت

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

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

[[مهمل]]
int gettimeofday(struct timeval *restrict tv,
                 struct timezone *_Nullable restrict tz);
[[مهمل]]
int settimeofday(const struct timeval *tv,
                 const struct timezone *_Nullable tz);

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

settimeofday():
    منذ glibc 2.19:
        _DEFAULT_SOURCE
    glibc 2.19 وما قبله:
        _BSD_SOURCE

الوصف
يمكن للدالتين gettimeofday() و settimeofday() الحصول على الوقت وضبطه بالإضافة إلى منطقة زمنية.

الوسيط tv هو struct timeval (كما هو محدد في <sys/time.h>):

    struct timeval {
        time_t      tv_sec;     /* ثوانٍ */
        suseconds_t tv_usec;    /* ميكرو ثانية */
    };

ويعطي عدد الثواني والميكروثواني منذ الحقبة (انظر time(2)).

الوسيط tz هو struct timezone:

    struct timezone {
        int tz_minuteswest;     /* دقائق غرب غرينتش */
        int tz_dsttime;         /* نوع تصحيح التوقيت الصيفي */
    };

إذا كان أي من tv أو tz NULL، فلن يتم ضبط البنية المقابلة أو إرجاعها. (ومع ذلك، ستنتج تحذيرات ترجمة إذا كان tv NULL.)

استخدام بنية timezone مهمل؛ يجب عادةً تحديد الوسيط tz كـ NULL. انظر الإصدارات.

تحت لينكس، هناك بعض دلالات "الساعة الملتوية" الغريبة المرتبطة باستدعاء النظام settimeofday() إذا كان في أول استدعاء (بعد الإقلاع) يحتوي على وسيط tz غير NULL، وكان الوسيط tv NULL وحقل tz_minuteswest غير صفري. (يجب أن يكون حقل tz_dsttime صفرًا لهذه الحالة.) في مثل هذه الحالة، يُفترض أن ساعة CMOS على التوقيت المحلي، ويجب زيادتها بهذا المقدار للحصول على وقت النظام العالمي (UTC). مما لا شك فيه أن استخدام هذه الميزة فكرة سيئة.

قيمة الإرجاع
ترجع gettimeofday() و settimeofday() 0 عند النجاح. عند الخطأ، يتم إرجاع -1 ويتم ضبط errno للإشارة إلى الخطأ.

الأخطاء

EFAULT
    أشار أحد tv أو tz إلى خارج مساحة العنوان القابلة للوصول.

EINVAL
    (settimeofday()): timezone غير صالح.

EINVAL
    (settimeofday()): tv.tv_sec سالب أو tv.tv_usec خارج النطاق [0, 999,999].

EINVAL (منذ لينكس 4.3)
    (settimeofday()): تمت محاولة ضبط الوقت على قيمة أقل من القيمة الحالية لساعة CLOCK_MONOTONIC (انظر clock_gettime(2)).

EPERM
    لا تملك العملية المستدعية صلاحية كافية لاستدعاء settimeofday()؛ تحت لينكس، مطلوب القدرة CAP_SYS_TIME.

الإصدارات

  الاختلافات بين مكتبة C والنواة
في بعض البنى، يتم توفير تطبيق لـ gettimeofday() في vdso(7).

يقبل النواة NULL لكل من tv و tz. يتم تجاهل وسيط المنطقة الزمنية بواسطة glibc و musl، ولا يتم تمريره إلى/من النواة. تمرر bionic الخاصة بأندرويد وسيط المنطقة الزمنية إلى/من النواة، لكن أندرويد لا يحدث المنطقة الزمنية للنواة بناءً على المنطقة الزمنية للجهاز في الإعدادات، لذا فإن المنطقة الزمنية للنواة عادةً ما تكون UTC.

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

التاريخ
4.3BSD, SVr4. وصفت SUSv1 و POSIX.1-2001 XSI gettimeofday() ولكن ليس settimeofday(). وضعت POSIX.1-2008 XSI علامة على gettimeofday() كمهملة، موصية باستخدام clock_gettime(2) بدلاً من ذلك. وبالمثل، يجب استخدام clock_settime(2) بدلاً من settimeofday(). أزالت POSIX.1-2024 gettimeofday().

تقليديًا، كانت حقول struct timeval من النوع long.

  حقل tz_dsttime
على نواة غير لينكس، مع glibc، سيتم ضبط حقل tz_dsttime من struct timezone على قيمة غير صفرية بواسطة gettimeofday() إذا كانت المنطقة الزمنية الحالية قد طبقت أو ستطبق قاعدة توقيت صيفي. وبهذا المعنى، فإنه يعكس تمامًا معنى daylight(3) للمنطقة الحالية. على لينكس، مع glibc، لم يتم استخدام ضبط حقل tz_dsttime من struct timezone مطلقًا بواسطة settimeofday() أو gettimeofday(). وبالتالي، فإن ما يلي ذو أهمية تاريخية بحتة.

على الأنظمة القديمة، يحتوي الحقل tz_dsttime على ثابت رمزي (القيم معطاة أدناه) يشير إلى أي جزء من السنة يكون التوقيت الصيفي ساريًا. (ملاحظة: هذه القيمة ثابتة طوال العام: لا تشير إلى أن التوقيت الصيفي ساري، بل تحدد خوارزمية فقط.) خوارزميات التوقيت الصيفي المعرفة هي كما يلي:

    DST_NONE     /* ليس على التوقيت الصيفي */
    DST_USA      /* التوقيت الصيفي على الطراز الأمريكي */
    DST_AUST     /* التوقيت الصيفي على الطراز الأسترالي */
    DST_WET      /* التوقيت الصيفي لأوروبا الغربية */
    DST_MET      /* التوقيت الصيفي لأوروبا الوسطى */
    DST_EET      /* التوقيت الصيفي لأوروبا الشرقية */
    DST_CAN      /* كندا */
    DST_GB       /* بريطانيا العظمى وأيرلندا */
    DST_RUM      /* رومانيا */
    DST_TUR      /* تركيا */
    DST_AUSTALT  /* الطراز الأسترالي مع تحول في 1986 */

بالطبع، اتضح أن الفترة التي يكون فيها التوقيت الصيفي ساريًا لا يمكن تحديدها بخوارزمية بسيطة، واحدة لكل بلد؛ في الواقع، هذه الفترة تحددها قرارات سياسية غير متوقعة. لذلك تم التخلي عن هذه الطريقة في تمثيل المناطق الزمنية.

ملاحظات
الوقت الذي ترجعه gettimeofday() يتأثر بالقفزات غير المستمرة في وقت النظام (مثلًا، إذا قام مسؤول النظام بتغيير وقت النظام يدويًا). إذا كنت بحاجة إلى ساعة متزايدة بشكل رتيب، انظر clock_gettime(2).

الماكرو للتعامل مع بنى timeval موصوفة في timeradd(3).

انظر أيضًا
date(1), adjtimex(2), clock_gettime(2), time(2), ctime(3), ftime(3), timeradd(3), capabilities(7), time(7), vdso(7), hwclock(8)

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

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

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