الاسم¶

getdate, getdate_r - تحويل سلسلة محارف تاريخ ووقت إلى وقت مفصل

المكتبة¶

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

موجز¶

#include <time.h>

struct tm *getdate(const char *string);

extern int getdate_err;

int getdate_r(const char *restrict string, struct tm *restrict res);

getdate():

    _XOPEN_SOURCE >= 500

getdate_r():

    _GNU_SOURCE

الوصف¶

تحوِّل الدالة getdate() تمثيلاً سلسلة محارف لتاريخ ووقت، موجودًا في المخزن المؤقت المشار إليه بواسطة string، إلى وقت مفصل. يُخزَّن الوقت المفصل في بنية tm، ويُعاد مؤشر إلى هذه البنية كنتيجة للدالة. تُخصَّص بنية tm هذه في تخزين ثابت، وبالتالي تُستبدل باستدعاءات لاحقة لـ getdate().

على عكس strptime(3) (التي تحتوي على معامل format)، تستخدم getdate() التنسيقات الموجودة في الملف الذي يُعطى اسم مساره الكامل في متغير البيئة DATEMSK. يُستخدم السطر الأول في الملف الذي يطابق سلسلة المحارف المُدخلة للتحويل.

تُجرى المطابقة دون حساسية لحالة الأحرف. يُتجاهل الفراغ الزائد، سواء في النمط أو في السلسلة المراد تحويلها.

مواصفات التحويل التي يمكن أن يحتويها النمط هي تلك المُعطاة لـ strptime(3). تُحدد مواصفة تحويل إضافية واحدة في POSIX.1-2001:

%Z

اسم المنطقة الزمنية. لم يُطبَّق هذا في glibc.

عندما يُعطى %Z، تُهيَّأ البنية المحتوية على الوقت المفصل بقيم تتوافق مع الوقت الحالي في المنطقة الزمنية المُعطاة. وإلا، تُهيَّأ البنية إلى الوقت المفصل الموافق للوقت المحلي الحالي (كما في استدعاء localtime(3)).

عندما يُعطى يوم الأسبوع فقط، يُؤخذ اليوم على أنه أول يوم من هذا النوع في أو بعد اليوم.

عندما يُعطى الشهر فقط (بدون سنة)، يُؤخذ الشهر على أنه أول شهر من هذا النوع مساوٍ أو بعد الشهر الحالي. إذا لم يُعطَ يوم، فهو أول يوم من الشهر.

عندما لا تُعطى ساعة ودقيقة وثانية، تُؤخذ الساعة والدقيقة والثانية الحالية.

إذا لم يُعطَ تاريخ، ولكننا نعرف الساعة، فتُؤخذ تلك الساعة على أنها أول ساعة من هذا النوع مساوية أو بعد الساعة الحالية.

getdate_r() هي إضافة GNU تُوفر نسخة قابلة لإعادة الدخول من getdate(). بدلاً من استخدام متغير عام للإبلاغ عن الأخطاء ومخزن مؤقت ثابت لإعادة الوقت المفصل، تُعيد الأخطاء عبر قيمة نتيجة الدالة، وتُعيد الوقت المفصل الناتج في المخزن المؤقت المُخصص من قبل المستدعي والمشار إليه بواسطة المعامل res.

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

عند النجاح، تُعيد getdate() مؤشرًا إلى struct tm. وإلا، تُعيد NULL وتضبط المتغير العام getdate_err على أحد أرقام الأخطاء الموضحة أدناه. التغييرات على errno غير محددة.

عند النجاح، تُعيد getdate_r() 0؛ عند الخطأ، تُعيد أحد أرقام الأخطاء الموضحة أدناه.

الأخطاء¶

تُعاد الأخطاء التالية عبر getdate_err (لـ getdate()) أو كنتيجة للدالة (لـ getdate_r()):

1

متغير البيئة DATEMSK غير مُعرَّف، أو قيمته سلسلة محارف فارغة.

2

ملف القالب المُحدَّد بواسطة DATEMSK لا يمكن فتحه للقراءة.

