scanf(3)

الاسم
scanf, fscanf, vscanf, vfscanf - تحويل تنسيق ملف الإدخال

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

موجز
#include <stdio.h>

int scanf(const char *restrict format, ...);
int fscanf(FILE *restrict stream,
           const char *restrict format, ...);

#include <stdarg.h>

int vscanf(const char *restrict format, va_list ap);
int vfscanf(FILE *restrict stream,
           const char *restrict format, va_list ap);

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

vscanf(), vfscanf():
    _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L

الوصف
عائلة دوال scanf() تمسح الإدخال المنسق مثل sscanf(3)، لكنها تقرأ من FILE. من الصعب جدًا استخدام هذه الدوال بشكل صحيح، ومن الأفضل قراءة سطور كاملة باستخدام fgets(3) أو getline(3) وتحليلها لاحقًا باستخدام sscanf(3) أو دوال أكثر تخصصًا مثل strtol(3).

تقرأ دالة scanf() الإدخال من دفق الإدخال القياسي stdin وتقرأ fscanf() الإدخال من مؤشر الدفق stream.

دالة vfscanf() مماثلة لـ vfprintf(3) وتقرأ الإدخال من مؤشر الدفق stream باستخدام قائمة وسائط متغيرة من المؤشرات (انظر stdarg(3). دالة vscanf() مماثلة لـ vprintf(3) وتقرأ من الإدخال القياسي.

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

تُعاد القيمة EOF إذا وُصلت نهاية الإدخال قبل إتمام أول تحويل ناجح أو حدوث فشل مطابقة. تُعاد EOF أيضًا إذا حدث خطأ قراءة، وفي هذه الحالة يُضبط مؤشر الخطأ للدفق (انظر ferror(3))، ويُضبط errno للإشارة إلى الخطأ.

الأخطاء

EAGAIN
    وُسِم واصف الملف الأساسي لـ stream كغير محظور، وستحجب عملية القراءة.

EBADF
    واصف الملف الأساسي لـ stream غير صالح، أو غير مفتوح للقراءة.

EILSEQ
    تسلسل بايتات الدخل لا يشكل محرفاً صالحاً.

EINTR
    قُطعت عملية القراءة بواسطة إشارة؛ انظر signal(7).

EINVAL
    لا توجد وسائط كافية؛ أو أن التنسيق format هو NULL.

ENOMEM
    نفدت الذاكرة.

السمات
للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر attributes(7).
الواجهة | السمة | القيمة
scanf(), fscanf(), vscanf(), vfscanf() | سلامة الخيوط | المنطقة (locale) آمنة لتعدد المسالك (MT-Safe)

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

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

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

لا تستطيع هذه الدوال الإبلاغ عن الأخطاء بعد آخر مواصفات تحويل غير مكبوتة.

العلل
من المستحيل معرفة عدد المحارف التي استهلكتها هذه الدوال من دفق الإدخال بدقة، لأنها تبلغ فقط عن عدد التحويلات الناجحة. على سبيل المثال، إذا كان الإدخال هو "123\n a"، فستستهلك scanf("%d %d", &a, &b) الأرقام، والسطر الجديد، والمسافة، ولكن ليس الحرف a. هذا يجعل التعافي من الإدخال غير الصالح صعبًا.

انظر أيضًا
fgets(3), getline(3), sscanf(3)

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

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

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