Scroll to navigation

sscanf(3) Library Functions Manual sscanf(3)

الاسم

sscanf, vsscanf - تحويل تنسيق سلسلة محارف الإدخال

المكتبة

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

موجز

#include <stdio.h>
int sscanf(const char *restrict str,
           const char *restrict format, ...);
#include <stdarg.h>
int vsscanf(const char *restrict str,
           const char *restrict format, va_list ap);

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

vsscanf():



    _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L

الوصف

عائلة الدوال sscanf() تفحص الإدخال المنسق وفقًا لـ format كما هو موصوف أدناه. قد يحتوي هذا التنسيق على مواصفات تحويل؛ تُخزَّن نتائج هذه التحويلات، إن وُجدت، في المواقع التي تشير إليها وسائط المؤشر التي تلي format. يجب أن تكون كل وسيطة مؤشر من نوع مناسب للقيمة التي تُرجعها مواصفة التحويل المقابلة.

إذا تجاوز عدد مواصفات التحويل في format عدد وسائط المؤشر، تكون النتائج غير محددة. إذا تجاوز عدد وسائط المؤشر عدد مواصفات التحويل، فتُقيَّم وسائط المؤشر الزائدة، ولكنها تُتجاهل بخلاف ذلك.

sscanf() تقرأ هذه الدوال إدخالها من سلسلة المحارف التي يشير إليها str.

الدالة vsscanf() مماثلة لـ vsprintf(3).

تتكون سلسلة محارف format من سلسلة من التوجيهات التي تصف كيفية معالجة سلسلة محارف الإدخال. إذا فشلت معالجة توجيه، لا يُقرأ أي إدخال إضافي، وتُرجع sscanf(). يمكن أن يكون "الفشل" أحد الأمرين التاليين: فشل إدخال، بمعنى أن محارف الإدخال لم تكن متاحة، أو فشل مطابقة، بمعنى أن الإدخال كان غير مناسب (انظر أدناه).

التوجيه هو أحد ما يلي:

•
سلسلة من محارف المسافة البيضاء (مسافة، علامة تبويب، سطر جديد، إلخ؛ انظر isspace(3)). يطابق هذا التوجيه أي مقدار من المسافة البيضاء، بما في ذلك عدم وجودها، في الإدخال.
•
محرف عادي (أي غير المسافة البيضاء أو '%'). يجب أن يطابق هذا المحرف تمامًا المحرف التالي للإدخال.
•
مواصفة تحويل، تبدأ بمحرف '%' (النسبة المئوية). تُحوَّل سلسلة من المحارف من الإدخال وفقًا لهذه المواصفة، ويُوضع الناتج في وسيطة المؤشر المقابلة. إذا لم يطابق العنصر التالي من الإدخال مواصفة التحويل، يفشل التحويل—وهذا هو فشل مطابقة.

كل مواصفات تحويل في تنسيق تبدأ إما بالحرف '%' أو بتسلسل الأحرف "%n$" (انظر أدناه للتمييز) متبوعًا بـ:

