kazmax - Linux で自宅サーバー

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

  1. 名前
  2. 書式
  3. 説明
  4. 返り値
  5. エラー
  6. 注意
  7. 準拠
  8. 関連項目

名前

strtol, strtoll, strtoq - 文字列を long int に変換する

書式

#include <stdlib.h>

long intstrtol(const char *nptr, char **endptr, int base);
long long intstrtoll(const char *nptr, char **endptr, int base);

説明

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

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

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

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

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

返り値

アンダーフローもオーバーフローも起きなかった場合、strtol () 関数は 変換された値を返す。オーバーフローした場合には LONG_MAX が返り、 アンダーフローした場合には LONG_MIN が返る。オーバーフロー、 アンダーフローのいずれの場合にも 大域変数 errno には ERANGE が設定される。 strtoll ()も同様であるが、LONG_MIN と LONG_MAX の代わりに LLONG_MIN と LLONG_MAX が 返される。

エラー

EINVAL
(C99 にはない) base が対応していない値である。
ERANGE
結果の値が範囲外である。

実装によっては、変換が行われなかった場合 (数字がなく、0 を返した場合)、 errnoEINVAL が設定される場合がある。

注意

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

BSD には、

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


という完全に同様の定義を持つ関数がある。 使用中のアーキテクチャのワード長次第であるが、この関数は strtoll ()か strtol ()と等価となることもある。

準拠

strtol ()は SVr4, 4.3BSD, C99 と POSIX.1-2001 に準拠している。 strtoll ()は C99 と POSIX.1-2001 に準拠している。

以下のプログラムは strtol ()の使用例である。 最初のコマンドライン引き数には strtol ()が数字として解釈する文字列を指定する。 (省略可能な) 二番目の引き数には 変換に使用される基数を指定する (この引き数は   atoi (3) を使って数値に変換される。   atoi (3) は strtol ()よりも簡単なインタフェースを持つ関数で、 その中ではエラーチェックは行われない)。 このプログラムの実行例をいくつか以下に示す:


$ ./a.out 123 strtol() returned 123 $ ./a.out ' 123' strtol() returned 123 $ ./a.out 123abc strtol() returned 123 Further characters after number: abc $ ./a.out 123abc 55 strtol: Invalid argument $ ./a.out '' No digits were found $ ./a.out 4000000000 strtol: Numerical result out of range

プログラムのソースコードは以下の通り:

#include <stdlib.h> #include <limits.h> #include <stdio.h> #include <errno.h>
int main(int argc, char *argv[]) { int base; char *endptr, *str; long val;
if (argc < 2) { fprintf(stderr, "Usage: %s str [base]\n", argv[0]); exit(EXIT_FAILURE); }
str = argv[1]; base = (argc > 2) ? atoi(argv[2]) : 10;
errno = 0; /* To distinguish success/failure after call */ val = strtol(str, &endptr, base);
/* Check for various possible errors */
if ((errno == ERANGE && (val == LONG_MAX || val == LONG_MIN)) || (errno != 0 && val == 0)) { perror("strtol"); exit(EXIT_FAILURE); }
if (endptr == str) { fprintf(stderr, "No digits were found\n"); exit(EXIT_FAILURE); }
/* If we got here, strtol() successfully parsed a number */
printf("strtol() returned %ld\n", val);
if (*endptr != '\0') /* Not necessarily an error... */ printf("Further characters after number: %s\n", endptr);
exit(EXIT_SUCCESS); }

関連項目