.\" Copyright (c) 1990, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Chris Torek and the American National Standards Committee X3,
.\" on Information Processing Systems.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)scanf.3 8.2 (Berkeley) 12/11/93
.\"
.\" $FreeBSD$
.Dd December 11, 1993
.Dt SCANF 3
.Os
.Sh 名称
.Nm scanf ,
.Nm fscanf ,
.Nm sscanf ,
.Nm vscanf ,
.Nm vsscanf ,
.Nm vfscanf
.Nd 入力のフォーマット変換
.Sh 書式
.Fd #include <stdio.h>
.Ft int
.Fn scanf "const char *format" ...
.Ft int
.Fn fscanf "FILE *stream" "const char *format" ...
.Ft int
.Fn sscanf "const char *str" "const char *format" ...
.Fd #include <stdarg.h>
.Ft int
.Fn vscanf "const char *format" "va_list ap"
.Ft int
.Fn vsscanf "const char *str" "const char *format" "va_list ap"
.Ft int
.Fn vfscanf "FILE *stream" "const char *format" "va_list ap"
.Sh 解説
.Fn scanf
の関数ファミリは、後述する
.Fa format
に従って入力を走査します。このフォーマットには
.Em 変換指示子
を含めることができます。このような変換の結果は、もし存在すれば
.Em ポインタ
引数を介して格納されます。
.Fn scanf
関数は入力を標準入力ストリーム
.Em stdin
から読み取ります。
.Fn fscanf
は入力をストリームポインタ
.Fa stream
から読み取ります。
.Fn sscanf
は入力を
.Fa str
の指すキャラクタ文字列から読み取ります。
.Fn vfscanf
関数は、
.Xr vfprintf 3
に類似しており、ポインタの可変引数リスト
(
.Xr stdarg 3
を参照)
を使用して
ストリームポインタ
.Fa stream
から入力を読み取ります。
.Fn vscanf
関数は標準入力から、
.Fn vsscanf
関数は文字列から可変引数リストを走査します。
これらの関数はそれぞれ
.Fn vprintf
関数と
.Fn vsprintf
関数に類似しています。
連続する
.Em ポインタ
引数の各々は、各々の連続する変換指示子と
適切に対応している必要があります
(
ただし、後述の `抑制' を参照
)
。
変換指示子はすべて
.Cm %
文字
(
パーセント符号
)
で始まります。
.Fa format
文字列には、他のキャラクタも含めることができます。
.Fa format
文字列内の空白
(
ブランクやタブ、改行など
)
は、入力に何も含まれていない場合を含む、任意の量の空白と一致します。
その他のキャラクタはすべてそれ自身とだけ一致します。
入力キャラクタがそのようなフォーマットキャラクタと
一致しなくなったときに走査は停止します。
走査は、入力変換が行えないときにも停止します
(
下記参照
)
。
.Sh 変換
変換の先頭となる
.Cm %
文字に続いて、以下にあげるいくつかの
.Em フラグ
文字をおくことができます。
.Bl -tag -width indent
.It Cm *
割り当ての抑制。以降の変換は普段通りに行われますが、
ポインタは使用されません。変換の結果は単に廃棄されます。
.It Cm h
変換が
.Cm dioux
または
.Cm n
のどれかであり、次のポインタは
(
.Em int
ではなく
)
.Em short int
を指すポインタであることを示します。
.It Cm l
変換が
.Cm dioux
または
.Cm n
のどれかであり、次のポインタが
(
.Em int
ではなく
)
.Em long int
を指すポインタであること、あるいは変換は
.Cm efg
のどれかであり、次のポインタは
(
.Em float
ではなく
)
.Em double
を指すポインタであることを示します。
.It Cm L
変換が
.Cm efg
になり、次のポインタが
.Em long double
を指すポインタであることを示します
(
このタイプは実装されていません。
.Cm L
フラグは現時点では無視されます
)
。
.It Cm q
変換が
.Cm dioux
または
.Cm n
のどれかであり、次のポインタが
(
.Em int
ではなく
)
.Em long long int
を指すポインタであることを示します。
.El
.Pp
これらのフラグに加えて、オプションとして
10
進数で表される最大フィールド幅を
.Cm %
と変換の間に置くことも可能です。
フィールド幅を指定しない場合、デフォルトの `無限' が使用されます
(
例外が
1 つあります。後述
)
。
フィールド幅を指定した場合、変換処理で最大でもその数のキャラクタが走査されます。
変換が始まる前に、ほとんどの変換は空白をスキップします。
この空白はフィールド幅のカウント対象にはなりません。
.Pp
以下の変換を利用できます。
.Bl -tag -width XXXX
.It Cm %
リテラルの
`%'
と一致します。すなわち、フォーマット文字列内の
`%\&%'
は、1 つの入力キャラクタ
`%'
と一致します。変換は行われず、割当ては行われません。
.It Cm d
オプションの符号つき
10
進数に一致します。次のポインタは
.Em int
を指すポインタである必要があります。
.It Cm D
.Cm ld
と同等です。これは後方互換性のためにだけ存在しています。
.It Cm i
オプションの符号つき整数に一致します。次のポインタは
.Em int
を指すポインタである必要があります。整数が
.Ql 0x
または
.Ql 0X
で始まる場合、整数を基底
16
で読み取ります。
.Ql 0
で始まる場合、基底
8
で読み取ります。それ以外の場合は、基底
10
です。基底に対応するキャラクタだけが使用されます。
.It Cm o
8
進数の整数と一致します。次のポインタは
.Em unsigned int
を指すポインタである必要があります。
.It Cm O
.Cm lo
と同等です。これは後方互換性のために存在しています。
.It Cm u
オプションの符号つき
10
進整数と一致します。次のポインタは
.Em unsigned int
を指すポインタである必要があります。
.It Cm x
オプションの符号つき
16
進整数に一致します。次のポインタは
.Em unsigned int
を指すポインタである必要があります。
.It Cm X
.Cm lx
と同等です。これは
.St -ansiC
違反ですが、以前の
.Ux
システムとは後方互換性があります。
.It Cm f
オプションの符号つき浮動小数点数と一致します。次のポインタは
.Em float
を指すポインタである必要があります。
.It Cm e
.Cm f
と同等です。
.It Cm g
.Cm f
と同等です。
.It Cm E
.Cm lf
と同等です。これは
.St -ansiC
違反ですが、以前の
.Ux
システムとは後方互換性があります。
.It Cm F
.Cm lf
と同等です。これは後方互換性のためにだけ存在します。
.It Cm s
非空白文字のシーケンスと一致します。次のポインタは
.Em char
を指すポインタである必要があり、配列はすべてのシーケンス
と終端の
.Dv NUL
文字を受け入れるのに十分なだけ大きい必要があります。
入力文字列は、空白、または最大フィールド幅のどちらかが
最初に発生した場所で停止します。
.It Cm c
.Em width
個
(
デフォルト
1
)
のキャラクタのシーケンスに一致します。次のポインタは
.Em char
を指すポインタである必要があり、
すべてのキャラクタに対して十分な余地がある必要があります
(
終端の
.Dv NUL
は追加されません
)
。
通常行われる先頭の空白スキップは抑制されます。
最初の空白をスキップするには、
フォーマット内に明示的なスペースを使用してください。
.It Cm \&[
指定された受け入れ文字集合からなる、
空でない文字列と一致します。次のポインタは、
.Em char
を指すポインタである必要があり、
文字列内のすべてのキャラクタに加えて終端の
.Dv NUL
文字を入れる十分な余地がある必要があります。
通常行われる先頭の空白スキップは抑制されます。
文字列は、特定の集合内の
(
または集合外の
)
文字で構成されます。この集合は、開き角括弧
.Cm [
文字と閉じ角括弧
.Cm ]
文字の間のキャラクタによって定義されます。
集合は、開き角括弧の直後の文字が曲折アクセント記号
.Cm ^
である場合、これらの文字を
.Em 除外
します。
集合内に閉じ角括弧を入れるには、閉じ角括弧を
開き角括弧または曲折アクセント記号の直後の文字にします。
その他の位置に置くと集合を終了させます。
ハイフン文字
.Cm -
も特殊です。
他の
2
つの文字間に置かれた場合、
ハイフンは間に入るすべての文字を集合に追加します。
ハイフンを入れるためには、
ハイフンを最後の閉じ角括弧の直前の文字にします。
たとえば、
.Ql [^]0-9-]
は、`閉じ角括弧、0 から 9、およびハイフン以外のすべて'
の集合を意味します。文字列は、集合内にない
(
または曲折アクセント記号がある集合に含まれる
)
文字が出現するか、またはフィールド幅が不足するときに終了します。
.It Cm p
(
.Xr printf 3
で
.Ql %p
で印字された
)
ポインタの値と一致します。次のポインタは
.Em void
を指すポインタである必要があります。
.It Cm n
何も予期しません。その代わり、入力以降消費された
キャラクタの個数が次のポインタを介して保存されます。
次のポインタは
.Em int
を指すポインタである必要があります。これは変換では
.Em ありません。
ただし
.Cm *
フラグで抑制できます。
.El
.Pp
後方互換性のために、他の変換キャラクタ
(
.Ql \e0
を除く
)
は
.Ql %d
であるかのように、または大文字の場合は
.Ql %ld
であるかのように扱われ、
.Ql %\e0
の変換はただちに
.Dv EOF
を戻します。
.Cm F
と
.Cm X
の変換は、将来
.Tn ANSI
C
標準を遵守するように変更される予定なので、
その後では、これらの変換はそれぞれ
.Cm f
と
.Cm x
のように動作するでしょう。
.Pp
.Sh 戻り値
これらの関数は、割り当てられた入力項目数を返します。
一致が成功しなかった場合、この数は
準備されたものよりも少なく、または
0
になることさえあります。
0
は、利用できる入力があったものの、
変換は割り当てられなかったことを示します。通常、これは
.Ql %d
変換に対するアルファベット文字等の様な、無効な入力文字のためです。
ファイルの終りの様に、
なんらかの変換が発生する前に入力処理が失敗した場合は、値
.Dv EOF
が返されます。変換が開始した後で、エラーまたはファイルの終りが
発生した場合、正常に完了した変換の数が返されます。
.Sh 関連項目
.Xr getc 3 ,
.Xr printf 3 ,
.Xr strtod 3 ,
.Xr strtol 3 ,
.Xr strtoul 3
.Sh 規格
関数
.Fn fscanf ,
.Fn scanf
および
.Fn sscanf
は
.St -ansiC
に準拠しています。
.Sh 歴史
関数
.Fn vscanf ,
.Fn vsscanf
および
.Fn vfscanf
はこのリリースで新しく取り入られたものです。
.Sh バグ
変換
.Cm %F
と
.Cm %X
の現在の状況は不都合な状態にあります。
.Pp
すべての後方互換フォーマットは、将来取り除かれます。
.Pp
数値文字列は
512
文字に切り捨てられます。たとえば、
.Cm %f
と
.Cm %d
は事実上
.Cm %512f
と
.Cm %512d
です。