•
حرف '*' اختياري لقمع الإسناد: يقرأ sscanf() المدخلات وفقًا لمواصفات التحويل، لكنه يتجاهل المدخلات. لا يلزم وجود وسيط مؤشر مقابل، ولا تُدرج هذه المواصفات في عدد الإسنادات الناجحة التي يُرجعها scanf().
•
للتحويلات العشرية، محرف اقتباس اختياري ('). يحدد هذا أن رقم الإدخال قد يتضمن فواصل الآلاف كما هو معرف بواسطة فئة LC_NUMERIC من الإعدادات المحلية الحالية. (انظر setlocale(3).) قد يسبق محرف الاقتباس أو يتبع محرف كبت التعيين '*'.
•
محرف 'm' اختياري. يُستخدم هذا مع تحويلات السلاسل (%s, %c, %[)، ويُريح المستدعي من الحاجة إلى تخصيص مخبأ مطابق لحفظ الإدخال: بدلاً من ذلك، تخصص sscanf() مخبأً بحجم كافٍ، وتُسند عنوان هذا المخبأ إلى وسيطة المؤشر المقابلة، والتي يجب أن تكون مؤشرًا لمتغير char * (لا يحتاج هذا المتغير إلى التهيئة قبل الاستدعاء). يجب على المستدعي لاحقًا تحرير هذا المخبأ باستخدام free(3) عندما لا يعود مطلوبًا.
•
عدد صحيح عشري اختياري يحدد أقصى عرض للحقل. تتوقف قراءة الأحرف إما عند الوصول إلى هذا الحد الأقصى أو عند العثور على حرف غير متطابق، أيهما يحدث أولاً. معظم التحويلات تتجاهل أحرف المسافات البيضاء الأولية (الاستثناءات مُلاحظة أدناه)، وهذه الأحرف المُتجاهلة لا تُحتسب ضمن أقصى عرض للحقل. تحويلات إدخال السلسلة تُخزِّن بايت فارغ ختامي ('\0') لتمييز نهاية الإدخال؛ أقصى عرض للحقل لا يتضمن هذا المُنهي.
•
محرف مُعدِّل نوع اختياري. على سبيل المثال، يُستخدم مُعدِّل النوع l مع تحويلات الأعداد الصحيحة مثل %d لتحديد أن وسيطة المؤشر المقابلة تشير إلى long بدلاً من مؤشر إلى int.
•
مُحدِّد تحويل يحدد نوع تحويل الإدخال الذي سيُجرى.

مواصفات التحويل في تنسيق تكون على شكلين، إما تبدأ بـ '%' أو تبدأ بـ "%n$". لا ينبغي خلط الشكلين في نفس سلسلة تنسيق، باستثناء أن سلسلة تحتوي على مواصفات "%n$" يمكن أن تتضمن %% و %*. إذا كان تنسيق يحتوي على مواصفات '%'، فإنها تتطابق بالترتيب مع وسائط مؤشر المتعاقبة. في شكل "%n$" (المُحدد في POSIX.1-2001، ولكن ليس C99)، n هو عدد صحيح عشري يحدد أن الإدخال المُحوَّل يجب وضعه في الموقع المشار إليه بواسطة وسيط مؤشر رقم n التالي لـ تنسيق.

التحويلات

يمكن أن تظهر محارف مُعدِّل النوع التالية في مواصفة تحويل:

يشير إلى أن التحويل سيكون واحدًا من d أو i أو o أو u أو x أو X أو n وأن المؤشر التالي هو مؤشر إلى short أو unsigned short (بدلاً من int).
كما هو الحال مع h، لكن المؤشر التالي هو مؤشر إلى signed char أو unsigned char.
كما هو الحال مع h، لكن المؤشر التالي هو مؤشر إلى intmax_t أو uintmax_t. هذا المُعدِّل أُدخل في C99.
يشير إما إلى أن التحويل سيكون واحدًا من d أو i أو o أو u أو x أو X أو n وأن المؤشر التالي هو مؤشر إلى long أو unsigned long (بدلاً من int)، أو أن التحويل سيكون واحدًا من e أو f أو g وأن المؤشر التالي هو مؤشر إلى double (بدلاً من float). إذا استُخدم مع %c أو %s، فإن المعامل المقابل يُعتبر مؤشرًا إلى حرف عريض أو سلسلة محارف عريضة على التوالي.
(ell-ell) يشير إلى أن التحويل سيكون واحدًا من b أو d أو i أو o أو u أو x أو X أو n وأن المؤشر التالي هو مؤشر إلى long long أو unsigned long long (بدلاً من int).
يشير إلى أن التحويل سيكون إما e أو f أو g وأن المؤشر التالي هو مؤشر إلى long double أو (كإضافة GNU) سيكون التحويل d أو i أو o أو u أو x وأن المؤشر التالي هو مؤشر إلى long long.
مكافئ لـ L. هذا المُحدِّد غير موجود في ANSI C.
كما هو الحال مع h، لكن المؤشر التالي هو مؤشر إلى ptrdiff_t. هذا المُعدِّل أُدخل في C99.
كما هو الحال مع h، لكن المؤشر التالي هو مؤشر إلى size_t. هذا المُعدِّل أُدخل في C99.

مُحدِّدات التحويل التالية متاحة:

%
يطابق حرف '%' حرفيًا. أي أن %% في سلسلة التنسيق يطابق حرف إدخال واحد '%'. لا يُجرى أي تحويل (لكن تُتجاهل محارف المسافات البيضاء الأولية)، ولا يحدث إسناد.
يطابق عددًا صحيحًا عشريًا مع إشارة اختيارية؛ يجب أن يكون المؤشر التالي مؤشرًا إلى int.
يطابق عددًا صحيحًا مع إشارة اختيارية؛ يجب أن يكون المؤشر التالي مؤشرًا إلى int. يُقرأ العدد الصحيح في الأساس 16 إذا بدأ بـ 0x أو 0X، وفي الأساس 8 إذا بدأ بـ 0، وفي الأساس 10 خلاف ذلك. تُستخدم فقط المحارف التي تتوافق مع الأساس.
يطابق عددًا صحيحًا ثمانيًا غير مع إشارة؛ يجب أن يكون المؤشر التالي مؤشرًا إلى unsigned int.
يطابق عددًا صحيحًا عشريًا غير مع إشارة؛ يجب أن يكون المؤشر التالي مؤشرًا إلى unsigned int.
يطابق عددًا صحيحًا سداسيًا عشريًا غير مع إشارة (قد يبدأ اختياريًا ببادئة 0x أو 0X، والتي تُتجاهل)؛ يجب أن يكون المؤشر التالي مؤشرًا إلى unsigned int.
مكافئ لـ x.
يطابق عددًا عائمًا مُوقَّعًا اختياريًا؛ يجب أن يكون المؤشر التالي مؤشرًا إلى float.
مكافئ لـ f.
مكافئ لـ f.
مكافئ لـ f.
(C99) مكافئ لـ f.
يطابق تسلسلاً من المحارف غير البيضاء؛ يجب أن يكون المؤشر التالي مؤشرًا إلى العنصر الأولي لمصفوفة محارف طويلة بما يكفي لاستيعاب تسلسل الإدخال والبايت الصفري الختامي ('\0')، الذي يُضاف آليًا. تتوقف سلسلة الإدخال عند المسافة البيضاء أو عند أقصى عرض حقل، أيهما يحدث أولاً.
تطابق سلسلة من المحارف يُحدد طولها بواسطة أقصى عرض حقل (المبدئي 1); يجب أن يكون المؤشر التالي مؤشرًا إلى char، ويجب أن تكون هناك مساحة كافية لجميع المحارف (لا يُضاف بايت ختامي صفري). يُثبَّط التخطي المعتاد للمسافات البيضاء البادئة. لتخطي المسافات البيضاء أولاً، استخدم مسافة صريحة في التنسيق.
[
تطابق سلسلة غير فارغة من المحارف من المجموعة المحددة من المحارف المقبولة; يجب أن يكون المؤشر التالي مؤشرًا إلى char، ويجب أن تكون هناك مساحة كافية لجميع المحارف في السلسلة، بالإضافة إلى بايت ختامي صفري. يُثبَّط التخطي المعتاد للمسافات البيضاء البادئة. تتكون السلسلة من محارف في (أو ليست في) مجموعة معينة; تُعرَّف المجموعة بالمحارف بين حرف القوس المفتوح [ وحرف القوس المغلق ]. تستبعد المجموعة تستبعد تلك المحارف إذا كان أول حرف بعد القوس المفتوح هو إشارة مد (^). لتضمين قوس مغلق في المجموعة، اجعله أول حرف بعد القوس المفتوح أو إشارة المد; أي موضع آخر سينهي المجموعة. حرف الوصلة - هو أيضًا خاص; عند وضعه بين حرفين آخرين، يُضيف جميع المحارف المتوسطة إلى المجموعة. لتضمين وصلة، اجعلها آخر حرف قبل القوس المغلق النهائي. على سبيل المثال، [^]0-9-] تعني المجموعة "كل شيء باستثناء القوس المغلق، صفر حتى تسعة، والوصلة". تنتهي السلسلة عند ظهور حرف ليس في المجموعة (أو، مع إشارة مد، في المجموعة) أو عندما ينفد عرض الحقل.
يطابق قيمة مؤشر (كما تُطبع بواسطة %p في printf(3))؛ يجب أن يكون المؤشر التالي مؤشرًا إلى مؤشر إلى void.
لا يُتوقع شيء; بدلاً من ذلك، يُخزَّن عدد المحارف المستهلكة حتى الآن من الإدخال عبر المؤشر التالي، والذي يجب أن يكون مؤشرًا إلى int، أو متغير يتطابق حجمه مع معدِّل طول العدد الصحيح (الاختياري) المُقدم. هذا ليس تحويلاً ولا يزيد العدد الذي تُرجعه الدالة. يمكن كبت التعيين بحرف كبت التعيين *، لكن التأثير على القيمة المُرجعة غير مُحدد. لذلك لا ينبغي استخدام تحويلات %*n.

قيمة الإرجاع

عند النجاح، تعيد هذه الدوال عدد عناصر المدخلات التي طابقت وجرى تعيينها بنجاح؛ وقد يكون هذا العدد أقل من المزود، أو حتى صفرًا في حالة فشل المطابقة المبكر.

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

الأخطاء

تسلسل بايتات الدخل لا يشكل محرفاً صالحاً.
لا توجد وسائط كافية؛ أو أن التنسيق format هو NULL.
نفدت الذاكرة.

السمات

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

الواجهة السمة القيمة
sscanf(), vsscanf() سلامة الخيوط المنطقة (locale) آمنة لتعدد المسالك (MT-Safe)

المعايير

C11, POSIX.1-2008.

التاريخ

C89, POSIX.1-2001.

مُحدِّد q هو تدوين 4.4BSD لـ long long، بينما ll أو استخدام L في تحويلات الأعداد الصحيحة هو تدوين GNU.

إصدار لينكس لهذه الدوال مبني على مكتبة GNU libio. ألق نظرة على توثيق info لـ GNU libc (glibc-1.08) للحصول على وصف أكثر إيجازًا.

ملاحظات

مُعدِّل إسناد-تخصيص 'a'

في الأصل، دعمت مكتبة GNU C التخصيص الديناميكي لإدخالات السلسلة (كإضافة غير قياسية) عبر محرف a. (هذه الميزة موجودة على الأقل منذ glibc 2.0.) وبالتالي، يمكن للمرء كتابة ما يلي لجعل sscanf() تخصص مخزنًا مؤقتًا لسلسلة، مع إرجاع مؤشر إلى ذلك المخزن في *buf:


char *buf;
sscanf(str, "%as", &buf);

كان استخدام الحرف a لهذا الغرض إشكاليًا، لأن a مُحدد أيضًا بواسطة معيار ISO C كمرادف لـ f (إدخال النقطة العائمة). بدلاً من ذلك، يُحدد POSIX.1-2008 المُعدِّل m لتخصيص الإسناد (كما هو موثق في الوصف، أعلاه).

لاحظ أن المُعدِّل a غير متاح إذا تم تجميع البرنامج باستخدام gcc -std=c99 أو gcc -D_ISOC99_SOURCE (ما لم يتم تحديد _GNU_SOURCE أيضًا)، وفي هذه الحالة يُفسَّر a كمُحدِّد للأعداد العائمة (انظر أعلاه).

أُضيف دعم المُعدِّل m إلى glibc 2.7، ويجب أن تستخدم البرامج الجديدة هذا المُعدِّل بدلاً من a.

بالإضافة إلى كونه مُوحَّدًا بواسطة POSIX، يتمتع المُعدِّل m بالمزايا الإضافية التالية على استخدام a:

•
يمكن أيضًا تطبيقه على محددات التحويل %c (مثلًا، %3mc).
•
يتجنب هذا الغموض فيما يتعلق بمحدد تحويل الفاصلة العائمة %a (ولا يتأثر بـ gcc -std=c99 وما إلى ذلك).

العلل

محددات التحويل الرقمية

استخدام محددات التحويل الرقمية يُنتج سلوكًا غير مُحدد للإدخال غير الصالح. انظر C11 7.21.6.2/10. هذا خطأ في معيار ISO C، وليس مشكلة تصميمية جوهرية في API. ومع ذلك، فإن التطبيقات الحالية ليست آمنة من هذا الخطأ، لذلك لا يُوصى باستخدامها. بدلاً من ذلك، يجب أن تستخدم البرامج دوالاً مثل strtol(3) لتحليل الإدخال الرقمي. بديلاً، خفف من تأثيره بتحديد أقصى عرض حقل.

المُعدِّلات غير القياسية

هذه الدوال متوافقة تمامًا مع C99، ولكنها توفر المُعدِّلات الإضافية q و a بالإضافة إلى سلوك إضافي للمُعدِّلات L و ll. يمكن اعتبار الأخير خطأ، لأنه يُغير سلوك المُعدِّلات المُعرَّفة في C99.

بعض التركيبات من معدِّلات النوع ومحددات التحويل المُعرَّفة بواسطة C99 لا معنى لها (مثل %Ld). بينما قد يكون لها سلوك مُحدد جيدًا على لينكس، فإن هذا ليس بالضرورة صحيحًا على بنى أخرى. لذلك من الأفضل عادةً استخدام معدِّلات غير مُعرَّفة بواسطة C99 على الإطلاق، أي استخدام q بدلاً من L مع تحويلات d، i، o، u، x، و X أو ll.

استخدام q ليس هو نفسه كما في 4.4BSD، حيث يمكن استخدامه في تحويلات الفاصلة العائمة بشكل مكافئ لـ L.

أمثلة

لاستخدام محدد تحويل التخصيص الديناميكي، حدد m كمعدِّل طول (وبالتالي %ms أو %m[نطاق]). يجب على المُستدعي تحرير free(3) السلسلة المُرجعة، كما في المثال التالي:


char *p;
int n;
errno = 0;
n = sscanf(str, "%m[a-z]", &p);
if (n == 1) {


    printf("read: %s\n", p);


    free(p);
} else if (errno != 0) {


    perror("sscanf");
} else {


    fprintf(stderr, "No matching characters\n");
}

كما هو موضح في المثال أعلاه، من الضروري استدعاء free(3) فقط إذا قرأت استدعاء sscanf() سلسلة محارف بنجاح.

انظر أيضًا

getc(3)، printf(3)، setlocale(3)، strtod(3)، strtol(3)، strtoul(3)

ترجمة

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

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

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

15 يونيو 2024 صفحات دليل لينكس 6.9.1