mbsrtowcs(3)

الاسم
mbsrtowcs - تحويل سلسلة محارف متعددة البايت إلى سلسلة محارف عريضة (قابلة لإعادة التشغيل)

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

موجز
#include <wchar.h>

size_t mbsrtowcs(size_t dsize;
                 wchar_t dest[restrict dsize],
                 const char **restrict src,
                 size_t dsize, mbstate_t *restrict ps);

الوصف
إذا لم يكن dest NULL، حوّل سلسلة المحارف متعددة البايت *src إلى سلسلة محارف عريضة تبدأ من dest. يُكتب على الأكثر dsize حرفًا عريضًا إلى dest. تُحدّث حالة الإزاحة *ps. يُنفّذ التحويل فعليًا باستدعاء متكرر لـ mbrtowc(dest, *src, n, ps) حيث n عدد موجب، طالما نجح هذا الاستدعاء، ثم زيادة dest بمقدار 1 و *src بعدد البايتات المستهلكة. يمكن أن يتوقف التحويل لثلاثة أسباب:

•   وُجِد تسلسل متعدد البايتات غير صالح. في هذه الحالة، يُترك *src يشير إلى التسلسل غير الصالح، ويُعاد (size_t) -1، ويُضبط errno على EILSEQ.

•   خُزّنت dsize حرفًا عريضًا غير L'\0' في dest. في هذه الحالة، يُترك *src مشيرًا إلى تسلسل المحارف متعددة البايت التالي المراد تحويله، ويُعاد عدد المحارف العريضة المكتوبة إلى dest.

•   حُوّلت سلسلة المحارف متعددة البايت بالكامل، بما في ذلك الحرف العريض الفارغ الختامي ('\0')، الذي له أثر جانبي بإعادة *ps إلى الحالة الأولية. في هذه الحالة، يُضبط *src على NULL، ويُعاد عدد المحارف العريضة المكتوبة إلى dest، باستثناء الحرف العريض الفارغ الختامي.

إذا كان dest فارغا (NULL)، يُتجاهل dsize، ويستمر التحويل كما هو موضح أعلاه، باستثناء أن المحارف العريضة المحولة لا تُكتب في الذاكرة، ولا يوجد حد للطول.

في كلتا الحالتين أعلاه، إذا كان ps NULL، يُستخدم حالة مجهولة ثابتة معروفة فقط لدالة mbsrtowcs() بدلاً من ذلك.

لتجنب الحالة 2 أعلاه، يجب على المبرمج التأكد من أن dsize أكبر من أو يساوي mbsrtowcs(NULL,src,0,ps)+1.

يجب على المبرمج التأكد من وجود مساحة لـ dsize من المحارف العريضة على الأقل في dest.

هذه الدالة هي نسخة قابلة لإعادة التشغيل من mbstowcs(3).

قيمة الإرجاع
عدد المحارف العريضة التي تشكل الجزء المحول من سلسلة المحارف العريضة، دون تضمين الحرف العريض الفارغ الختامي. إذا صودف تسلسل محارف متعددة البايت غير صالح، يُعاد (size_t) -1، ويُضبط errno على EILSEQ.

السمات
للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر attributes(7).
الواجهة | السمة | القيمة
mbsrtowcs() | سلامة الخيوط | MT-Unsafe race:mbsrtowcs/!ps

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

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

ملاحظات
يعتمد سلوك mbsrtowcs() على فئة LC_CTYPE للإعدادات المحلية الحالية.

تمرير NULL كـ ps ليس آمنًا في تعدد الخيوط.

انظر أيضًا
iconv(3), mbrtowc(3), mbsinit(3), mbsnrtowcs(3), mbstowcs(3)

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

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

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