wprintf(3)

الاسم
wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf - تحويل مخرجات محارف عريضة منسقة

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

موجز
#include <stdio.h>
#include <wchar.h>

int wprintf(const wchar_t *restrict format, ...);
int fwprintf(FILE *restrict stream,
             const wchar_t *restrict format, ...);
int swprintf(size_t n;
             wchar_t wcs[restrict n], size_t n,
             const wchar_t *restrict format, ...);

int vwprintf(const wchar_t *restrict format, va_list args);
int vfwprintf(FILE *restrict stream,
             const wchar_t *restrict format, va_list args);
int vswprintf(size_t n;
             wchar_t wcs[restrict n], size_t n,
             const wchar_t *restrict format, va_list args);

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

كافة الدوال الموضحة أعلاه:
    _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE
        || _POSIX_C_SOURCE >= 200112L

الوصف
عائلة الدوال wprintf() هي المكافئ للمحارف العريضة لعائلة الدوال printf(3). تُجري مخرجات منسقة من المحارف العريضة.

الدالتان wprintf() و vwprintf() تُجريان مخرجات محارف عريضة إلى stdout. يجب ألا يكون stdout موجهاً للبايت؛ انظر fwide(3) لمزيد من المعلومات.

الدالتان fwprintf() و vfwprintf() تُجريان مخرجات محارف عريضة إلى stream. يجب ألا يكون stream موجهاً للبايت؛ انظر fwide(3) لمزيد من المعلومات.

الدالتان swprintf() و vswprintf() تُجريان مخرجات محارف عريضة إلى مصفوفة من المحارف العريضة. يجب على المبرمج ضمان وجود مساحة لـ n محرف عريض على الأقل في wcs.

هذه الدوال تشبه الدوال printf(3), vprintf(3), fprintf(3), vfprintf(3), sprintf(3), vsprintf(3) باستثناء الاختلافات التالية:

•   سلسلة المحارف format هي سلسلة محارف عريضة.

•   يتكون المخرج من محارف عريضة، وليس بايتات.

•   تأخذ swprintf() و vswprintf() معامل n، بينما sprintf(3) و vsprintf(3) لا تفعلان. (تأخذ snprintf(3) و vsnprintf(3) معامل n، لكن هذه الدوال لا تُرجع -1 عند تجاوز سعة المخزن المؤقت في لينكس.)

معالجة محارف التحويل c و s مختلفة:

c   إذا لم يكن المُعدِّل l موجوداً، يُحوَّل المعامل int إلى محرف عريض باستدعاء الدالة btowc(3)، ويُكتب المحرف العريض الناتج. إذا كان المُعدِّل l موجوداً، يُكتب المعامل wint_t (محرف عريض).

s   إذا لم يكن المُعدِّل l موجوداً: يُتوقع أن يكون المعامل const char * مؤشراً إلى مصفوفة من نوع محرف (مؤشر إلى سلسلة محارف) تحتوي على تسلسل محارف متعددة البايتات يبدأ في حالة الإزاحة الأولية. تُحوَّل المحارف من المصفوفة إلى محارف عريضة (كل منها باستدعاء الدالة mbrtowc(3) مع حالة تحويل تبدأ في الحالة الأولية قبل البايت الأول). تُكتب المحارف العريضة الناتجة حتى (ولكن لا تشمل) المحرف العريض الفارغ الختامي (L'\0'). إذا حُددت دقة، لا يُكتب عدد من المحارف العريضة أكثر من العدد المحدد. لاحظ أن الدقة تحدد عدد المحارف العريضة المكتوبة، وليس عدد البايتات أو مواقع الشاشة. يجب أن تحتوي المصفوفة على بايت فارغ ختامي ('\0')، ما لم تُعطَ دقة وكانت صغيرة جداً بحيث يصل عدد المحارف العريضة المحولة إليها قبل الوصول إلى نهاية المصفوفة. إذا كان المُعدِّل l موجوداً: يُتوقع أن يكون المعامل const wchar_t * مؤشراً إلى مصفوفة من المحارف العريضة. تُكتب المحارف العريضة من المصفوفة حتى (ولكن لا تشمل) محرف عريض فارغ ختامي. إذا حُددت دقة، لا يُكتب أكثر من العدد المحدد. يجب أن تحتوي المصفوفة على محرف عريض فارغ ختامي، ما لم تُعطَ دقة وكانت أصغر من أو تساوي عدد المحارف العريضة في المصفوفة.

قيمة الإرجاع
تُرجع الدوال عدد المحارف العريضة المكتوبة، باستثناء المحرف العريض الفارغ الختامي في حالة الدالتين swprintf() و vswprintf(). عند حدوث خطأ، يُرجع -1، ويُضبط errno للإشارة إلى الخطأ.

الأخطاء
انظر write(2) و putwc(3). بالإضافة إلى ذلك، قد يحدث الخطأ التالي:

EOVERFLOW
    القيمة المطلوب إرجاعها أكبر من INT_MAX.

قد تفشل الدالتان fwprintf() و wprintf() بالإضافة إلى ذلك إذا:

ENOMEM
    مساحة تخزين غير كافية متاحة.

السمات
للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر attributes(7).
الواجهة | السمة | القيمة
wprintf(), fwprintf(), swprintf(), vwprintf(), vfwprintf(), vswprintf() | سلامة الخيوط | المنطقة (locale) آمنة لتعدد المسالك (MT-Safe)

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

التاريخ
POSIX.1-2001، C99.

ملاحظات
يعتمد سلوك wprintf() وآخرون على فئة LC_CTYPE من الإعدادات المحلية الحالية.

إذا احتوت سلسلة المحارف format على محارف عريضة غير ASCII، فسيعمل البرنامج بشكل صحيح فقط إذا كانت فئة LC_CTYPE من الإعدادات المحلية الحالية وقت التشغيل مطابقة لفئة LC_CTYPE من الإعدادات المحلية الحالية وقت الترجمة. يعود ذلك إلى أن تمثيل wchar_t يعتمد على المنصة والإعدادات المحلية. (يمثل glibc المحارف العريضة باستخدام نقاط الترميز الخاصة بها في Unicode (ISO/IEC 10646)، لكن المنصات الأخرى لا تفعل ذلك. كما أن استخدام أسماء المحارف العامة C99 بالصيغة \unnnn لا يحل هذه المشكلة.) لذلك، في البرامج المعولمة، ينبغي أن تتكون سلسلة المحارف format من محارف عريضة ASCII فقط، أو تُبنى وقت التشغيل بطريقة معولمة (مثل استخدام gettext(3) أو iconv(3)، متبوعة بـ mbstowcs(3)).

انظر أيضًا
fprintf(3)، fputwc(3)، fwide(3)، printf(3)، snprintf(3)

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

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

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