newlocale(3)

الاسم
newlocale, freelocale - إنشاء وتعديل وتحرير كائن محلي

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

موجز
#include <locale.h>

locale_t newlocale(int category_mask, const char *locale,
                   locale_t base);
void freelocale(locale_t locobj);

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

newlocale()، freelocale():
    منذ glibc 2.10:
        _XOPEN_SOURCE >= 700
    قبل glibc 2.10:
        _GNU_SOURCE

الوصف
تنشئ الدالة newlocale() كائنًا محليًا جديدًا، أو تعدل كائنًا موجودًا، وتعيد مرجعًا إلى الكائن الجديد أو المعدل كنتيجة للدالة. يُحدد ما إذا كان الاستدعاء ينشئ كائنًا جديدًا أو يعدل كائنًا موجودًا بقيمة base:

•   إذا كان base هو (locale_t) 0، يُنشأ كائن جديد.

•   إذا كان base يشير إلى كائن محلي موجود صالح (أي كائن أُعيد بواسطة استدعاء سابق لـ newlocale() أو duplocale(3))، فسيُعدل ذلك الكائن بواسطة الاستدعاء. إذا نجح الاستدعاء، تكون محتويات base غير محددة (على وجه الخصوص، قد يُحرر الكائن المشار إليه بـ base، ويُنشأ كائن جديد). لذلك، يجب على المستدعي التأكد من توقف استخدام base قبل استدعاء newlocale()، ويجب عليه لاحقًا الإشارة إلى الكائن المعدل عبر المرجع المُعاد كنتيجة للدالة. إذا فشل الاستدعاء، تظل محتويات base صالحة ودون تغيير.

إذا كان base هو الكائن المحلي الخاص LC_GLOBAL_LOCALE (انظر duplocale(3))، أو لم يكن (locale_t) 0 ولم يكن مقبض كائن محلي صالح، فالسلوك غير محدد.

الوسيطة category_mask هي قناع بت يحدد فئات المحلية التي ستُضبط في كائن محلي منشأ حديثًا أو تُعدل في كائن موجود. يُنشأ القناع بواسطة OR أحادي البت للثوابت LC_ADDRESS_MASK وLC_CTYPE_MASK وLC_COLLATE_MASK وLC_IDENTIFICATION_MASK وLC_MEASUREMENT_MASK وLC_MESSAGES_MASK وLC_MONETARY_MASK وLC_NUMERIC_MASK وLC_NAME_MASK وLC_PAPER_MASK وLC_TELEPHONE_MASK وLC_TIME_MASK. بدلاً من ذلك، يمكن تحديد القناع كـ LC_ALL_MASK، وهو ما يعادل OR لجميع الثوابت السابقة.

لكل فئة محددة في category_mask، ستُستخدم بيانات المحلية من locale في الكائن المُعاد بواسطة newlocale(). إذا كان يُنشأ كائن محلي جديد، تُؤخذ بيانات جميع الفئات غير المحددة في category_mask من المحلية المبدئية ("POSIX").

القيم المحددة مسبقًا التالية لـ locale مُعرفة لجميع الفئات التي يمكن تحديدها في category_mask:

"POSIX"
    بيئة محلية دنيا لبرامج لغة C.

"C" مكافئ لـ "POSIX".

""  بيئة أصلية مُعرفة بالتطبيق تتوافق مع قيم متغيرات البيئة LC_* وLANG (انظر locale(7)).

  freelocale()
تحرر الدالة freelocale() الموارد المرتبطة بـ locobj، وهو كائن محلي أُعيد سابقًا بواسطة استدعاء لـ newlocale() أو duplocale(3). إذا كان locobj هو LC_GLOBAL_LOCALE أو لم يكن مقبض كائن محلي صالح، فالنتائج غير محددة.

بمجرد تحرير كائن محلي، يجب ألا يستخدمه البرنامج بعد ذلك.

قيمة الإرجاع
عند النجاح، تُعيد newlocale() مقبضًا يمكن استخدامه في استدعاءات duplocale(3) وfreelocale() ودوال أخرى تأخذ وسيطة locale_t. عند الخطأ، تُعيد newlocale() (locale_t) 0، وتضبط errno للإشارة إلى الخطأ.

الأخطاء

EINVAL
    بت واحد أو أكثر في category_mask لا يتوافق مع فئة محلية صالحة.

EINVAL
    locale هو NULL.

ENOENT
    locale ليس مؤشر سلسلة محارف يشير إلى محلية صالحة.

