الاسم¶

asctime, ctime, gmtime, localtime, mktime, asctime_r, ctime_r, gmtime_r, localtime_r - تحويل التاريخ والوقت إلى وقت مفصل أو ASCII

المكتبة¶

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

موجز¶

#include <time.h>

char *asctime(const struct tm *tm);
char *asctime_r(const struct tm *restrict tm,
                    char buf[restrict 26]);

char *ctime(const time_t *timep);
char *ctime_r(const time_t *restrict timep,
                    char buf[restrict 26]);

struct tm *gmtime(const time_t *timep);
struct tm *gmtime_r(const time_t *restrict timep,
                    struct tm *restrict result);

struct tm *localtime(const time_t *timep);
struct tm *localtime_r(const time_t *restrict timep,
                    struct tm *restrict result);

time_t mktime(struct tm *tm);

asctime_r(), ctime_r(), gmtime_r(), localtime_r():

    _POSIX_C_SOURCE


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

الوصف¶

الدوال ctime() و gmtime() و localtime() جميعها تأخذ معاملاً من نوع البيانات time_t، الذي يمثل الوقت التقويمي. عند تفسيره كقيمة وقت مطلقة، فإنه يمثل عدد الثواني المنقضية منذ الحقبة، 1970-01-01 00:00:00 +0000 (UTC).

الدالتان asctime() و mktime() تأخذان معاملاً يمثل الوقت المفصل، وهو تمثيل مقسم إلى سنة وشهر ويوم وهكذا.

الوقت المفصل يُخزَّن في الهيكل tm، الموصوف في tm(3type).

الاستدعاء ctime(t) يعادلasctime(localtime(t)). يحول الوقت التقويمي t إلى سلسلة محارف منتهية بصفر بالشكل

"Wed Jun 30 21:49:08 1993\n"

اختصارات أيام الأسبوع هي "Sun" و "Mon" و "Tue" و "Wed" و "Thu" و "Fri" و "Sat". اختصارات الأشهر هي "Jan" و "Feb" و "Mar" و "Apr" و "May" و "Jun" و "Jul" و "Aug" و "Sep" و "Oct" و "Nov" و "Dec". قيمة الإرجاع تشير إلى سلسلة محارف مخصصة بشكل ثابت قد تُستبدل باستدعاءات لاحقة لأي من دوال التاريخ والوقت. الدالة أيضاً تضبط المتغيرات الخارجية tzname و timezone و daylight كما لو أنها استدعت tzset(3). النسخة القابلة لإعادة الدخول ctime_r() تفعل نفس الشيء، لكنها تخزن السلسلة في مخزن مؤقت يوفره المستخدم يجب أن يتسع لـ 26 بايت على الأقل. لا تحتاج إلى ضبط tzname و timezone و daylight.

الدالة gmtime() تحول الوقت التقويمي timep إلى تمثيل وقت مفصل، معبر عنه بالتوقيت العالمي المنسق (UTC). قد ترجع NULL عندما لا يتسع العام لعدد صحيح. قيمة الإرجاع تشير إلى هيكل مخصص بشكل ثابت قد يُستبدل باستدعاءات لاحقة لأي من دوال التاريخ والوقت. الدالة gmtime_r() تفعل نفس الشيء، لكنها تخزن البيانات في هيكل يوفره المستخدم.

الدالة localtime() تحول الوقت التقويمي timep إلى تمثيل وقت مفصل، معبر عنه بالنسبة للمنطقة الزمنية المحددة من قبل المستخدم. الدالة أيضاً تضبط المتغيرات الخارجية tzname و timezone و daylight كما لو أنها استدعت tzset(3). قيمة الإرجاع تشير إلى هيكل مخصص بشكل ثابت قد يُستبدل باستدعاءات لاحقة لأي من دوال التاريخ والوقت. الدالة localtime_r() تفعل نفس الشيء، لكنها تخزن البيانات في هيكل يوفره المستخدم. لا تحتاج إلى ضبط tzname و timezone و daylight.

الدالة asctime() تحول قيمة الوقت المفصل tm إلى سلسلة محارف منتهية بصفر بنفس تنسيق ctime(). قيمة الإرجاع تشير إلى سلسلة محارف مخصصة بشكل ثابت قد تُستبدل باستدعاءات لاحقة لأي من دوال التاريخ والوقت. الدالة asctime_r() تفعل نفس الشيء، لكنها تخزن السلسلة في مخزن مؤقت يوفره المستخدم يجب أن يتسع لـ 26 بايت على الأقل.

