الاسم¶

iconv - إجراء تحويل مجموعة المحارف

المكتبة¶

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

موجز¶

#include <iconv.h>

size_t iconv(iconv_t cd,
             char **restrict inbuf, size_t *restrict inbytesleft,
             char **restrict outbuf, size_t *restrict outbytesleft);

الوصف¶

تحوّل الدالة iconv() سلسلة من المحارف في ترميز محارف واحد إلى سلسلة من المحارف في ترميز محارف آخر. الوسيط cd هو واصف تحويل، أُنشئ سابقًا باستدعاء iconv_open(3)؛ يحدد واصف التحويل ترميزات المحارف التي تستخدمها iconv() للتحويل. الوسيط inbuf هو عنوان متغير يشير إلى أول محرف في سلسلة الإدخال؛ يشير inbytesleft إلى عدد البايتات في ذلك المخزن المؤقت. الوسيط outbuf هو عنوان متغير يشير إلى أول بايت متاح في مخزن الإخراج المؤقت؛ يشير outbytesleft إلى عدد البايتات المتاحة في مخزن الإخراج المؤقت.

الحالة الرئيسية هي عندما لا يكون inbuf NULL ولا *inbuf NULL. في هذه الحالة، تحوّل الدالة iconv() سلسلة متعددة البايتات التي تبدأ عند *inbuf إلى سلسلة متعددة البايتات تبدأ عند *outbuf. سيُقرأ على الأكثر *inbytesleft بايت، بدءًا من *inbuf. سيُكتب على الأكثر *outbytesleft بايت، بدءًا من *outbuf.

تقوم الدالة iconv() بتحويل محرف متعدد البايتات واحد في كل مرة، ولكل تحويل محرف تزيد *inbuf وتنقص *inbytesleft بعدد بايتات المدخلات المحولة، وتزيد *outbuf وتنقص *outbytesleft بعدد بايتات المخرجات المحولة، وتحدث حالة التحويل الموجودة في cd. إذا كان ترميز المحارف للمدخلات ذا حالة، يمكن للدالة iconv() أيضاً تحويل تسلسل من بايتات المدخلات إلى تحديث لحالة التحويل دون إنتاج أي بايتات مخرجات؛ يُسمى هذا المدخل تسلسل إزاحة. يمكن أن يتوقف التحويل لخمسة أسباب:

•

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

•

تمت مصادفة سلسلة متعددة البايتات صالحة ولكن لا يمكن ترجمتها إلى ترميز محارف الإخراج. تعتمد هذه الحالة على التنفيذ وعلى واصف التحويل. في مكتبة GNU C وGNU libiconv، إذا أُنشئ cd بدون اللاحقة //TRANSLIT أو //IGNORE، يكون التحويل صارمًا: تنتج التحويلات ذات الفقدان هذه الحالة. إذا حُددت اللاحقة //TRANSLIT، يمكن للنقل الحرفي تجنب هذه الحالة في بعض الحالات. في مكتبة musl C، لا يمكن أن تحدث هذه الحالة لأن تحويلاً إلى '*' يُستخدم كحل احتياطي. في تطبيقات FreeBSD وNetBSD وSolaris لـ iconv()، لا يمكن أن تحدث هذه الحالة أيضًا، لأن تحويلاً إلى '?' يُستخدم كحل احتياطي. عند استيفاء هذه الحالة، تضبط iconv() errno على EILSEQ وتُرجع (size_t) -1. يُترك *inbuf يشير إلى بداية السلسلة متعددة البايتات غير القابلة للتحويل.

•

تم تحويل سلسلة بايتات الإدخال بالكامل، أي أن *inbytesleft أصبح 0. في هذه الحالة، تُرجع iconv() عدد التحويلات غير القابلة للعكس التي أُجريت خلال هذا الاستدعاء.

•

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

•

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

حالة مختلفة هي عندما يكون inbuf NULL أو *inbuf NULL، ولكن outbuf ليس NULL و*outbuf ليس NULL. في هذه الحالة، تحاول الدالة iconv() ضبط حالة تحويل cd على الحالة الأولية وتخزين تسلسل إزاحة مطابق عند *outbuf. سيُكتب على الأكثر *outbytesleft بايت، بدءًا من *outbuf. إذا لم تكن هناك مساحة كافية في مخزن الإخراج المؤقت لتسلسل إعادة الضبط هذا، تضبط errno على E2BIG وتُرجع (size_t) -1. وإلا، تزيد *outbuf وتنقص *outbytesleft بعدد البايتات المكتوبة.

حالة ثالثة هي عندما يكون inbuf NULL أو *inbuf NULL، ويكون outbuf NULL أو *outbuf NULL. في هذه الحالة، تضبط الدالة iconv() حالة تحويل cd على الحالة الأولية.

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

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

الأخطاء¶

يمكن أن تحدث الأخطاء التالية، من بين أخطاء أخرى:

E2BIG

لا توجد مساحة كافية عند *outbuf.

EILSEQ

تمت مصادفة سلسلة متعددة البايتات غير صالحة في الإدخال.

EINVAL

تمت مصادفة سلسلة متعددة البايتات غير مكتملة في الإدخال.

السمات¶

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

الدالة iconv() آمنة للخيوط (MT-Safe)، طالما أن المستدعين يرتبون للاستبعاد المتبادل على الوسيط cd.

المعايير¶

POSIX.1-2008.

التاريخ¶

glibc 2.1. POSIX.1-2001.

ملاحظات¶

في كل سلسلة من استدعاءات iconv()، يجب أن يكون آخرها مع inbuf أو *inbuf مساوياً لـ NULL، وذلك لطرد أي مدخلات محولة جزئياً.

على الرغم من أن inbuf و outbuf مكتوبان كـ char **، إلا أن هذا لا يعني أن الكائنات التي يشيران إليها يمكن تفسيرها كسلاسل محارف C أو كمصفوفات محارف: تفسير تسلسلات البايتات المحرفية يُعالج داخلياً بواسطة دوال التحويل. في بعض الترميزات، قد تكون البايتة الصفرية جزءاً صالحاً من محرف متعدد البايتات.

يجب على مستدعي iconv() أن يضمن أن المؤشرات الممررة للدالة مناسبة للوصول إلى المحارف في مجموعة المحارف المناسبة. يشمل ذلك ضمان المحاذاة الصحيحة على المنصات التي لديها قيود صارمة على المحاذاة.

انظر أيضًا¶

iconv_close(3)، iconv_open(3)، iconvconfig(8)

ترجمة¶

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

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

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