WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / C

vsnprintf — eine va_list in einen begrenzten Puffer formatieren

vsnprintf formatiert Argumente, die über eine va_list übergeben werden. Die Schreibvorgänge werden auf die Pufferkapazität begrenzt; anhand der zurückgegebenen Länge lässt sich eine gekürzte Ausgabe erkennen.

Version: C23; repository compiler flag, production runtime not attested

Syntax

#include <stdarg.h>
#include <stdio.h>
int vsnprintf(char * restrict s, size_t n, const char * restrict format, va_list arg);

vsnprintf funktioniert wie snprintf, nimmt aber statt ...-Argumenten eine va_list entgegen. Damit lassen sich eigene Formatierungsfunktionen erstellen.

n ist die Pufferkapazität in Bytes, einschließlich des abschließenden \0. Für n > 0 werden höchstens n - 1 Ausgabebytes und ein Abschlusszeichen geschrieben. Für n == 0 wird nichts geschrieben; s darf NULL sein.

Das Ergebnis r ist die benötigte Länge ohne Abschlusszeichen; ein negativer Wert weist auf einen Kodierungsfehler hin. Prüfe zuerst r < 0. Ist r nichtnegativ und gilt n > 0, zeigt (unsigned int)r >= n an, dass die Ausgabe gekürzt wurde. Bei der Umwandlung in unsigned int bleibt jeder nichtnegative int-Wert erhalten, auch wenn size_t ihn nicht darstellen kann.

Initialisiere die Liste mit va_start und schließe sie mit va_end ab; die Funktion erledigt Letzteres nicht. Für einen weiteren Durchlauf verwende va_copy, bevor du die Liste verbrauchst, und schließe auch die Kopie ab. Die Argumenttypen müssen zum Format passen; sich überlappende kopierte Objekte führen zu undefiniertem Verhalten. Übergib nicht vertrauenswürdigen Text als Daten für %s, nicht als Format.

Beispiele

#include <stdarg.h>
#include <stdio.h>

static int format_to(char *dst, size_t cap, const char *fmt, ...)
{
    va_list args;
    va_start(args, fmt);
    int result = vsnprintf(dst, cap, fmt, args);
    va_end(args);
    return result;
}

int main(void)
{
    char buf[8];
    int result = format_to(buf, sizeof buf, "%s:%d", "item", 12345);
    if (result < 0) {
        return 1;
    }
    printf("text=%s\nneeded=%d\ntruncated=%d\n",
           buf, result, (unsigned int)result >= sizeof buf);
    return 0;
}

Ergebnis

text=item:12
needed=10
truncated=1

Der angezeigte Code und das angegebene Ergebnis wurden in einer isolierten Umgebung mit der im Prüfnachweis für genau diese Version dokumentierten Methode verifiziert.

Quellen