Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / C

vsnprintf — formatar uma va_list num buffer de capacidade limitada

vsnprintf formata argumentos fornecidos através de uma va_list. Limita as escritas à capacidade do buffer, e o comprimento devolvido permite detetar uma saída truncada.

Versão: C23; repository compiler flag, production runtime not attested

Sintaxe

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

vsnprintf funciona como snprintf, mas aceita uma va_list em vez de argumentos .... Pode ser usada para criar funções próprias de formatação.

n é a capacidade do buffer em bytes, incluindo o \0 final. Para n > 0, escreve no máximo n - 1 bytes de saída e um terminador. Para n == 0, não escreve nada; s pode ser NULL.

O resultado r é o comprimento necessário sem o terminador; um valor negativo indica um erro de codificação. Verifique primeiro r < 0. Se r não for negativo e n > 0, a condição (unsigned int)r >= n indica que a saída foi truncada. A conversão para unsigned int preserva qualquer valor não negativo do tipo int, mesmo que size_t não o consiga representar.

Inicialize a lista com va_start e termine-a com va_end; a função não faz esta última operação. Para uma nova passagem, use va_copy antes de consumir a lista e termine também a cópia. Os tipos dos argumentos têm de corresponder ao formato; objetos copiados sobrepostos provocam comportamento indefinido. Passe texto não fiável como dados para %s, não como formato.

Exemplos

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

Resultado

text=item:12
needed=10
truncated=1

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes