Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

CKTIS / C

vsnprintf — formatowanie z va_list do bufora o ograniczonej pojemności

vsnprintf formatuje argumenty przekazane przez va_list. Ogranicza zapis do pojemności bufora, a zwracana długość pozwala wykryć obcięcie wyniku.

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

Składnia

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

vsnprintf działa jak snprintf, lecz przyjmuje va_list zamiast argumentów .... Służy do tworzenia własnych funkcji formatujących.

n oznacza pojemność bufora w bajtach, łącznie z końcowym \0. Dla n > 0 zapisuje najwyżej n - 1 bajtów wyniku i terminator. Dla n == 0 nic nie zapisuje; s może być NULL.

Wynik r to potrzebna długość bez terminatora; wartość ujemna oznacza błąd kodowania. Najpierw sprawdź r < 0. Jeśli r jest nieujemne i n > 0, warunek (unsigned int)r >= n oznacza obcięcie wyniku. Konwersja do unsigned int zachowuje każdą nieujemną wartość int, nawet gdy size_t nie może jej reprezentować.

Zainicjalizuj listę przez va_start i zakończ przez va_end; funkcja nie robi tego ostatniego. Do kolejnego przebiegu użyj va_copy przed zużyciem listy i zakończ także kopię. Typy argumentów muszą odpowiadać formatowi; nakładanie kopiowanych obiektów powoduje niezdefiniowane zachowanie. Niezaufany tekst przekazuj jako dane dla %s, nie jako format.

Przykłady

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

Wynik

text=item:12
needed=10
truncated=1

Wyświetlony kod i zadeklarowany wynik zweryfikowano w odizolowanym środowisku metodą zapisaną w dowodzie weryfikacji tej dokładnej wersji.

Źródła