ENOMEM
    ذاكرة غير كافية لإنشاء كائن محلي.

المعايير
POSIX.1-2008.

التاريخ
glibc 2.3.

ملاحظات
يجب تحرير كل كائن محلي أُنشئ بواسطة newlocale() باستخدام freelocale().

أمثلة
يقبل البرنامج التالي وسيطتين لسطر الأوامر كحد أقصى، كل منهما يُعرّف محلية. الوسيطة الأولى مطلوبة، وتُستخدم لتعيين فئة LC_NUMERIC في كائن محلي أُنشئ باستخدام newlocale(). الوسيطة الثانية اختيارية؛ إذا وُجدت، تُستخدم لتعيين فئة LC_TIME للكائن المحلي.

بعد إنشاء وتهيئة الكائن المحلي، يُطبّقه البرنامج باستخدام uselocale(3)، ثم يختبر تأثير تغييرات المحلية عن طريق:

(1) عرض رقم فاصلة عائمة بجزء كسري. سيتأثر هذا المخرج بإعداد LC_NUMERIC. في العديد من المحليات ذات اللغات الأوروبية، يُفصل الجزء الكسري عن الجزء الصحيح باستخدام فاصلة بدلاً من نقطة.

(2) عرض التاريخ. سيتأثر تنسيق ولغة المخرج بإعداد LC_TIME.

تُظهر جلسات الصدفة التالية بعض الأمثلة لتشغيل هذا البرنامج.

اضبط فئة LC_NUMERIC على fr_FR (الفرنسية):

    $ ./a.out fr_FR;
    123456,789
    Fri Mar  7 00:25:08 2014

اضبط فئة LC_NUMERIC على fr_FR (الفرنسية)، وفئة LC_TIME على it_IT (الإيطالية):

    $ ./a.out fr_FR it_IT;
    123456,789
    ven 07 mar 2014 00:26:01 CET

حدد إعداد LC_TIME كسلسلة فارغة، مما يؤدي إلى أخذ القيمة من إعدادات متغيرات البيئة (التي تحدد هنا mi_NZ، الماوري النيوزيلندي):

    $ LC_ALL=mi_NZ ./a.out fr_FR ""
    123456,789
    Te Paraire, te 07 o Poutū-te-rangi, 2014 00:38:44 CET

  مصدر البرنامج
    #define _XOPEN_SOURCE 700
    #include <err.h>
    #include <locale.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <time.h>

    int
    main(int argc, char *argv[])
    {
        char buf[100];
        time_t t;
        size_t s;
        struct tm *tm;
        locale_t loc, nloc;

        if (argc < 2) {
            fprintf(stderr, "Usage: %s locale1 [locale2]\n", argv[0]);
            exit(EXIT_FAILURE);
        }

        /* Create a new locale object, taking the LC_NUMERIC settings
           from the locale specified in argv[1].  */

        loc = newlocale(LC_NUMERIC_MASK, argv[1], (locale_t) 0);
        if (loc == (locale_t) 0)
            err(EXIT_FAILURE, "newlocale");

        /* If a second command-line argument was specified, modify the
           locale object to take the LC_TIME settings from the locale
           specified in argv[2].  We assign the result of this newlocale()
           call to 'nloc' rather than 'loc', since in some cases, we might
           want to preserve 'loc' if this call fails.  */

        if (argc > 2) {
            nloc = newlocale(LC_TIME_MASK, argv[2], loc);
            if (nloc == (locale_t) 0)
                err(EXIT_FAILURE, "newlocale");
            loc = nloc;
        }

        /* Apply the newly created locale to this thread.  */

        uselocale(loc);

        /* Test effect of LC_NUMERIC.  */

        printf("%8.3f\n", 123456.789);

        /* Test effect of LC_TIME.  */

        t = time(NULL);
        tm = localtime(&t);
        if (tm == NULL)
            err(EXIT_FAILURE, "time");

        s = strftime(buf, sizeof(buf), "%c", tm);
        if (s == 0)
            err(EXIT_FAILURE, "strftime");

        printf("%s\n", buf);

        /* Free the locale object.  */

        uselocale(LC_GLOBAL_LOCALE);    /* So 'loc' is no longer in use */
        freelocale(loc);

        exit(EXIT_SUCCESS);
    }

انظر أيضًا
locale(1), duplocale(3), setlocale(3), uselocale(3), locale(5), locale(7)

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

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

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