الدالة mktime() تحول هيكل وقت مفصل، معبر عنه كوقت محلي، إلى تمثيل وقت تقويمي. الدالة تتجاهل القيم المقدمة من المستدعي في حقلي tm_wday و tm_yday. القيمة المحددة في حقل tm_isdst تُعلم mktime() ما إذا كان التوقيت الصيفي (DST) ساري المفعول للوقت المقدم في هيكل tm: قيمة موجبة تعني أن DST ساري؛ صفر يعني أن DST غير ساري؛ وقيمة سالبة تعني أن mktime() يجب أن (تستخدم معلومات المنطقة الزمنية وقواعد بيانات النظام) تحاول تحديد ما إذا كان DST ساري المفعول في الوقت المحدد.

الدالة mktime() تعدل حقول هيكل tm كالتالي: tm_wday و tm_yday يُضبطان إلى قيم محددة من محتويات الحقول الأخرى؛ إذا كانت أعضاء الهيكل خارج نطاقها الصحيح، فسيتم تطبيعها (بحيث، على سبيل المثال، 40 أكتوبر تُحول إلى 9 نوفمبر)؛ tm_isdst يُضبط (بغض النظر عن قيمته الأولية) إلى قيمة موجبة أو 0، على التوالي، للإشارة إلى ما إذا كان DST ساري المفعول في الوقت المحدد أم لا. الدالة أيضاً تضبط المتغيرات الخارجية tzname و timezone و daylight كما لو أنها استدعت tzset(3).

إذا لم يمكن تمثيل الوقت المفصل المحدد كوقت تقويمي (ثوانٍ منذ الحقبة)، تُرجع mktime() (time_t) -1 ولا تغير أعضاء هيكل الوقت المفصل.

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

عند النجاح، تُرجع gmtime() و localtime() مؤشراً إلى struct tm.

عند النجاح، تُعيد gmtime_r() و localtime_r() عنوان البنية المشار إليها بواسطة result.

عند النجاح، تُعيد asctime() و ctime() مؤشرًا إلى سلسلة محارف.

عند النجاح، تُعيد asctime_r() و ctime_r() مؤشرًا إلى سلسلة المحارف المشار إليها بواسطة buf.

عند النجاح، تُعيد mktime() الوقت التقويمي (الثواني منذ الحقبة)، معبرًا عنه بقيمة من النوع time_t.

عند الخطأ، تُرجع mktime() القيمة (time_t) -1. تُرجع الدوال المتبقية NULL عند الخطأ. عند الخطأ، يُضبط errno للإشارة إلى الخطأ.

الأخطاء¶

EOVERFLOW

لا يمكن تمثيل النتيجة.

السمات¶

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

الإصدارات¶

لا يُحدد POSIX معاملات ctime_r() لتكون restrict؛ ذلك خاص بـ glibc.

في العديد من التطبيقات، بما في ذلك glibc، يُفسر 0 في tm_mday على أنه يعني اليوم الأخير من الشهر السابق.

وفقًا لـ POSIX.1، يُطلب من localtime() أن تتصرف كما لو أن tzset(3) قد استُدعيت، بينما لا تمتلك localtime_r() هذا المطلب. للكود المحمول، يجب استدعاء tzset(3) قبل localtime_r().

المعايير¶

asctime()

ctime()

gmtime()

localtime()

mktime()

C23، ‏POSIX.1-2024.

gmtime_r()

localtime_r()

POSIX.1-2024.

asctime_r()

ctime_r()

لا شيء.

التاريخ¶

gmtime()

localtime()

mktime()

C89, POSIX.1-1988.

asctime()

ctime()

C89، POSIX.1-1988. وُسِمَ بالتقادم في C23 وPOSIX.1-2008 (يوصي بـ strftime(3)).

gmtime_r()

localtime_r()

POSIX.1-1996.

asctime_r()

ctime_r()

POSIX.1-1996. وُسِمَ بالتقادم في POSIX.1-2008. أُزيل في POSIX.1-2024 (يوصي بـ strftime(3)).

ملاحظات¶

الدوال الأربع asctime()، ctime()، gmtime()، وlocaltime() تُعيد مؤشرًا إلى بيانات ثابتة وبالتالي ليست آمنة للخيوط. الإصدارات الآمنة للخيوط، asctime_r()، ctime_r()، gmtime_r()، وlocaltime_r()، مُحددة بواسطة SUSv2.

يقول POSIX.1: "الدوال asctime()، ctime()، gmtime()، وlocaltime() يجب أن تُعيد قيمًا في واحد من كائنين ثابتين: بنية وقت مفصلة ومصفوفة من النوع char. تنفيذ أي من الدوال التي تُعيد مؤشرًا إلى أحد أنواع الكائنات هذه قد يكتب فوق المعلومات في أي كائن من نفس النوع يُشار إليه بالقيمة المُعادة من أي استدعاء سابق لأي منها." يمكن أن يحدث هذا في تطبيق glibc.

انظر أيضًا¶

date(1), gettimeofday(2), time(2), utime(2), clock(3), difftime(3), strftime(3), strptime(3), timegm(3), tzset(3), time(7)

ترجمة¶

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

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

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