Provided by: manpages-ja-dev_0.5.0.0.20221215+dfsg-1_all bug

名前

       printf,  fprintf,  dprintf,  sprintf,  snprintf,  vprintf,  vfprintf,  vdprintf, vsprintf,
       vsnprintf - 指定された書式に変換して出力を行う

書式

       #include <stdio.h>

       int printf(const char *format, ...);
       int fprintf(FILE *stream, const char *format, ...);
       int dprintf(int fd, const char *format, ...);
       int sprintf(char *str, const char *format, ...);
       int snprintf(char *str, size_t size, const char *format, ...);

       #include <stdarg.h>

       int vprintf(const char *format, va_list ap);
       int vfprintf(FILE *stream, const char *format, va_list ap);
       int vdprintf(int fd, const char *format, va_list ap);
       int vsprintf(char *str, const char *format, va_list ap);
       int vsnprintf(char *str, size_t size, const char *format, va_list ap);

   glibc 向けの機能検査マクロの要件 (feature_test_macros(7)  参照):

       snprintf(), vsnprintf():
           _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE ||
               || /* Glibc versions <= 2.19: */ _BSD_SOURCE

       dprintf(), vdprintf():
           glibc 2.10 以降:
               _POSIX_C_SOURCE >= 200809L
           glibc 2.10 より前:
               _GNU_SOURCE

