الاسم¶

snprintf, vsnprintf - طباعة سلسلة محارف منسقة

المكتبة¶

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

موجز¶

#include <stdio.h>

int snprintf(size_t size;
            char str[restrict size], size_t size,
            const char *restrict format, ...);
int vsnprintf(size_t size;
            char str[restrict size], size_t size,
            const char *restrict format, va_list ap);

snprintf(), vsnprintf():

    _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE


        || /* glibc <= 2.19: */ _BSD_SOURCE

الوصف¶

هذه الدوال مشابهة لـ printf(3)، باستثناء أنها تكتب إلى سلسلة المحارف str بدلاً من تيار.

تكتب الدالتان snprintf() وvsnprintf() على الأكثر size بايت (بما في ذلك بايت الخلو المنتهي ('\0')) إلى str.

vsnprintf() مكافئة لـ snprintf()، باستثناء أنها تُستدعى مع va_list بدلاً من عدد متغير من المعاملات. هذه الدالة لا تستدعي ماكرو va_end. نظرًا لأنها تستدعي ماكرو va_arg، فإن قيمة ap تكون غير معرفة بعد الاستدعاء. انظر stdarg(3).

C99 وPOSIX.1-2001 يحددان أن النتائج غير معرفة إذا تسبب استدعاء snprintf() أو vsnprintf() في نسخ بين كائنات متداخلة (مثلًا، إذا كانت مصفوفة السلسلة الهدف وأحد معاملات الإدخال المقدمة تشير إلى نفس المخزن المؤقت). انظر تحذيرات.

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

عند العودة بنجاح، تعيد هذه الدوال عدد البايتات المطبوعة (باستثناء بايت الخلو المستخدم لإنهاء المخرجات إلى السلاسل النصية).

لا تكتب الدالتان snprintf() وvsnprintf() أكثر من size بايت (بما في ذلك بايت الخلو المنتهي ('\0')). إذا بُترت المخرجات بسبب هذا الحد، فإن القيمة المعادة هي عدد المحارف (باستثناء بايت الخلو المنتهي) التي كانت ستُكتب في السلسلة النهائية لو توفرت مساحة كافية. وبذلك، فإن القيمة المعادة التي تساوي size أو أكثر تعني أن المخرجات قد بُترت. (انظر أيضًا أدناه تحت التنبيهات CAVEATS.)

عند حدوث خطأ، تُعاد قيمة سالبة، ويُضبط errno للإشارة إلى الخطأ.

الأخطاء¶

انظر printf(3).

السمات¶

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

المعايير¶

C11, POSIX.1-2008.

التاريخ¶

SUSv2, C99, POSIX.1-2001.

بخصوص القيمة المُرجعة، يتعارض SUSv2 وC99 مع بعضهما البعض: عندما يُستدعى snprintf() مع size=0، ينص SUSv2 على قيمة إرجاع غير محددة أقل من 1، بينما يسمح C99 بأن تكون str فارغة (NULL) في هذه الحالة، ويعطي القيمة المُرجعة (كما هو الحال دائمًا) كعدد المحارف التي كانت ستُكتب لو كانت سلسلة الإخراج كبيرة بما يكفي. POSIX.1-2001 والإصدارات الأحدث توائم مواصفاتها لـ snprintf() مع C99.

تحذيرات¶

تعتمد بعض البرامج بتهور على كود مثل الآتي

snprintf(buf, countof(buf), "%s some further text", buf);

لإلحاق نص بـ buf. ومع ذلك، تنص المعايير صراحةً على أن النتائج غير معرفة إذا تداخلت المخازن المؤقتة المصدر والوجهة عند استدعاء snprintf() وvsnprintf(). اعتمادًا على إصدار gcc(1) المستخدم، وخيارات المترجم المُستخدمة، فإن الاستدعاءات مثل المذكور أعلاه لن تُنتج النتائج المتوقعة.

يتوافق تطبيق glibc للدالتين snprintf() وvsnprintf() مع معيار C99، أي أنه يتصرف كما هو موضح أعلاه، وذلك منذ الإصدار glibc 2.1. حتى الإصدار glibc 2.0.6، كانتا تعيدان -1 عند بتر المخرجات.

العلل¶

انظر printf(3).

أمثلة¶

لتخصيص سلسلة كبيرة بما يكفي والطباعة فيها (كود صحيح لكل من glibc 2.0 و glibc 2.1):

#include <stdio.h>
#include <stdlib.h>
#include <stdarg.h>
char *
make_message(const char *fmt, ...)
{


    int n = 0;


    size_t size = 0;


    char *p = NULL;


    va_list ap;


    /* تحديد الحجم المطلوب.  */


    va_start(ap, fmt);


    n = vsnprintf(p, size, fmt, ap);


    va_end(ap);


    if (n < 0)


        return NULL;


    size = (size_t) n + 1;      /* بايت إضافي واحد لـ '\0' */


    p = malloc(size);


    if (p == NULL)


        return NULL;


    va_start(ap, fmt);


    n = vsnprintf(p, size, fmt, ap);


    va_end(ap);


    if (n < 0) {


        free(p);


        return NULL;


    }


    return p;
}

إذا حدث البتر في إصدارات glibc الأقدم من 2.0.6، فيُعامل هذا كخطأ بدلاً من التعامل معه بلباقة.

انظر أيضًا¶

printf(1), asprintf(3), printf(3), puts(3), scanf(3), setlocale(3), strfromd(3), wcrtomb(3), wprintf(3), locale(5)

ترجمة¶

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

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

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