KennisbankExamencentrum
NL · NLNederlands (Nederland)
Taal kiezen13

CKTIS / C

vsnprintf — een va_list formatteren in een begrensde buffer

vsnprintf formatteert argumenten die via een va_list worden aangeleverd. Schrijfbewerkingen blijven binnen de buffercapaciteit; aan de geretourneerde lengte kun je zien of de uitvoer is afgekapt.

Versie: 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 werkt als snprintf, maar accepteert een va_list in plaats van ...-argumenten. Je kunt ermee zelf formatteringsfuncties maken.

n is de buffercapaciteit in bytes, inclusief de afsluitende \0. Bij n > 0 schrijft de functie maximaal n - 1 uitvoerbytes en een afsluiter. Bij n == 0 schrijft ze niets; s mag NULL zijn.

Het resultaat r is de benodigde lengte zonder de afsluiter; een negatieve waarde duidt op een coderingsfout. Controleer eerst r < 0. Als r niet negatief is en n > 0, geeft (unsigned int)r >= n aan dat de uitvoer is afgekapt. Bij conversie naar unsigned int blijft elke niet-negatieve int-waarde behouden, ook als size_t die waarde niet kan weergeven.

Initialiseer de lijst met va_start en sluit die af met va_end; de functie doet dat laatste niet. Gebruik voor een volgende doorgang va_copy voordat je de lijst verbruikt, en sluit ook de kopie af. De argumenttypen moeten overeenkomen met het formaat; overlappende gekopieerde objecten veroorzaken ongedefinieerd gedrag. Geef niet-vertrouwde tekst als gegevens voor %s door, niet als formaat.

Voorbeelden

#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;
}

Resultaat

text=item:12
needed=10
truncated=1

De getoonde code en het opgegeven resultaat zijn in een geïsoleerde omgeving geverifieerd met de methode die in het verificatiebewijs voor exact deze versie is vastgelegd.

Bronnen