snprintf | Programming Place Plus　Ｃ言語編　標準ライブラリのリファレンス

トップページ – Ｃ言語編 – 標準ライブラリのリファレンス（名前順）

トップページ – Ｃ言語編 – 標準ライブラリのリファレンス（ヘッダ別）

snprintf関数

概要 文字の配列へ、変換指定に沿って変換された文字列を、指定文字数以下だけ出力する。
ヘッダ stdio.h
形式 int snprintf(char* restrict s, size_t n, const char* restrict format, …);
引数 s

結果を格納する配列を指すポインタ。

引数n が 0 の場合に限って、ヌルポインタでも構わない。
n

s に書き込む最大文字数。終端に書き込まれる ‘\0’ を含めた文字数である。

0 を指定することはできるが、この場合は何も書き込まれない。
format 変換指定を含んだ、あるいは含まないプレーンな文字列。
… format に含まれている変換指定子に対応した個数のパラメータ。
戻り値

実際に書き込まれたはずの文字数（末尾のヌル文字は除く）を返す。つまり、変換指定を行った結果の文字列の長さが、引数n の値以上になった場合、引数n による制限によって書き込まれなかった部分の長さも含めて返される。

変換に関するエラーが発生した場合は、負数を返す。
詳細

書き込む最大文字数を指定することを除いて、sprintf関数と同じ機能を持つ。最大文字数を指定できることで、バッファオーバーフローを防止できるが、完全に防ぐためには、使い方に若干の注意を要する（「注意」のところで解説する）。

変換指定を行い生成された文字列のうち、「引数n の値 - 1」文字目までが、引数s で示した配列に格納され、末尾に ‘\0’ が付加される。

引数n が 0 の場合は、‘\0’ も含め、何も書き込まない。この場合は、引数 s はヌルポインタであっても構わない。
注意

必要な個数の実引数が指定されていない場合は、未定義の動作となる。余分に指定されている場合には、その実引数の評価は行われるが、snprintf関数としては無視する。

バッファオーバーフローの備えがない sprintf関数と比べると、この関数は安全性が増しているが、その安全性を得るために、引数n に、引数s が示す配列の実際の要素数（あるいはそれ以下の値）を指定するように注意しなければならない。引数n が実際の要素数より大きく、かつ、%d などを変換したあとの文字列の長さが、書き込み先の配列の要素数よりも長くなる場合には、バッファオーバーフローは起こる。安全のためには、sizeof を使うなどして、配列の要素数を確実に渡す（たとえば、snprintf(s, sizeof(s), "%d", x); のように）。ただし、s が動的メモリ割り当てで確保された配列を指すポインタになっている場合など、sizeof(s) とはできないケースに注意すること。
使用例 
#include <stdio.h>

int main(void)
{
    char str[5];

    int n = snprintf(str, sizeof(str), "%d", 1234);
    if (n < 0) {
        fputs("error\n", stderr);
    }
    else if (n >= sizeof(str)) {
        puts("truncated");
    }
    else {
        puts(str);
    }

    n = snprintf(str, sizeof(str), "%d", 1234567890);
    if (n < 0) {
        fputs("error\n", stderr);
    }
    else if (n >= sizeof(str)) {
        puts("truncated");
    }
    else {
        puts(str);
    }

// 以下のように、書き込み先の配列の実際の要素数よりも、第２引数が大きいのは危険である。
//  snprintf(str, 8, "%d", 99999999);
//  puts(str);
}

実行結果：

1234
truncated
関連

この関数のワイド文字版は直接的に対応するものはないが、swprintf関数 が近い。戻り値の意味などに違いがあることに注意。

引数に … ではなく、va_list を用いたバージョンとして、vsnprintf関数がある。
解説章


参考リンク


更新履歴

’2018/4/20　「NULL」という表記を「ヌルポインタ」に修正。

’2018/4/15　バッファオーバーフローに関する説明を大幅に追加した。

’2018/4/5　VisualStudio 2013 の対応終了。

’2018/4/2　「VisualC++」という表現を「VisualStudio」に統一。

’2018/2/1　Ｃ言語編全体で表記を統一するため、「フォーマット指定」を「変換指定」に改めた。

’2018/1/22　新規作成。


標準ライブラリのリファレンス（名前順）のトップページへ

標準ライブラリのリファレンス（ヘッダ別）のトップページへ

Ｃ言語編のトップページへ

Programming Place Plus のトップページへ

はてなブックマーク に保存 Pocket に保存 Facebook でシェア
Twitter でツイート Twitter をフォロー LINE で送る
rss1.0 取得ボタン RSS 管理者情報 プライバシーポリシー
先頭へ戻る