説明

       printf()  関数グループは、以下で述べるように、  format  に従って出力を生成するものである。
       printf()   と  vprintf()   は出力を stdout (標準出力ストリーム) に書き出す。 fprintf()  と
       vfprintf()  は出力を指定された出力 stream に書き出す。 sprintf(), snprintf(),  vsprintf(),
       vsnprintf()  は出力を文字列 str に書き込む。

       dprintf()  関数は  fprintf(3) 関数と同じだが、 この関数は stdio ストリームではなくファイル
       ディスクリプター fd に対して出力を行う点が異なる。

       snprintf()  と vsnprintf()  は最大で size バイトを str に書き込む (size には文字列を終端す
       るヌルバイト ('\0') もを含まれる)。

       vprintf(),  vfprintf(),  vdprintf(),  vsprintf(), vsnprintf() の各関数はそれぞれ printf(),
       fprintf(), dprintf(),  sprintf(),  snprintf(),  の各関数と等価であり、可変数引数の代わりに
       va_list  を引数として呼び出される点だけが異なる。 これらの関数では va_end マクロは呼び出さ
       れない。  これらの関数は  va_arg  を呼び出すので、呼び出し後の   ap   の値は未定義である。
       stdarg(3)  を参照のこと。

       これらの関数はすべて format 文字列の制御に従って出力を書き出す。 format 文字列は、これに続
       く引数 (または stdarg(3)  の可変長引数機構を使ってアクセスできる引数)   をどのように変換し
       て出力するかを指定する。

       C99  と  POSIX.1-2001  では、  sprintf(),  snprintf(), vsprintf(), vsnprintf()  の呼び出し
       で、範囲が重複するオブジェクト間でコピーが発生する場合の  結果は不定であると規定されている
       (例えば、出力先の文字列と入力された   引数の一つが同じバッファーを参照している場合などであ
       る)。 「注意」の節を参照。

   フォーマット文字列のフォーマット
       フォーマット文字列は文字の列で、 (もしあるなら) 初期シフト状態で始まり、初期シフト状態で終
       わる。  フォーマット用の文字列は  0  個以上の命令 (directives) によって構成される。 命令に
       は、通常文字と変換指定 (conversion specifications) がある。 通常文字は %  以外の文字で、出
       力ストリームにそのままコピーされる。  変換指定は、それぞれが 0 個以上の引数を取る。 各変換
       指定は文字 % で始まり、 変換指定子 (conversion specifier) で終わる。 %  と変換指定子の間に
       は、0  個以上の フラグ  最小 フィールド幅  精度  長さ修飾子 を (この順序で) 置くこと
       ができる。

       The arguments  must  correspond  properly  (after  type  promotion)  with  the  conversion
       specifier.   By  default,  the  arguments are used in the order given, where each '*' (see
       Field width and Precision below) and each conversion specifier asks for the next  argument
       (and  it  is  an  error if insufficiently many arguments are given).  One can also specify
       explicitly which argument is taken, at each  place  where  an  argument  is  required,  by
       writing "%m$" instead of '%' and "*m$" instead of '*', where the decimal integer m denotes
       the position in the argument list of the desired argument, indexed starting from 1.  Thus,

           printf("%*d", width, num);

       と

           printf("%2$*1$d", width, num);

       は等価である。 二番目の書き方では同じ引数を繰り返し参照することができる。  C99  標準には、
       Single UNIX Specification 由来の '$' を使った書き方は含まれていない。 '$' を使ったスタイル
       を使うと、引数を取る変換及び幅と精度の引数を  全てこのスタイルで指定しなければならないが、
       引数を消費しない  "%%" フォーマットと混ざっているかもしれない。 '$' で指定される引数の番号
       に空きがあってはならない。 例えば、もし引数 1 と 3 が指定されると、引数 2 もフォーマット文
       字列のどこかで 指定されなければならない。

       数値変換には小数点や  1000  単位の区切り文字を使うものもある。  実際にどの文字を使うかはロ
       ケールの LC_NUMERIC による (setlocale(3) 参照)。 POSIX ロケールでは小数点に  '.'  を用い、
       区切り文字は使わない。 従って、

           printf("%'.2f", 1234567.89);

       は、 POSIX ロケールでは "1234567.89" 、 nl_NL ロケールでは "1234567,89"、 da_DK ロケールで
       は "1.234.567,89" となる。

   フラグ文字
       % 文字の後ろには 0 個以上のフラグ文字が続く。

       #      値は「別の形式」に変換される。 o 変換の場合、(先頭文字が 0 になっていない場合に先頭
              に 0 を追加することで)  出力文字列の最初の文字を 0 にする。 xX 変換の場合、数値
              が 0 でないときには文字列 "0x" (X 変換の場合には "0X") が前に付与される。 a, A,  e,
              E,  f, F, g, G 変換では、 小数点に続く数字がなくても、 出力には常に小数点が含まれる
              (通常は、小数点の後に数字が続く場合にのみ、 小数点が表示される)。 gG  変換の場
              合、他の変換とは異なり、末尾のゼロが変換結果から削除されない。 その他の変換では、結
              果は未定義である。

       0      値をゼロで埋める。 d, i, o, u, x, X, a, A, e, E, f, F, g, G  変換では、変換した値の
              左側を空白文字の代わりにゼロで埋める。 0- が両方とも指定された場合は、 0 フラグ
              は無視される。 精度が数値変換 (d, i, o, u, x, X) と同時に指定された場合には、 0  フ
              ラグは無視される。 その他の変換では、動作は未定義である。

       -      変換値をフィールド境界で左揃えにする (デフォルトは右揃えである)。 変換された値は 左
              側ではなく右側を空白文字やゼロで埋められる。 -0 の両方が指定された場合には、  -
              が優先される。

       ' '    (1個の半角スペース)  符号付き変換で生成された正の数字の前に空白 (または空文字列) が
              置かれる。

       +      符号付き変換によって出力される数字の前に、常に符号 (+ か -) が置かれる。 デフォルト
              では、符号は負の数字の場合のみ付与される。  + と半角スペースの 両方が使われている場
              合には、 + が優先される。

       上記の 5 つのフラグは C99 標準で定義されている。 Single UNIX Specified  では、さらにもう一
       つフラグ文字が規定されている。

       '      10進数変換  (i, d, u, f, F, g, G)  において、ロケール情報に指定があれば 1000 単位の
              区切り文字を出力する (setlocale(3)  参照)。  gcc(1)  の多くのバージョンは、このオプ
              ションを解釈することができず、  警告を出力することに注意せよ。 (%'F は SUSv2 には含
              まれていなかったが、 SUSv3 で追加された。

       glibc 2.2 では、さらに一つフラグ文字が追加されている。

       I      10進整数変換 (i, d, u)   において、ロケールの代替出力数字があれば、それを用いて出力
              する。  例えば、  glibc  2.2.3 以降では、ペルシア ("fa_IR") ロケールで アラビア数字
              (Arabic-Indic digits) を出力できる。

   フィールド幅
       最小のフィールド幅を指定する 10進数の数値文字列 (文字列の最初の文字は  ゼロ以外)。本項目は
       オプションである。 変換された値の文字数がフィールド長よりも少ない場合、 フィールドの左側を
       スペースで埋める (左揃えのフラグがある場合は右側を埋める)。  10進数の文字列の代わりに  "*"
       や "*m$" (m は 10進整数) を書くこともできる。 "*" と "*m$" はそれぞれ、次の引数と m 番目の
       引数をフィールド幅として 使うことを指定する  (これらの引数は  int  型でなければならない)。
       フィールド幅に負の数が指定された場合は、  '-' フラグと正の数のフィールド幅として扱われる。
       フィールド幅が小さかったり指定がなかったりしても、フィールドが切り詰められる      ことはな
       い。もし変換結果がフィールド幅よりも広かった場合、  フィールドは変換結果が入る幅に広げられ
       る。

   精度
       オプションである精度は、ピリオド ('.') とそれに続く10進数という 形式で指定する (10進数はオ
       プション)  。  10進数の文字列の代わりに  "*" や "*m$" (m は 10 進整数)を書くこともできる。
       "*" と "*m$" はそれぞれ、次の引数と m 番目の引数を精度として 使うことを指定する  (これらの
       引数は  int 型でなければならない)。 精度として '.' だけが指定された場合、 精度はゼロとみな
       される。 精度が負の数だった場合、 精度は指定されなかったものとみなされる。 d, i, o, u,  x,
       X 変換では、表示される最小の桁数を指定する。 a, A, e, E, f, F 変換では、小数点以下に表示さ
       れる数字の桁数を指定する。 gG 変換では、有効数字の最大桁数を指定する。 sS  変換で
       は、文字列から出力される最大文字数を指定する。

   長さ修飾子
       「整数変換」とは、 d, i, o, u, x, X 変換のことである。

       hh     整数変換に対応する引数が  signed  charunsigned char で、 n 変換に対応する引数が
              signed char へのポインターであることを示す。

       h      整数変換に対応する引数が shortunsigned short で、 n 変換に対応する引数が  short
              へのポインターであることを示す。

       l      各変換に対応する引数が、  整数変換では longunsigned longn 変換では long への
              ポインター、 c 変換では wint_ts  変換では  wchar_t  へのポインターであることを示
              す。

       ll (エルエル)
              整数変換に対応する引数が  long longunsigned long long で、 n 変換に対応する引数
              が long long へのポインターであることを示す。

       q      A synonym for ll.  This is a nonstandard extension, derived from BSD; avoid its use
              in new code.

       L      a,  A, e, E, f, F, g, G 変換に対応する引数が long double であることを示す。 (C99 で
              は %LF を使うことを認めているが、SUSv2 では認められていない。)

       j      整数変換に対応する引数が intmax_tuintmax_t で、 n 変換に対応する引数が intmax_t
              へのポインターであることを示す。

       z      整数変換に対応する引数が  size_tssize_t で、 n 変換に対応する引数が size_t への
              ポインターであることを示す。

       Z      A nonstandard synonym for z that predates the appearance of z.  Do not use  in  new
              code.

       t      整数変換に対応する引数が ptrdiff_t で、 n 変換に対応する引数が ptrdiff_t へのポイン
              ターであることを示す。

       SUSv3 specifies all of the above, except for those modifiers  explicitly  noted  as  being
       nonstandard  extensions.   SUSv2 specified only the length modifiers h (in hd, hi, ho, hx,
       hX, hn)  and l (in ld, li, lo, lx, lX, ln, lc, ls)  and L (in Le, LE, Lf, Lg, LG).

       As a nonstandard extension, the GNU implementations treats ll and L as synonyms,  so  that
       one  can, for example, write llg (as a synonym for the standards-compliant Lg)  and Ld (as
       a synonym for the standards compliant lld).  Such usage is nonportable.

   変換指定子
       適用される変換の型を指定する文字。 変換指定子とその意味は以下の通りである。

       d, i   int 引数を符号付き 10 進表記に変換する。 精度指定があれば、精度で指定した桁数は必ず
              出力される。変換後の値が 指定された桁数に足りない場合は、左側が 0 で埋められる。 デ
              フォルトの精度は 1 である。 0 を表示しようとした時に、明示的に精度として 0 が指定さ
              れていると、 出力は空文字列となる。

       o, u, x, X
              unsigned  int  引数を、 符号なし8進数 (o), 符号なし10進数 (u), 符号なし16進数 (xX) に変換する。 x 変換では abcdef が使用され、 X 変換では ABCDEF が使用される。  精
              度指定があれば、精度で指定した桁数は必ず出力される。変換後の値が 指定された桁数に足
              りない場合は、左側が 0 で埋められる。

       e, E   The double argument is rounded and converted in the style [-]d.ddde±dd where  there
              is   one  digit  (which  is  nonzero  if  the  argument  is  nonzero)   before  the
              decimal-point character and  the  number  of  digits  after  it  is  equal  to  the
              precision; if the precision is missing, it is taken as 6; if the precision is zero,
              no decimal-point character appears.  An E conversion uses the letter E (rather than
              e)   to  introduce the exponent.  The exponent always contains at least two digits;
              if the value is zero, the exponent is 00.

       f, F   double 引数を丸めて [-]ddd.ddd の形の10進表現に変換する。  小数点の後の桁数は、精度
              で指定された値となる。 精度が指定されていない場合には 6 として扱われる。 精度として
              明示的に  0  が指定されたときには、小数点以下は表示されない。  小数点を表示する際に
              は、小数点の前に少なくとも一桁は数字が表示される。

              (SUSv2  では、F は規定されておらず、無限や NaN に関する文字列表現を行ってもよいこと
              になっている。 SUSv3 では F の規定が追加された。 C99  標準では、f  変換では、無限は
              "[-]inf"  か "[-]infinity" と表示し、 NaN は文字列の先頭に `nan' をつけて表示するよ
              うに規定されている。 F 変換の場合は "[-]INF", "[-]INFINITY", "NAN" と表示される。)

       g, G   double 引数を fe (G 変換の場合は FE)  の形式に変換する。 精度は表示する桁数
              を指定する。 精度が指定されない場合は、6桁とみなされる。 精度が 0 の場合は、1桁とみ
              なされる。 変換される値の指数が、 -4 より小さいか、精度以上の場合に、 e  形式が使用
              される。  変換された結果の小数部分の末尾の 0 は削除される。小数点が表示されるのは、
              小数点以下に数字が少なくとも一つある場合にだけである。

       a, A   (C99; not in SUSv2, but added in SUSv3)  For a conversion, the double  argument  is
              converted  to  hexadecimal  notation  (using  the  letters  abcdef)   in  the style
              [-]0xh.hhhhp±d; for A conversion  the  prefix  0X,  the  letters  ABCDEF,  and  the
              exponent  separator  P  is used.  There is one hexadecimal digit before the decimal
              point, and the number of digits after it is equal to the  precision.   The  default
              precision   suffices  for  an  exact  representation  of  the  value  if  an  exact
              representation in base 2 exists and otherwise is sufficiently large to  distinguish
              values  of  type  double.   The  digit  before the decimal point is unspecified for
              nonnormalized  numbers,  and  nonzero  but  otherwise  unspecified  for  normalized
              numbers.   The  exponent  always contains at least one digit; if the value is zero,
              the exponent is 0.

       c      l 修飾子がなければ、 int 引数を unsigned char  に変換して、その結果に対応する文字を
              出力する。  l 修飾子があれば、 wint_t (ワイド文字) 引数を、 wcrtomb(3) 関数を初期シ
              フト状態で呼び出してマルチバイト文字列に変換し、 変換されたマルチバイト文字列を出力
              する。

       s      l 修飾子がない場合、 引数は const char * 型で文字型の配列へのポインター (文字列への
              ポインター) であることが 期待されている。配列中の文字は、終端の  ヌルバイト  ('\0')
              が出てくるまで出力される  (終端文字は出力されない)。 精度が指定されていると、指定さ
              れた字数以上は出力されない。 精度が指定された場合には、終端バイトが存在する必要はな
              い。  精度が指定されていなかったり、精度の値が配列の大きさより大きい場合には、 配列
              は終端のヌルバイトを含んでいなければならない。

              l 修飾子が指定されている場合、 引数は const wchar_t *  型でワイド文字の配列へのポイ
              ンターであることが期待されている。 配列中のワイド文字は (1文字毎に wcrtomb(3)  を呼
              び出して) マルチバイト文字に変換される (最初のワイド文字の変換の前に wcrtomb()   の
              シフト状態を初期状態に戻してから変換は行われる)。  マルチバイト文字への変換は、文字
              列を終端するヌルワイド文字が 出てくるまで行われ、終端ヌルワイド文字も含めて変換され
              る。  結果のマルチバイト文字列は、終端のヌルバイトが出てくるまで 出力される (終端の
              ヌルバイトは出力されない)。  精度が指定された場合、指定されたバイト数以上には出力さ
              れない。   但し、マルチバイト文字の一部分だけが出力されることはない。  精度は「バイ
              ト」数を指定するものであり、「ワイド文字」数や 「画面での位置」を指定するものではな
              いことに注意。 精度が指定されていて、さらに出力が配列の末尾に達する前に出力バイト数
              が 精度の値を超える場合だけは、配列はヌルワイド文字で終端されていなくてもよい。  そ
              れ以外の場合は、必ず配列はヌルワイド文字で終端されていなければならない。

       C      (C99, C11 にはないが SUSv2, SUSv3, SUSv4 にはある)  lc と同じ。使ってはならない。

       S      (C99, C11 にはないが SUSv2, SUSv3, SUSv4 にはある)  ls と同じ。使ってはならない。

       p      void * ポインター引数を (%#x%#lx のような) 16 進数で出力する。

       n      The  number  of  characters written so far is stored into the integer pointed to by
              the corresponding argument.  That argument shall be an int *, or variant whose size
              matches  the  (optionally)   supplied  integer  length  modifier.   No  argument is
              converted.  (This specifier is  not  supported  by  the  bionic  C  library.)   The
              behavior  is  undefined if the conversion specification includes any flags, a field
              width, or a precision.

       m      (glibc での拡張; uClibc と musl で対応)  strerror(errno) の出力を表示する。引数は必
              要ない。

       %      '%' 文字を出力する。変換される引数は無い。 変換指定全体を書くと "%%" となる。

返り値

       成功時には、上記の関数は書き込まれた文字数を返す (文字列の最後を示すために使用するヌルバイ
       トは数に含まれない)。

       snprintf()  と vsnprintf()  は、 size バイトを越える文字数を書き込まない (size  には文字列
       を終端するヌルバイト  ('\0')  も含まれる)。 この制限によって出力が切り詰められた場合には、
       もし十分なスペースがあれば書き込まれたであろう文字の個数   (文字列を終端するヌルバイトを除
       く)  を返す。 従って、返り値が size 以上だった場合、出力が切り詰められたことを意味する (後
       述の注意も参照のこと)。

       エラーが発生した場合は、負の数を返す。

属性

       この節で使用されている用語の説明については、 attributes(7) を参照。

       ┌────────────────────────┬───────────────┬────────────────┐
       │インターフェース属性             │
       ├────────────────────────┼───────────────┼────────────────┤
       │printf(), fprintf(),    │ Thread safety │ MT-Safe locale │
       │sprintf(), snprintf(),  │               │                │
       │vprintf(), vfprintf(),  │               │                │
       │vsprintf(), vsnprintf() │               │                │
       └────────────────────────┴───────────────┴────────────────┘

準拠

       fprintf(),  printf(),  sprintf(),   vprintf(),   vfprintf(),   vsprintf():   POSIX.1-2001,
       POSIX.1-2008, C89, C99.

       snprintf(), vsnprintf(): POSIX.1-2001, POSIX.1-2008, C99.

       dprintf()   と vdprintf()  は、どちらも元は GNU による拡張であったが、 POSIX.1-2008 で標準
       化された。

       snprintf()   の返り値を見ると、  SUSv2  と  C99  標準は互いに矛盾している。  SUSv2  では、
       snprintf() が size=0 で呼び出された場合、 1 未満の値を何か返り値とするように規定している。
       一方 C99 では、このような場合 str を NULL とし、返り値として (通常通り) 出力バッファーが十
       分な大きさが  あった場合に出力されるであろう文字数を返す。 POSIX.1-2001 やそれ以降では C99
       の snprintf() の規定にあわせたものとなっている。

       glibc 2.1 では、長さ修飾子 hh, j, t, z と変換文字 a, A が追加された。

       glibc 2.2 では、 C99 で規定された意味での変換文字 F と フラグ文字 I が追加された。

注意

       テキストを buf に追加するのに、軽率にも次のようなコードを使っているプログラムがある。

           sprintf(buf, "%s some further text", buf);

       しかしながら、標準規格では、 sprintf(), snprintf(), vsprintf(), vsnprintf() の呼び出しにお
       いて、コピー元とコピー先のバッファーが重なっていた場合の  結果は不定である、と明記されてい
       る。 使用する gcc(1) のバージョンや指定したコンパイラのオプション次第では、 上記のような呼
       び出しで、期待した結果が得られ「ない」ことがある。

       glibc  の snprintf()  と vsnprintf()  の実装は、バージョン 2.1 以降は C99 標準に準拠してお
       り、 上記の通りの動作をする。 glibc 2.0.6 までは、出力が切り詰められた場合は -1 を返す。

バグ

       sprintf()  と  vsprintf()   は勝手に十分に長い文字列領域があると仮定するので、呼び出し側は
       実際の領域からあふれないように注意しなければならない。  しかし、これを保証することが不可能
       な場合が多い。 生成される文字列の長さはロケール依存であり、予測が難しいことに注意。 代わり
       に snprintf()  と vsnprintf() (または asprintf(3)  と vasprintf(3))  を使うこと。

       printf(foo); のようなコードはしばしばバグを引き起こす。 なぜなら foo に % 文字が含まれてる
       かもしれないからである。 foo が信頼できないユーザー入力から作られている場合には、 その中に
       %n  が含まれていることがあり、 printf()  呼び出し時にメモリーへの書き込みが起こり、 セキュ
       リティーホールを作ることになるかもしれない。

       Pi を 5 桁で出力する。

           #include <math.h>
           #include <stdio.h>
           fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0));

       日付と時間を "Sunday, July 3, 10:02" の形式で出力する。 (weekdaymonth は文字列へのポイ
       ンターである)

           #include <stdio.h>
           fprintf(stdout, "%s, %s %d, %.2d:%.2d\n",
                                                   weekday, month, day, hour, min);

       日  - 月 - 年 の順序で表示を行う国も多い。 従って、国際版では書式で指定された順番で 引数を
       表示できなければならない。

           #include <stdio.h>
           fprintf(stdout, format,
                                                   weekday, month, day, hour, min);

       format はロケールに依存しており、引数の順番を変えることもできる。 format が

           "%1$s, %3$d. %2$s, %4$d:%5$.2d\n"

       であれば、 "Sonntag, 3. Juli, 10:02" という結果になる。

       十分に大きな文字列領域を確保して、そこにメッセージを格納するには (glibc 2.0 と  glibc  2.1
       の両方で正しく動作するコード):

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

       char *
       make_message(const char *fmt, ...)
       {
           int n = 0;
           size_t size = 0;
           char *p = NULL;
           va_list ap;

           /* Determine required size */

           va_start(ap, fmt);
           n = vsnprintf(p, size, fmt, ap);
           va_end(ap);

           if (n < 0)
               return NULL;

           /* One extra byte for '\0' */

           size = (size_t) n + 1;
           p = malloc(size);
           if (p == NULL)
               return NULL;

           va_start(ap, fmt);
           n = vsnprintf(p, size, fmt, ap);
           va_end(ap);

           if (n < 0) {
               free(p);
               return NULL;
           }

           return p;
       }

       バージョン  2.0.6  より前の glibc で切り詰めが起こった場合、切り詰めは適切に処理されず、エ
       ラーとして扱われる。

関連項目

       printf(1),  asprintf(3),  puts(3),  scanf(3),   setlocale(3),   strfromd(3),   wcrtomb(3),
       wprintf(3), locale(5)

この文書について

       この man ページは Linux man-pages プロジェクトのリリース 5.10 の一部である。プロジェクトの
       説明とバグ報告に関する情報は https://www.kernel.org/doc/man-pages/ に書かれている。