EN JA
STRTOL(3)
STRTOL(3) Linux Programmer's Manual STRTOL(3)

名前

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

書式


#include <stdlib.h>
 

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

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

glibc 向けの機能検査マクロの要件 ( feature_test_macros(7) 参照):
 
strtoll():
XOPEN_SOURCE >= 600 || _BSD_SOURCE || _SVID_SOURCE || _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L;
 
または cc -std=c99

説明

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_MINLONG_MAX の代わりに LLONG_MINLLONG_MAX が返される。

エラー

EINVAL
(C99 にはない) 指定された base がサポートされていない値である。
ERANGE
結果の値が範囲外である。

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

準拠

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

注意

strtol () からは成功、失敗どちらの場合でも 0, LONG_MAX, LONG_MIN ( strtoll() では LLONG_MAX, LLONG_MIN) が返る可能性があるので、プログラムは関数を呼び出す前に errno を 0 に設定し、呼び出し後に errno が 0 以外の値かどうかを確認しエラーが発生したかどうかを判断する必要がある。
 
According to POSIX.1-2001, in locales other than the "C" and "POSIX", these functions may accept other, implementation-defined numeric strings.

BSD には、

 



quad_t strtoq(const char *nptr, char **endptr, int base);

 



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

以下のプログラムは 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);
}

関連項目

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

この文書について

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