C vsnprintf 函数

最后修改日期：2025 年 4 月 6 日

字符串格式化是 C 编程中的核心操作，能够实现动态文本创建。`vsnprintf` 函数提供了一种安全的方式，可以使用可变参数格式化字符串，同时防止缓冲区溢出。本教程将深入解释 `vsnprintf`，将其与不安全的方式进行比较，并提供实用示例。理解这些函数对于编写处理字符串安全、健壮的 C 应用程序至关重要。

什么是 vsnprintf？

`vsnprintf` 函数格式化并存储一个带有可变参数的字符串，与 `snprintf` 类似，但它接受一个 `va_list` 而不是直接的可变参数。它最多写入指定缓冲区大小的字符，从而防止溢出。始终包含 `stdarg.h` 以支持 `va_list`。此函数返回如果缓冲区足够大时会写入的字符数，从而允许进行大小检查。

基本的 vsnprintf 示例

此示例演示了 `vsnprintf` 与自定义格式化函数的根本用法。

basic_vsnprintf.c

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

void format_string(char *buffer, size_t size, const char *fmt, ...) {
    va_list args;
    va_start(args, fmt);
    vsnprintf(buffer, size, fmt, args);
    va_end(args);
}

int main() {
    char buffer[50];
    format_string(buffer, sizeof(buffer), "Hello, %s! You are %d years old.", 
                 "John", 30);
    printf("%s\n", buffer);
    return 0;
}

在此，`format_string` 包装了 `vsnprintf` 以实现更简洁的用法。`va_list` 安全地处理可变参数。明确地传递了缓冲区大小以防止溢出。然后打印格式化后的字符串。这种模式在对安全性至关重要的日志记录或消息格式化函数中很常见。

使用 vsnprintf 安全地格式化字符串

此示例展示了如何安全地格式化字符串，同时防止缓冲区溢出。

safe_formatting.c

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

int safe_format(char *buf, size_t size, const char *fmt, ...) {
    va_list args;
    va_start(args, fmt);
    int result = vsnprintf(buf, size, fmt, args);
    va_end(args);
    
    if (result >= size) {
        // Buffer was too small, truncation occurred
        buf[size - 1] = '\0';
        return -1;
    }
    return result;
}

int main() {
    char small_buf[10];
    if (safe_format(small_buf, sizeof(small_buf), "Long string %d", 12345) == -1) {
        printf("Buffer too small!\n");
    }
    printf("Result: '%s'\n", small_buf);
    return 0;
}

`safe_format` 函数通过将返回值与缓冲区大小进行比较来检查格式化后的字符串是否适合缓冲区。如果发生截断，它会确保正确地以 null 终止，并返回一个错误代码。这演示了 `vsnprintf` 如何帮助防止缓冲区溢出，这是 C 程序中常见的安全漏洞。

构建日志函数

使用 `vsnprintf` 为格式化输出创建一个灵活的日志函数。

logging_function.c

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

void log_message(FILE *stream, const char *format, ...) {
    char buffer[256];
    va_list args;
    
    // Get current time
    time_t now = time(NULL);
    struct tm *tm_info = localtime(&now);
    strftime(buffer, sizeof(buffer), "[%Y-%m-%d %H:%M:%S] ", tm_info);
    fputs(buffer, stream);
    
    // Format the message
    va_start(args, format);
    vsnprintf(buffer, sizeof(buffer), format, args);
    va_end(args);
    
    fputs(buffer, stream);
    fputc('\n', stream);
}

int main() {
    log_message(stdout, "System started with PID: %d", getpid());
    log_message(stderr, "Warning: %s", "Low memory detected");
    return 0;
}

此日志函数结合了时间戳格式化和消息格式化，使用了 `vsnprintf`。固定大小的缓冲区确保了安全性，而可变参数提供了灵活性。该函数可以输出到任何 `FILE` 流，使其可重用于标准输出和错误日志记录。这种模式在生产代码中被广泛使用。

实现字符串构建器

在此高级示例中使用 `vsnprintf` 逐块构建动态字符串。

string_builder.c

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

typedef struct {
    char *buffer;
    size_t size;
    size_t capacity;
} StringBuilder;

void sb_init(StringBuilder *sb, size_t initial_capacity) {
    sb->buffer = malloc(initial_capacity);
    sb->size = 0;
    sb->capacity = initial_capacity;
    if (sb->buffer) sb->buffer[0] = '\0';
}

