scanfのヘルプ・マニュアル
日本語 英語
scanf --help
man scanf
SCANF(3) Linux Programmer’s Manual SCANF(3)
名前
scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf - 書式付き入力変換
書式
#include
int scanf(const char *format, ...);
int fscanf(FILE *stream, const char *format, ...);
int sscanf(const char *str, const char *format, ...);
#include
int vscanf(const char *format, va_list ap);
int vsscanf(const char *str, const char *format, va_list ap);
int vfscanf(FILE *stream, const char *format, va_list ap);
glibc 向けの機能検査マクロの要件 (feature_test_macros(7) 参照):
vscanf(), vsscanf(), vfscanf(): _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE;
or cc -std=c99
説明
scanf() 関数グループは、以下に述べるように、 format に従って入力を読 み
込 む ものである。この書式には 「変換指定」 (conversion specifications)
を含めることができ、変換指定があれば、その変換の結果は format に 続 く
pointer 引き数が指す場所に格納される。それぞれの pointer 引き数の型は、
対応する変換指定が返す値に適合していなければならない。
format 中の変換指定の個数が pointer 引き数の数より多かった場合の結果 は
未定義である。 pointer 引き数の数が変換指定の個数よりも多かった場合、余
分な pointer 引き数の評価は行われるが、それ以外は行われず無視される。
scanf() 関数は標準入力ストリーム stdin からの入力を読み込む。 fscanf()
は ストリームポインタ stream からの入力を読み込む。 sscanf() は文字列ポ
インタ str で示された文字列からの入力を読み込む。
vfscanf() 関数は vfprintf(3) と同様に、ストリームポインタ stream からの
入力をポインタの可変長引き数リストを用いて読み込む (stdarg(3) を参照)。
vscanf() 関数は、可変長引き数のリストに基づき標準入力からの読み取りを行
う。 vsscanf() 関数はそのリストに基づき文字列から読み取る。これらの関係
は vprintf(3) と vsprintf(3) 関数の関係と同様である。
format 文字列は 「命令」 (directive) の列で構成される。命令は入力文字の
系 列をどのように処理するかを指示するものである。ある命令の処理が失敗す
ると、入力はそれ以上読み込まれず、 scanf() は返る。「失敗」は 「入力 の
失 敗」 (input failure) と 「一致の失敗」 (matching failure) のいずれか
である。入力の失敗は入力文字が使用できなかったことを意味し、一致の失 敗
は入力が不適切であったこと (下記参照) を意味する。
命令は以下のいずれかである:
· ホワイトスペース (スペース、タブ、改行など; isspace(3) 参照) の
列。この命令は、入力中の任意の個数のホワイトスペースに一致する。
(「何もなし」にも一致する)。
· 通常文字 (つまり、ホワイトスペースと '%' 以外の文字)。この文字は
入力の次の文字に正確に一致しなければならない。
· 変換指定。変換指定は '%' (パーセント) 文字で始まる。入力された文
字 の 系 列 は こ の指定にもとづいて変換され、変換結果は対応する
pointer 引き数が指す場所に格納される。入力の次の文字が変換指定と
一 致 し な い 場 合 は 、変換は失敗する — これが 「一致の失敗」
(matching failure) である。
format 中の各々の 「変換指定」は文字 '%' か文字系列 "%n$" (違いについて
は後述) で始まり、以下の要素が続く。
· 代入抑制文字 '*' (省略可能)。 scanf() は変換指定に指示された通り
入力を読み込むが、その入力は捨てられる。対応する pointer 引き 数
は 必要なく、 scanf() が返す代入が成功した数にこの指定は含まれな
い。
· 文字 'a' (省略可能)。これは文字列変換とともに使用され、これを 使
うと呼び出し元が入力を保持する対応するバッファを確保する必要がな
くなる。代わりに scanf() が必要な大きさのバッファを確保し、こ の
バ ッファのアドレスを対応する pointer 引き数に代入する。 pointer
引き数は char * 型の変数へのポインタでなければならない (変数自体
は 呼び出し前に初期化されている必要はない)。呼び出し元は、不要に
なった時点で、このバッファを free(3) すべきである。この 機 能 は
GNU による拡張である。 C99 は 'a' 文字を変換指定として使用してい
る (こちらも GNU の実装と同じように使用することができる)。
· 「最大フィールド幅」を指定する 10進数 (省略可能)。この最大値に達
するか、一致しない文字が見つかるか、のどちらかになると、文字の読
み込みを停止する。ほとんどの変換では、先頭のホワイトスペース文字
は 捨てられ (例外については後述する)、捨てられたこれらの文字は最
大フィールド幅の計算には含まれない。文字列の入力変換では、入力の
末尾を示すヌル終端文字 ('\0') も格納されるが、最大フィールド幅に
はこの終端文字は含まれない。
· 「型修飾子」 (type modifier characters) (省略可能)。例えば、型修
飾子 l を %d などの整数変換と一緒に使うと、対応する pointer 引き
数が int ではなく long int を参照していることを指定できる。
· 「変換指定」 : 実行すべき入力変換の種類を指定する。
format 中の変換指定は、'%' で始まるか、 "%n$" で始まるかの、いずれか の
形 式である。これら 2つの形式を同じ format 文字列に混ぜることはできない
。但し、"%n$" を含む文字列に %% と %* を含めることはできる。 format に
'%' 指定が含まれている場合、各々の '%' 指定と後続の pointer 引き数はそ
の順番通りに対応する。 "%n$" 形式 (POSIX.1-2001 では規定されて い る が
、C99 にはない) では、 n は 10進数であり、変換後の入力を format の後ろ
の n 番目の pointer 引き数が参照する場所に格納することを指定する。
変換
変換指定には、以下の 「型修飾子」を入れることができる。
h 変換が d, i, o, u, x, X, n のいずれかであり、次のポインタが (int
ではなく) short int か unsigned short int へのポインタであること
を示す。
hh h と同じだが、次のポインタが signed char か unsigned char へのポ
インタであることを示す。
j h と同じだが、次のポインタが intmax_t か uintmax_t へのポインタ
であることを示す。この修飾子は C99 で導入された。
l 変換が d, i, o, u, x, X, n か n のいずれかであり次のポイン タ が
(int ではなく) long int か unsigned long int へのポインタである
こと、または、変換が e, f, g のうちのひとつであり次のポインタ が
(float ではなく) double へのポインタであることのいずれかであるこ
とを示す。 l 文字を二つ指定すると、 L と同じ意味となる。 %c や
%s とともに使用すると、パラメータはそれぞれワイド文字やワイド文
字列へのポインタであるとみなされる。
L e, f, g 変換で、次のポインタが long double へのポインタである こ
と を 示す。もしくは、 d, i, o, u, x 変換で、次のポインタが long
long へのポインタであることのいずれかであることを示す。
q L と同一である。この修飾子は ANSI C には存在しない。
t h と同様だが、次のポインタが ptrdiff_t へのポインタであること を
示す。この修飾子は C99 で導入された。
z h と同様だが、次のポインタが size_t へのポインタであることを示す
。この修飾子は C99 で導入された。
以下の 「変換指定子」が利用可能である。
% 文字 '%' に対応する。書式文字列の中の %% は単一の文字 '%' に対応
する。変換は行われず (但し、先頭のホワイトスペース文字は捨てられ
る)、変数への代入は生じない。
d 符号つきの 10進の整数に対応する。次のポインタは int へのポインタ
でなければならない。
D ld と同一である。これは以前の仕様との互換性だけのためにある。 (
注意: これは libc4 の場合だけである。 libc5 や glibc では %D は
暗黙のうちに無視され、古いプログラムにおいて謎に満ちた失敗の原因
となる。)
i 符号つき整数に対応する。次のポインタは int へのポインタでなけ れ
ばならない。この整数は 0x または 0X で開始する場合には 16 進数、
0 で開始する場合には 8 進数、その他の場合には 10進数として読み込
まれる。この変換で使用される文字は、これらの基数に対応しているも
のだけである。
o 符号なしの 8 進の整数に対応する。次のポインタは unsigned int で
なければならない。
u 符号なしの 10進の整数に対応する。次のポインタは unsigned int へ
のポインタでなければならない。
x 符号なしの 16 進の整数に対応する。次のポインタは unsigned int へ
のポインタでなければならない。
X x と同一である。
f 符号つき浮動小数点実数に対応する。次のポインタは float へのポイ
ンタでなければならない。
e f と同一である。
g f と同一である。
E f と同一である。
a (C99) f と同一である。
s ホワイトスペースではない文字で構成された文字列に対応する。次のポ
インタは文字の配列へのポインタでなければならず、その文字配列は、
入力された文字列と (自動的に追加される) ヌル終端文字 ('\0') を格
納するのに十分な大きさでなければならない。文字列の入力は、ホワイ
トスペースが入力されるか、最大フィールド幅に達するか、のどちらか
が起こると停止される。
c 「最大フィールド幅」 (デフォルトは 1) で指定された幅の文字の列に
対応する。次のポインタは char へのポインタで、すべての文字を格納
するのに十分な領域がなければならない (終端の NULL バイトは追加さ
れない)。通常行われる先頭のホワイトスペースの読み飛ばしは行わ れ
ない。先頭のホワイトスペースを読み飛ばすためには、フォーマット文
の中で明示的にスペースを使用すれば良い。
[ 格納された文字列のうちから取り出された、指定された文字の集合で構
成される空ではない文字の列に対応する。次のポインタは char へのポ
インタでなければならず、そこには文字列中のすべての文字と終 端 の
NULL バイトを格納するための十分な領域がなければならない。通常行
われる先頭のホワイトスペースの読み飛ばしは行われない。この文字列
は 特別な集合の中の文字で構成されている。この集合は開き括弧 [ と
閉じ括弧 ] の間の文字で定義される。開き括弧のあとの最初の文字 が
曲 アクセント記号 (^) の場合、集合はこれらの文字を含まないものと
なる。閉じ括弧を集合に含ませるためには、この文字を開き括弧または
曲アクセント記号のあとの最初の文字にすればよい。つまり、他の位置
に閉じ括弧を置くと文字の集合が終る。ハイフン - もまた特殊文字 で
ある。二つの異なる文字の間に置かれた時、この文字は、その間にある
全ての文字を集合に加える。ハイフン自体を含ませるためには、括弧が
閉 じる前の最後の一文字をハイフンにすればよい。例えば、 [^]0-9-]
は「閉じ括弧、0 〜 9、ハイフンの 3 種類を除く全ての文字」の集 合
を意味する。この文字列は集合に含まれていない (曲アクセントの場合
には含まれる) 文字の出現または確保された領域が使い切られた時に終
了する。
p (printf(3) の %p で印字されるような) ポインタ値に対応する。次の
ポインタは void へのポインタへのポインタでなければならない。
n どんな入力も必要としない。そのかわりに、入力からここまで消費され
た文字数が次のポインタで指定された場所に格納される。このポインタ
は int へのポインタでなければならない。変換を抑制するのであれ ば
* 代入抑制文字を使って抑制することができるのだが、この変換指定子
は変換では「ない」。 C 言語の標準規格では「実行の完了時に返さ れ
る代入の回数は %n 命令の実行では増加しない」となっているが、正誤
表の内容はこれと矛盾するようである。おそらく、 %n 変換が返り値に
与える影響についてはどのような仮定もしないのが賢明であろう。
返り値
こ れらの関数は、一致と代入が成功した入力要素の個数を返す。返される値は
渡された変換の個数よりも少ないこともあり、最初に一致の失敗があった場 合
には 0 になることもある。
最 初の変換が成功する前に入力の最後に達して、一致の失敗が起こった場合に
は、 EOF が返される。また、読み込みエラーが発生した場合にも EOF が返 さ
れ る。読み込みエラーの場合には、そのストリームのエラー指示子がセットさ
れ (ferror(3) 参照)、 errno にエラーを示す値がセットされる。
エラー
EAGAIN stream に対応するファイルディスクリプタが non-blocking となっ て
おり、読み込み操作は停止 (block) することになる。
EBADF stream に対応するファイルディスクリプタが無効であるが、読み込み
用にオープンされていない。
EILSEQ 入力されたバイト列が有効な文字を構成していない。
EINTR 読み込み操作がシグナルにより割り込まれた。 signal(7) 参照。
EINVAL 引き数が十分でない。または format が NULL である。
ENOMEM メモリ不足。
ERANGE 整数変換の結果が、対応する整数型に格納できるサイズを越えてしまう
。
準拠
fscanf(), scanf(), sscanf() 関数は C89, C99, POSIX.1-2001 に準拠してい
る。これらの標準では、エラー ERANGE は規定されていない。
q 指定子は long long の 4.4BSD での記述方法である。一方、整数変換 で の
ll または L の使用は GNU での拡張である。
こ れらの関数の Linux 版は GNU libio ライブラリーを元にしている。より簡
潔な説明には GNU libc (glibc-1.08) の info 文書に目を通すこと。
注意
GNU C ライブラリ (glibc) では非標準のオプションをサポートしており、この
オプションを使うと変換指定子 %s や %a[range] への入力文字列に対して十分
な大きさの文字列をライブラリが動的に確保するようになる。この機能を使 用
す る には、長さ修飾子として a を指定する (したがって、全体としては %as
や %a[range] となる)。以下の例にあるように、呼び出し側は返された文字 列
を free(3) しなければならない。
char *p;
int n;
errno = 0;
n = scanf("%a[a-z]", &p);
if (n == 1) {
printf("read: %s\n", p);
free(p);
} else if (errno != 0) {
perror("scanf");
} else {
fprintf(stderr, "No matching characters\n"):
}
上記の例にあるように、 scanf() が文字列の読み込みに成功した場合にだけ、
free(3) を呼び出す必要がある。
gcc -std=c99 や gcc -D_ISOC99_SOURCE でコンパイルしたプログ ラ ム で は
(_GNU_SOURCE も同時に指定していない場合)、 a 修飾子は利用できない。上記
の場合、 a は (上述の通り) 浮動小数点数を示す変換指定子と解釈される。
バージョン 2.7 以降では、glibc は a 修飾子と同じ目的で m 修飾子も提供し
ている。 m 修飾子は以下の利点がある。
* %c 変換指定子にも適用できる (例えば %3mc)。
* 浮動小数点変換指定子としての %a との紛らわしさが避けられる (また gcc
-std=c99 などの影響も避けられる)。
* POSIX.1 標準の次の改訂版で規定される。
バグ
全ての関数は、完全に C89 に準拠している。しかし追加で q と a 指定子が提
供 さ れ ており、同様に L と l 指定子の付加的な振る舞いもある。後者は、
C89 で定義された指定子の振る舞いを変更するものなので、バグとみなされ る
かもしれない。
ANSI C で定義された型修飾子と変換指定子の組み合わせの中には意味をなさな
いものがある (例えば、 %Ld)。これらが指定された場合、 Linux 上ではは っ
き りと定義された振る舞いをするかもしれないが、他のアーキテクチャでも同
様になっているとは限らない。それゆえに、ほとんどの場合、 ANSI C で定 義
さ れていない修飾子を使用した方が良い。すなわち、 d, i, o, u, x, X 変換
や ll と組み合わせる場合には、 L の代わりに q を使用した方が良い。
q の使用方法は 4.4BSD と同じではない。 4.4BSD では q は L と同等に浮 動
小数の変換に使用される。
関連項目
getc(3), printf(3) setlocale(3), strtod(3), strtol(3), strtoul(3),
GNU 2008-07-12 SCANF(3)
SCANF(3) Linux Programmer’s Manual SCANF(3)
NAME
scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf - input format conver-
sion
SYNOPSIS
#include
int scanf(const char *format, ...);
int fscanf(FILE *stream, const char *format, ...);
int sscanf(const char *str, const char *format, ...);
#include
int vscanf(const char *format, va_list ap);
int vsscanf(const char *str, const char *format, va_list ap);
int vfscanf(FILE *stream, const char *format, va_list ap);
Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
vscanf(), vsscanf(), vfscanf(): _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE;
or cc -std=c99
DESCRIPTION
The scanf() family of functions scans input according to format as
described below. This format may contain conversion specifications;
the results from such conversions, if any, are stored in the locations
pointed to by the pointer arguments that follow format. Each pointer
argument must be of a type that is appropriate for the value returned
by the corresponding conversion specification.
If the number of conversion specifications in format exceeds the number
of pointer arguments, the results are undefined. If the number of
pointer arguments exceeds the number of conversion specifications, then
the excess pointer arguments are evaluated, but are otherwise ignored.
The scanf() function reads input from the standard input stream stdin,
fscanf() reads input from the stream pointer stream, and sscanf() reads
its input from the character string pointed to by str.
The vfscanf() function is analogous to vfprintf(3) and reads input from
the stream pointer stream using a variable argument list of pointers
(see stdarg(3). The vscanf() function scans a variable argument list
from the standard input and the vsscanf() function scans it from a
string; these are analogous to the vprintf(3) and vsprintf(3) functions
respectively.
The format string consists of a sequence of directives which describe
how to process the sequence of input characters. If processing of a
directive fails, no further input is read, and scanf() returns. A
"failure" can be either of the following: input failure, meaning that
input characters were unavailable, or matching failure, meaning that
the input was inappropriate (see below).
A directive is one of the following:
· A sequence of white-space characters (space, tab, newline, etc.;
see isspace(3)). This directive matches any amount of white
space, including none, in the input.
· An ordinary character (i.e., one other than white space or '%').
This character must exactly match the next character of input.
· A conversion specification, which commences with a '%' (percent)
character. A sequence of characters from the input is converted
according to this specification, and the result is placed in the
corresponding pointer argument. If the next item of input does
not match the conversion specification, the conversion fails —
this is a matching failure.
Each conversion specification in format begins with either the charac-
ter '%' or the character sequence "%n$" (see below for the distinction)
followed by:
· An optional '*' assignment-suppression character: scanf() reads
input as directed by the conversion specification, but discards
the input. No corresponding pointer argument is required, and
this specification is not included in the count of successful
assignments returned by scanf().
· An optional 'a' character. This is used with string conver-
sions, and relieves the caller of the need to allocate a corre-
sponding buffer to hold the input: instead, scanf() allocates a
buffer of sufficient size, and assigns the address of this
buffer to the corresponding pointer argument, which should be a
pointer to a char * variable (this variable does not need to be
initialized before the call). The caller should subsequently
free(3) this buffer when it is no longer required. This is a
GNU extension; C99 employs the 'a' character as a conversion
specifier (and it can also be used as such in the GNU implemen-
tation).
· An optional decimal integer which specifies the maximum field
width. Reading of characters stops either when this maximum is
reached or when a non-matching character is found, whichever
happens first. Most conversions discard initial white space
characters (the exceptions are noted below), and these discarded
characters don’t count towards the maximum field width. String
input conversions store a null terminator ('\0') to mark the end
of the input; the maximum field width does not include this ter-
minator.
· An optional type modifier character. For example, the l type
modifier is used with integer conversions such as %d to specify
that the corresponding pointer argument refers to a long int
rather than a pointer to an int.
· A conversion specifier that specifies the type of input conver-
sion to be performed.
The conversion specifications in format are of two forms, either begin-
ning with '%' or beginning with "%n$". The two forms should not be
mixed in the same format string, except that a string containing "%n$"
specifications can include %% and %*. If format contains '%' specifi-
cations then these correspond in order with successive pointer argu-
ments. In the "%n$" form (which is specified in POSIX.1-2001, but not
C99), n is a decimal integer that specifies that the converted input
should be placed in the location referred to by the n-th pointer argu-
ment following format.
Conversions
The following type modifier characters can appear in a conversion spec-
ification:
h Indicates that the conversion will be one of d, i, o, u, x, X,
or n and the next pointer is a pointer to a short int or
unsigned short int (rather than int).
hh As for h, but the next pointer is a pointer to a signed char or
unsigned char.
j As for h, but the next pointer is a pointer to an intmax_t or a
uintmax_t. This modifier was introduced in C99.
l Indicates either that the conversion will be one of d, i, o, u,
x, X, or n and the next pointer is a pointer to a long int or
unsigned long int (rather than int), or that the conversion will
be one of e, f, or g and the next pointer is a pointer to double
(rather than float). Specifying two l characters is equivalent
to L. If used with %c or %s the corresponding parameter is con-
sidered as a pointer to a wide character or wide-character
string respectively.
L Indicates that the conversion will be either e, f, or g and the
next pointer is a pointer to long double or the conversion will
be d, i, o, u, or x and the next pointer is a pointer to long
long.
q equivalent to L. This specifier does not exist in ANSI C.
t As for h, but the next pointer is a pointer to a ptrdiff_t.
This modifier was introduced in C99.
z As for h, but the next pointer is a pointer to a size_t. This
modifier was introduced in C99.
The following conversion specifiers are available:
% Matches a literal '%'. That is, %% in the format string matches
a single input '%' character. No conversion is done (but ini-
tial white space characters are discarded), and assignment does
not occur.
d Matches an optionally signed decimal integer; the next pointer
must be a pointer to int.
D Equivalent to ld; this exists only for backwards compatibility.
(Note: thus only in libc4. In libc5 and glibc the %D is
silently ignored, causing old programs to fail mysteriously.)
i Matches an optionally signed integer; the next pointer must be a
pointer to int. The integer is read in base 16 if it begins
with 0x or 0X, in base 8 if it begins with 0, and in base 10
otherwise. Only characters that correspond to the base are
used.
o Matches an unsigned octal integer; the next pointer must be a
pointer to unsigned int.
u Matches an unsigned decimal integer; the next pointer must be a
pointer to unsigned int.
x Matches an unsigned hexadecimal integer; the next pointer must
be a pointer to unsigned int.
X Equivalent to x.
f Matches an optionally signed floating-point number; the next
pointer must be a pointer to float.
e Equivalent to f.
g Equivalent to f.
E Equivalent to f.
a (C99) Equivalent to f.
s Matches a sequence of non-white-space characters; the next
pointer must be a pointer to character array that is long enough
to hold the input sequence and the terminating null character
('\0'), which is added automatically. The input string stops at
white space or at the maximum field width, whichever occurs
first.
c Matches a sequence of characters whose length is specified by
the maximum field width (default 1); the next pointer must be a
pointer to char, and there must be enough room for all the char-
acters (no terminating null byte is added). The usual skip of
leading white space is suppressed. To skip white space first,
use an explicit space in the format.
[ Matches a non-empty sequence of characters from the specified
set of accepted characters; the next pointer must be a pointer
to char, and there must be enough room for all the characters in
the string, plus a terminating null byte. The usual skip of
leading white space is suppressed. The string is to be made up
of characters in (or not in) a particular set; the set is
defined by the characters between the open bracket [ character
and a close bracket ] character. The set excludes those charac-
ters if the first character after the open bracket is a circum-
flex (^). To include a close bracket in the set, make it the
first character after the open bracket or the circumflex; any
other position will end the set. The hyphen character - is also
special; when placed between two other characters, it adds all
intervening characters to the set. To include a hyphen, make it
the last character before the final close bracket. For
instance, [^]0-9-] means the set "everything except close
bracket, zero through nine, and hyphen". The string ends with
the appearance of a character not in the (or, with a circumflex,
in) set or when the field width runs out.
p Matches a pointer value (as printed by %p in printf(3); the next
pointer must be a pointer to a pointer to void.
n Nothing is expected; instead, the number of characters consumed
thus far from the input is stored through the next pointer,
which must be a pointer to int. This is not a conversion,
although it can be suppressed with the * assignment-suppression
character. The C standard says: "Execution of a %n directive
does not increment the assignment count returned at the comple-
tion of execution" but the Corrigendum seems to contradict this.
Probably it is wise not to make any assumptions on the effect of
%n conversions on the return value.
RETURN VALUE
These functions return the number of input items successfully matched
and assigned, which can be fewer than provided for, or even zero in the
event of an early matching failure.
The value EOF is returned if the end of input is reached before either
the first successful conversion or a matching failure occurs. EOF is
also returned if a read error occurs, in which case the error indicator
for the stream (see ferror(3)) is set, and errno is set indicate the
error.
ERRORS
EAGAIN The file descriptor underlying stream is marked non-blocking,
and the read operation would block.
EBADF The file descriptor underlying stream is invalid, or not open
for reading.
EILSEQ Input byte sequence does not form a valid character.
EINTR The read operation was interrupted by a signal; see signal(7).
EINVAL Not enough arguments; or format is NULL.
ENOMEM Out of memory.
ERANGE The result of an integer conversion would exceed the size that
can be stored in the corresponding integer type.
CONFORMING TO
The functions fscanf(), scanf(), and sscanf() conform to C89 and C99
and POSIX.1-2001. These standards do not specify the ERANGE error.
The q specifier is the 4.4BSD notation for long long, while ll or the
usage of L in integer conversions is the GNU notation.
The Linux version of these functions is based on the GNU libio library.
Take a look at the info documentation of GNU libc (glibc-1.08) for a
more concise description.
NOTES
The GNU C library supports a non-standard extension that causes the
library to dynamically allocate a string of sufficient size for input
strings for the %s and %a[range] conversion specifiers. To make use of
this feature, specify a as a length modifier (thus %as or %a[range]).
The caller must free(3) the returned string, as in the following exam-
ple:
char *p;
int n;
errno = 0;
n = scanf("%a[a-z]", &p);
if (n == 1) {
printf("read: %s\n", p);
free(p);
} else if (errno != 0) {
perror("scanf");
} else {
fprintf(stderr, "No matching characters\n"):
}
As shown in the above example, it is only necessary to call free(3) if
the scanf() call successfully read a string.
The a modifier is not available if the program is compiled with gcc
-std=c99 or gcc -D_ISOC99_SOURCE (unless _GNU_SOURCE is also speci-
fied), in which case the a is interpreted as a specifier for floating-
point numbers (see above).
Since version 2.7, glibc also provides the m modifier for the same pur-
pose as the a modifier. The m modifier has the following advantages:
* It may also be applied to %c conversion specifiers (e.g., %3mc).
* It avoids ambiguity with respect to the %a floating-point conversion
specifier (and is unaffected by gcc -std=c99 etc.)
* It is specified in the upcoming revision of the POSIX.1 standard.
BUGS
All functions are fully C89 conformant, but provide the additional
specifiers q and a as well as an additional behavior of the L and l
specifiers. The latter may be considered to be a bug, as it changes
the behavior of specifiers defined in C89.
Some combinations of the type modifiers and conversion specifiers
defined by ANSI C do not make sense (e.g. %Ld). While they may have a
well-defined behavior on Linux, this need not to be so on other archi-
tectures. Therefore it usually is better to use modifiers that are not
defined by ANSI C at all, that is, use q instead of L in combination
with d, i, o, u, x, and X conversions or ll.
The usage of q is not the same as on 4.4BSD, as it may be used in float
conversions equivalently to L.
SEE ALSO
getc(3), printf(3), setlocale(3), strtod(3), strtol(3), strtoul(3)
COLOPHON
This page is part of release 3.22 of the Linux man-pages project. A
description of the project, and information about reporting bugs, can
be found at http://www.kernel.org/doc/man-pages/.
GNU 2008-07-12 SCANF(3)