strtoul - ライブラリコールの説明 - Linux コマンド集 一覧表

strtoul, strtoull, strtouq - 文字列を unsigned long int に変換する

#include <stdlib.h>

unsigned long intstrtoul(const char *nptr, char **endptr, int base);

unsigned long long intstrtoull(const char *nptr, char **endptr, int base);

strtoul () 関数は nptr の文字列の最初の部分を、 base を基数として unsigned long int に変換する。 この base は 2 から 36 までの値 あるいは特別な意味を持つ値 0 (後述)でなければならない。

文字列の先頭には、任意の数の ( isspace (3)で定められる) 空白があってもよく、また数字の直前には `+' か `-' の 符号があってもよい。 base が 0 または 16 の場合には、 文字列の先頭に `0x' を置くことが でき、その場合には文字列は 16進数として扱われる。 これ以外の文字列で base が 0 の場合は、 文字列が `0' で始まるときは 8進数として、 それ以外のときは 10進数として扱われる。

文字列の残りの部分は unsigned long int に変換されるが、基数に対して 有効でない数字が現れた時点で変換は終了する。(11進数以上では `A' は 大文字・小文字に関わらず 10 を表し、 `B' は 11 を表現し, 以下同様に、 `Z' は 35 を表す。)

endptr がヌル値 (NULL) でない場合、 strtoul () は最初に不正な文字が現れたアドレスを *endptr に格納している。 文字列に有効な数字がひとつもなければ、 strtoul () は nptr の元の値を *endptr に代入する(そして 0 を返す)。 特に、 *nptr が `\0' 以外で、戻された **endptr が `\0' ならば、文字列全体が有効だったことになる。

strtoull ()関数は strtoul ()関数と同様だが、unsigned long long int 型の値を返す。

strtoul () 関数は変換結果を返す。文字列がマイナス符号から始まっていた場 合は、(符号反転前の値がオーバーフローしていなければ) 変換結果を符号反転した 値を unsigned 型で返す。変換でオーバーフローが発生した場合は ULONG_MAX を 返し、グローバル変数 errno に ERANGE を設定する。 (ULONG_MAX を ULLONG_MAX と読み替えれば) strtoull ()は strtoul ()と全く同じである。

EINVAL

(C99 にはない) 与えられた base がサポートされていない値である。

ERANGE

文字列が数値の表現範囲外である。

実装によっては、全く変換が行われなかった場合(全く数字が現れず、 0 が返される)、errno に EINVAL がセットされるかもしれない。

strtoul () からは成功、失敗どちらの場合でも 0, LONG_MAX ( strtoull ()では LLONG_MAX) が返る可能性があるので、 プログラムは関数を呼び出す前に errno を 0 に設定し、呼び出し後に errno が 0 以外の値かどうかを確認しエラーが発生したかどうかを判断する 必要がある。
"C" 以外のロケールの場合、その他の文字列も受け付けられるかもしれない。 (例えば、現在のロケールの 1000 毎の区切り文字に対応しているかもしれない。)

BSD には、

u_quad_tstrtouq(const char *nptr, char **endptr, int base);

という完全に同様の定義を持つ関数がある。 使用中のアーキテクチャのワード長次第であるが、この関数は strtoull ()や stroul ()と等価な場合もありえる。
負の値も正当な入力とみなされ、エラーもなく、 対応する unsigned long 型の値に変換される。

strtoul ()は SVr4, C99 と POSIX-2001 に準拠している。 strtoull ()は C99 と POSIX.1-2001 に準拠している。

  strtol (3) のマニュアルページの例を参照。 このページで説明した関数の使用方法も同様である。

  atof (3),   atoi (3),  atol (3),  strtod (3),   strtol (3)