Znalostní bázeCentrum zkoušek
CSČeština
Vybrat jazyk13

CKTIS / C

vsnprintf — formátování va_list do omezeného bufferu

vsnprintf formátuje argumenty předané prostřednictvím va_list. Omezuje zápis podle kapacity bufferu a vrácená délka umožňuje zjistit, zda byl výstup zkrácen.

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

Syntaxe

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

vsnprintf funguje jako snprintf, ale místo argumentů ... přijímá va_list. Používá se k vytváření vlastních formátovacích funkcí.

n je kapacita bufferu v bajtech včetně závěrečného \0. Pro n > 0 zapíše nejvýše n - 1 bajtů výstupu a ukončovací znak. Pro n == 0 nezapíše nic; s může být NULL.

Výsledek r je potřebná délka bez ukončovacího znaku; záporná hodnota značí chybu kódování. Nejprve zkontrolujte r < 0. Pokud je r nezáporné a platí n > 0, podmínka (unsigned int)r >= n znamená, že byl výstup zkrácen. Převod na unsigned int zachová každou nezápornou hodnotu typu int, i když ji typ size_t nedokáže reprezentovat.

Seznam inicializujte pomocí va_start a ukončete pomocí va_end; funkce druhý krok neprovádí. Pro další průchod použijte va_copy před spotřebováním seznamu a ukončete i kopii. Typy argumentů musí odpovídat formátu; překrývající se kopírované objekty způsobují nedefinované chování. Nedůvěryhodný text předávejte jako data pro %s, nikoli jako formát.

Příklady

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

Výsledek

text=item:12
needed=10
truncated=1

Zobrazený kód a uvedený výsledek byly ověřeny v izolovaném prostředí metodou zaznamenanou v dokladu o ověření této přesné verze.

Zdroje