3

فشل الحصول على معلومات حالة الملف.

4

ملف القالب ليس ملفًا عاديًا.

5

وُجِد خطأ أثناء قراءة ملف القالب.

6

فشل تخصيص الذاكرة (لا توجد ذاكرة كافية متاحة).

7

لا يوجد سطر في الملف يطابق المُدخل.

8

مواصفات مُدخل غير صالحة.

البيئة¶

DATEMSK

ملف يحتوي على أنماط التنسيق.

TZ

LC_TIME

متغيرات تُستخدم بواسطة strptime(3).

السمات¶

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

الإصدارات¶

مواصفات POSIX.1 لـ strptime(3) تحتوي على مواصفات تحويل تستخدم المُعدِّل %E أو %O، بينما هذه المواصفات غير مُعطاة لـ getdate(). في glibc، getdate() مُطبَّقة باستخدام strptime(3)، لذا فإن نفس التحويلات مدعومة تمامًا بواسطة كلتيهما.

المعايير¶

POSIX.1-2008.

التاريخ¶

POSIX.1-2001.

أمثلة¶

البرنامج أدناه يستدعي getdate() لكل وسيط من وسائط سطر الأوامر، ولكل استدعاء يعرض القيم في حقول بنية tm المُرجَعة. جلسة الصدفة التالية توضح تشغيل البرنامج:

$ TFILE=$PWD/tfile
$ echo '%A' > $TFILE       # Full name of the day of the week
$ echo '%T' >> $TFILE      # Time (HH:MM:SS)
$ echo '%F' >> $TFILE      # ISO date (YYYY-MM-DD)
$ date
$ export DATEMSK=$TFILE
$ ./a.out Tuesday '2009-12-28' '12:22:33'
Sun Sep  7 06:03:36 CEST 2008
Call 1 ("Tuesday") succeeded:


    tm_sec   = 36


    tm_min   = 3


    tm_hour  = 6


    tm_mday  = 9


    tm_mon   = 8


    tm_year  = 108


    tm_wday  = 2


    tm_yday  = 252


    tm_isdst = 1
Call 2 ("2009-12-28") succeeded:


    tm_sec   = 36


    tm_min   = 3


    tm_hour  = 6


    tm_mday  = 28


    tm_mon   = 11


    tm_year  = 109


    tm_wday  = 1


    tm_yday  = 361


    tm_isdst = 0
Call 3 ("12:22:33") succeeded:


    tm_sec   = 33


    tm_min   = 22


    tm_hour  = 12


    tm_mday  = 7


    tm_mon   = 8


    tm_year  = 108


    tm_wday  = 0


    tm_yday  = 250


    tm_isdst = 1

#define _GNU_SOURCE
#include <stdio.h>
#include <stdlib.h>
#include <time.h>
int
main(int argc, char *argv[])
{


    struct tm *tmp;


    for (size_t j = 1; j < argc; j++) {


        tmp = getdate(argv[j]);


        if (tmp == NULL) {


            printf("Call %zu failed; getdate_err = %d\n",


                   j, getdate_err);


            continue;


        }


        printf("Call %zu (\"%s\") succeeded:\n", j, argv[j]);


        printf("    tm_sec   = %d\n", tmp->tm_sec);


        printf("    tm_min   = %d\n", tmp->tm_min);


        printf("    tm_hour  = %d\n", tmp->tm_hour);


        printf("    tm_mday  = %d\n", tmp->tm_mday);


        printf("    tm_mon   = %d\n", tmp->tm_mon);


        printf("    tm_year  = %d\n", tmp->tm_year);


        printf("    tm_wday  = %d\n", tmp->tm_wday);


        printf("    tm_yday  = %d\n", tmp->tm_yday);


        printf("    tm_isdst = %d\n", tmp->tm_isdst);


    }


    exit(EXIT_SUCCESS);
}

انظر أيضًا¶

time(2), localtime(3), setlocale(3), strftime(3), strptime(3)

ترجمة¶

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

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

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