.\" -*- coding: UTF-8 -*- '\" t .\" Copyright, the authors of the Linux man-pages project .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH snprintf 3 "7 ديسمبر 2025" "صفحات دليل لينكس 6.18" .SH الاسم snprintf, vsnprintf \- طباعة سلسلة محارف منسقة .SH المكتبة مكتبة سي المعيارية (\fIlibc\fP،\ \fI\-lc\fP) .SH موجز .nf \fB#include \fP .P \fBint snprintf(\fPsize_t size; \fB char \fP\fIstr\fP\fB[restrict \fP\fIsize\fP\fB], size_t \fP\fIsize\fP\fB,\fP \fB const char *restrict \fP\fIformat\fP\fB, ...);\fP \fBint vsnprintf(\fPsize_t size; \fB char \fP\fIstr\fP\fB[restrict \fP\fIsize\fP\fB], size_t \fP\fIsize\fP\fB,\fP \fB const char *restrict \fP\fIformat\fP\fB, va_list \fP\fIap\fP\fB);\fP .fi .P .RS -4 متطلبات ماكروات اختبار الميزات لـ glibc (انظر \fBfeature_test_macros\fP(7)): .RE .P \fBsnprintf\fP(), \fBvsnprintf\fP(): .nf _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE .fi .SH الوصف هذه الدوال مشابهة لـ \fBprintf\fP(3)، باستثناء أنها تكتب إلى سلسلة المحارف \fIstr\fP بدلاً من تيار. .P تكتب الدالتان \fBsnprintf\fP() و\fBvsnprintf\fP() على الأكثر \fIsize\fP بايت (بما في ذلك بايت الخلو المنتهي (\[aq]\[rs]0\[aq])) إلى \fIstr\fP. .P \fBvsnprintf\fP() مكافئة لـ \fBsnprintf\fP()، باستثناء أنها تُستدعى مع \fIva_list\fP بدلاً من عدد متغير من المعاملات. هذه الدالة لا تستدعي ماكرو \fIva_end\fP. نظرًا لأنها تستدعي ماكرو \fIva_arg\fP، فإن قيمة \fIap\fP تكون غير معرفة بعد الاستدعاء. انظر \fBstdarg\fP(3). .P C99 وPOSIX.1\-2001 يحددان أن النتائج غير معرفة إذا تسبب استدعاء \fBsnprintf\fP() أو \fBvsnprintf\fP() في نسخ بين كائنات متداخلة (مثلًا، إذا كانت مصفوفة السلسلة الهدف وأحد معاملات الإدخال المقدمة تشير إلى نفس المخزن المؤقت). انظر تحذيرات. .SS "تنسيق سلسلة التنسيق" انظر \fBprintf\fP(3). .SH "قيمة الإرجاع" عند العودة بنجاح، تعيد هذه الدوال عدد البايتات المطبوعة (باستثناء بايت الخلو المستخدم لإنهاء المخرجات إلى السلاسل النصية). .P لا تكتب الدالتان \fBsnprintf\fP() و\fBvsnprintf\fP() أكثر من \fIsize\fP بايت (بما في ذلك بايت الخلو المنتهي (\[aq]\[rs]0\[aq])). إذا بُترت المخرجات بسبب هذا الحد، فإن القيمة المعادة هي عدد المحارف (باستثناء بايت الخلو المنتهي) التي كانت ستُكتب في السلسلة النهائية لو توفرت مساحة كافية. وبذلك، فإن القيمة المعادة التي تساوي \fIsize\fP أو أكثر تعني أن المخرجات قد بُترت. (انظر أيضًا أدناه تحت التنبيهات CAVEATS.) .P عند حدوث خطأ، تُعاد قيمة سالبة، ويُضبط \fIerrno\fP للإشارة إلى الخطأ. .SH الأخطاء انظر \fBprintf\fP(3). .SH السمات للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر \fBattributes\fP(7). .TS allbox; lbx lb lb l l l. الواجهة السمة القيمة T{ .na .nh \fBsnprintf\fP()، \fBvsnprintf\fP() T} سلامة الخيوط المنطقة (locale) آمنة لتعدد المسالك (MT\-Safe) .TE .SH المعايير C11, POSIX.1\-2008. .SH التاريخ SUSv2, C99, POSIX.1\-2001. .IP بخصوص القيمة المُرجعة، يتعارض SUSv2 وC99 مع بعضهما البعض: عندما يُستدعى \fBsnprintf\fP() مع \fIsize\fP=0، ينص SUSv2 على قيمة إرجاع غير محددة أقل من 1، بينما يسمح C99 بأن تكون \fIstr\fP فارغة (NULL) في هذه الحالة، ويعطي القيمة المُرجعة (كما هو الحال دائمًا) كعدد المحارف التي كانت ستُكتب لو كانت سلسلة الإخراج كبيرة بما يكفي. POSIX.1\-2001 والإصدارات الأحدث توائم مواصفاتها لـ \fBsnprintf\fP() مع C99. .SH تحذيرات تعتمد بعض البرامج بتهور على كود مثل الآتي .P .in +4n .EX snprintf(buf, countof(buf), "%s some further text", buf); .EE .in .P .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7075 لإلحاق نص بـ \fIbuf\fP. ومع ذلك، تنص المعايير صراحةً على أن النتائج غير معرفة إذا تداخلت المخازن المؤقتة المصدر والوجهة عند استدعاء \fBsnprintf\fP() و\fBvsnprintf\fP(). اعتمادًا على إصدار \fBgcc\fP(1) المستخدم، وخيارات المترجم المُستخدمة، فإن الاستدعاءات مثل المذكور أعلاه \fBلن\fP تُنتج النتائج المتوقعة. .P .\" .SH HISTORY .\" UNIX V7 defines the three routines .\" .BR sprintf (). .\" 2.11BSD has .\" .BR vsprintf (). .\" 4.4BSD introduces the functions .\" .BR snprintf () .\" and .\" .BR vsnprintf (). .\" FreeBSD also has functions .\" .BR asprintf () .\" and .\" .BR vasprintf (), .\" that allocate a buffer large enough for .\" .BR sprintf (). يتوافق تطبيق glibc للدالتين \fBsnprintf\fP() و\fBvsnprintf\fP() مع معيار C99، أي أنه يتصرف كما هو موضح أعلاه، وذلك منذ الإصدار glibc 2.1. حتى الإصدار glibc 2.0.6، كانتا تعيدان \-1 عند بتر المخرجات. .SH العلل انظر \fBprintf\fP(3). .SH أمثلة لتخصيص سلسلة كبيرة بما يكفي والطباعة فيها (كود صحيح لكل من glibc 2.0 و glibc 2.1): .P .EX #include #include #include \& 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; /* بايت إضافي واحد لـ \[aq]\[rs]0\[aq] */ 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; } .EE .P إذا حدث البتر في إصدارات glibc الأقدم من 2.0.6، فيُعامل هذا كخطأ بدلاً من التعامل معه بلباقة. .SH "انظر أيضًا" \fBprintf\fP(1), \fBasprintf\fP(3), \fBprintf\fP(3), \fBputs\fP(3), \fBscanf\fP(3), \fBsetlocale\fP(3), \fBstrfromd\fP(3), \fBwcrtomb\fP(3), \fBwprintf\fP(3), \fBlocale\fP(5) .PP .SH ترجمة تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي . .PP هذه الترجمة هي وثيقة مجانية؛ راجع .UR https://www.gnu.org/licenses/gpl-3.0.html رخصة جنو العامة الإصدار 3 .UE أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات. .PP إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: .MT kde-l10n-ar@kde.org .ME .