void sb_appendf(StringBuilder *sb, const char *format, ...) {
    va_list args;
    va_start(args, format);
    
    // Determine required space
    int needed = vsnprintf(NULL, 0, format, args) + 1;
    va_end(args);
    
    // Resize if necessary
    if (sb->size + needed > sb->capacity) {
        size_t new_capacity = sb->capacity * 2;
        while (sb->size + needed > new_capacity) new_capacity *= 2;
        char *new_buffer = realloc(sb->buffer, new_capacity);
        if (!new_buffer) return;
        sb->buffer = new_buffer;
        sb->capacity = new_capacity;
    }
    
    // Actually format the string
    va_start(args, format);
    vsnprintf(sb->buffer + sb->size, sb->capacity - sb->size, format, args);
    va_end(args);
    
    sb->size += needed - 1;
}

int main() {
    StringBuilder sb;
    sb_init(&sb, 64);
    
    sb_appendf(&sb, "User: %s\n", "johndoe");
    sb_appendf(&sb, "Score: %d\n", 95);
    sb_appendf(&sb, "Average: %.2f\n", 87.5);
    
    printf("%s", sb.buffer);
    free(sb.buffer);
    return 0;
}

此字符串构建器实现使用了两次 `vsnprintf`：第一次使用 NULL 缓冲区来测量所需空间，然后实际格式化字符串。动态缓冲区在需要时增长，防止溢出同时保持效率。这种方法在构建来自多个组件的复杂字符串时非常有用，例如在模板引擎或序列化代码中。

错误处理包装器

创建一个健壮的错误处理函数，该函数可以安全地格式化错误消息。

error_handler.c

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

void set_error(char *err_buf, size_t err_size, int err_code, 
              const char *format, ...) {
    char message[256];
    va_list args;
    
    // Format the custom message
    va_start(args, format);
    vsnprintf(message, sizeof(message), format, args);
    va_end(args);
    
    // Include system error if applicable
    if (err_code != 0) {
        vsnprintf(err_buf, err_size, "%s: %s", message, strerror(err_code));
    } else {
        vsnprintf(err_buf, err_size, "%s", message);
    }
}

int main() {
    char error_message[256];
    FILE *fp = fopen("nonexistent.txt", "r");
    
    if (fp == NULL) {
        set_error(error_message, sizeof(error_message), errno,
                "Failed to open file");
        fprintf(stderr, "Error: %s\n", error_message);
        return 1;
    }
    
    fclose(fp);
    return 0;
}

此错误处理函数使用 `vsnprintf` 安全地结合了自定义消息和系统错误信息。严格强制执行缓冲区大小以防止溢出。该函数同时处理自定义格式的消息和系统错误（当 `err_code` 非零时）。这种模式在库代码中特别有用，其中错误报告既需要灵活又安全。

为什么选择 vsnprintf 而不是 vsprintf？

缓冲区安全：`vsnprintf` 通过限制写入到缓冲区大小来防止溢出。
截断检测：返回值指示输出是否被截断。
安全性：消除了缓冲区溢出漏洞的风险。
可预测行为：始终以 null 终止输出字符串。
现代实践：在 CERT C 等安全编码标准中推荐。

vsnprintf 的最佳实践

始终检查返回值：通过检查返回值来检测截断或错误。
包含 null 终止符：请记住 `vsnprintf` 需要为 null 字节留出空间。
堆栈缓冲区使用 sizeof：`sizeof(buffer)` 比硬编码大小更安全。
考虑两趟方法：先使用 NULL 缓冲区调用以确定所需大小。
验证输入：检查 NULL 指针或无效的格式字符串。

来源

C vsnprintf 文档

本教程深入探讨了 `vsnprintf` 函数，展示了它在 C 中进行安全字符串格式化的重要性。从基本用法到字符串构建器和错误处理程序等高级模式，`vsnprintf` 为安全文本处理提供了强大的基础。

作者

我叫 Jan Bodnar，是一名敬业的程序员，对编码充满热情。自 2007 年以来，我通过 1,400 多篇文章和 8 本电子书分享了我的专业知识。凭借十多年的教学经验，我努力使编程变得易于理解且引人入胜。

列表 C 标准库。