BEZEICHNUNG¶

snprintf, vsnprintf - Formatierte Zeichenkettenausgabe

BIBLIOTHEK¶

Standard-C-Bibliothek (libc, -lc)

ÜBERSICHT¶

#include <stdio.h>

int snprintf(size_t Größe;
            char zk[restrict Größe], size_t Größe,
            const char *restrict Format, …);
int vsnprintf(size_t Größe;
            char zk[restrict Größe], size_t Größe,
            const char *restrict Format, va_list ap);

snprintf(), vsnprintf():

    _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE


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

BESCHREIBUNG¶

Diese Funktionen sind printf(3) ähnlich, außer dass sie in die Zeichenkette zk anstatt in einen Datenstrom schreiben.

Die Funktionen snprintf() und vsnprintf() schreiben höchstens Größe byte (einschließlich des abschließenden Nullbytes (»\0«)) nach zk.

vsnprintf() ist zu snprintf() äquivalent, außer dass es mit einer va_list statt einer variablen Zahl von Argumenten aufgerufen wird. Diese Funktion ruft das Makro va_end nicht auf. Da es das Makro va_arg aufruft, ist der Wert von ap nach dem Aufruf nicht definiert. Siehe stdarg(3).

C99 und POSIX.1-2001 legen fest, dass das Ergebnis nicht definiert ist, wenn ein Aufruf von snprintf() oder vsnprintf() zu einem Kopieren zwischen überlappenden Objekten führen würde (z.B. wenn das Zielzeichenkettenfeld und eines der übergebenen Eingabe-Argumente sich auf den gleichen Puffer beziehen). Siehe WARNUNGEN.

RÜCKGABEWERT¶

Nach erfolgreicher Ausführung geben diese Funktionen die Anzahl der ausgegebenen Bytes zurück (ohne das für den Abschluß der Zeichenkettenausgabe verwendete Nullbyte).

Die Funktionen snprintf() und vsnprintf() schreiben nicht mehr als Größe byte (einschließlich des abschließenden Nullbytes »\0«)). Falls die Ausgabe wegen dieser Begrenzung gekürzt wurde, ist der Rückgabewert die Anzahl der Zeichen (ohne abschließendes Nullbyte), die bei ausreichendem Speicherplatz in die Ausgabe geschrieben worden wären. Damit bedeutet ein Rückgabewert von Größe oder mehr, dass die Ausgabe gekürzt wurde. (Siehe auch im Folgenden unter WARNUNGEN.)

Bei einem Fehler wird ein negativer Wert zurückgegeben und errno wird gesetzt, um den Fehler anzuzeigen.

FEHLER¶

Siehe printf(3).

ATTRIBUTE¶

Siehe attributes(7) für eine Erläuterung der in diesem Abschnitt verwandten Ausdrücke.

STANDARDS¶

C11, POSIX.1-2008.

GESCHICHTE¶

SUSv2, C99, POSIX.1-2001.

Bezüglich des Rückgabewertes widersprechen sich SUSv2 und C99: Wird snprintf() mit size=0 aufgerufen, dann fordert SUSv2 einen nicht festgelegten Wert kleiner als 1, während C99 erlaubt, dass zk in diesem Fall NULL ist und beschreibt den Rückgabewert (wie üblich) als die Anzahl der Zeichen, die geschrieben worden wären, falls die Ausgabezeichenkette groß genug gewesen wäre. POSIX.1-2001 und neuere richten ihre Spezifikation von snprintf() an C99 aus.

WARNUNGEN¶

Einige Programme verlassen sich leichtsinnig auf Code wie den folgenden

snprintf(puf, countof(puf), "%s weiterer Text", puf);

um Text an puf anzuhängen. Allerdings vermerken die Standards explizit, dass die Ergebnisse nicht definiert sind, falls sich die Quell- und Zielpuffer beim Aufruf von snprintf() und vsnprintf() überlappen. Abhängig von der verwandten Version von gcc(1) und den eingesetzten Compiler-Optionen werden Aufrufe wie der vorstehende nicht die erwarteten Ergebnisse liefern.

Seit der Glibc-Version 2.1 ist die Implementierung der Funktionen snprintf() und vsnprintf() konform zu C99, verhält sich also wie oben beschrieben. Bis Glibc 2.0.6 gaben sie im Fall gekürzter Ausgaben -1 zurück.

FEHLER¶

Siehe printf(3).

BEISPIELE¶

Um eine genügend große Zeichenkette bereitzustellen und in sie zu schreiben (der Code ist korrekt sowohl für Glibc 2.0 als auch 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;


    /* Benötigte Größe bestimomen.  */


    va_start(ap, fmt);


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


    va_end(ap);


    if (n < 0)


        return NULL;


    size = (size_t) n + 1;      /* Ein zusätzliches Byte für »\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;
}

Bei Kürzungen in Glibc-Versionen vor 2.0.6 wird dies als ein Fehler aufgefasst und nicht wohlwollend behandelt.

SIEHE AUCH¶

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

ÜBERSETZUNG¶

Die deutsche Übersetzung dieser Handbuchseite wurde von Helge Kreutzmann <debian@helgefjell.de> erstellt.

Diese Übersetzung ist Freie Dokumentation; lesen Sie die GNU General Public License Version 3 oder neuer bezüglich der Copyright-Bedingungen. Es wird KEINE HAFTUNG übernommen.

Wenn Sie Fehler in der Übersetzung dieser Handbuchseite finden, schicken Sie bitte eine E-Mail an die Mailingliste der Übersetzer.