Development Tools

strtol

Conversion of character string to integer (long type) and storing pointer in last character string

[Classification]

Standard library

[Syntax]

#include <stdlib.h>

long strtol(const char *str, char **ptr, int base);

[Return value]

Returns the converted value if the partial character string could be converted. If it could not, 0 is returned.

If an overflow occurs (because the converted value is too great), LONG_MAX or LONG_MIN is returned, and macro ERANGE is set to global variable errno.

[Description]

This function converts the first part of the character string indicated by str into a long type representation. strol first divides the input characters into the following three parts: the "first blank", "a string represented by the base number determined by the value of base and is subject to conversion into an integer", and "the last one or more character string that is not recognized (including the null character (\0))". Then strtol converts the string into an integer, and returns the result.

(1)	Specify 0 or 2 to 36 as argument base.

(a)	If base is 0

The expected format of the character string subject to conversion is of integer format having an optional + or - sign and "0x", indicating a hexadecimal number, prefixed.

(b)	If the value of base is 2 to 36

The expected format of the character string is of character string or numeric string type having an optional + or - sign prefixed and expressing an integer whose base is specified by base. Characters "a" (or "A") through "z" (or "Z") are assumed to have a value of 10 to 35. Only characters whose value is less than that of base can be used.

(c)	If the value of base is 16

"0x" is prefixed (suffixed to the sign if a sign exists) to the string of characters and numerals (this can be omitted).

(2)	The string subject to conversion is defined as the longest partial string at the beginning of the input character string that starts with the first character other than blank and has an expected format.

(a)	If the input character string is vacant, if it consists of blank only, or if the first character that is not blank is not a sign or a character or numeral that is permitted, the subject string is vacant.

(b)

If the string subject to conversion has an expected format and if the value of base is 0, the base number is judged from the input character string. The character string led by 0x is regarded as a hexadecimal value, and the character string to which 0 is prefixed but x is not is regarded as an octal number. All the other character strings are regarded as decimal numbers.

(c)	If the value of base is 2 to 36, it is used as the base number for conversion as mentioned above.

(d)	If the string subject to conversion starts with a - sign, the sign of the value resulting from conversion is reversed.

(3)	The pointer that indicates the first character string

(a)	This is stored in the object indicated by ptr, if ptr is not a null pointer.

(b)	If the string subject conversion is vacant, or if it does not have an expected format, conversion is not executed. The value of str is stored in the object indicated by ptr if ptr is not a null pointer.

Remark

This function is not reentrancy.

[Example]

#include    <stdlib.h>

void func(long ret) {

        char    *p;

        ret = strtol("10", &p, 0);      /*10 is returned to ret.*/

        ret = strtol("0x10", &p, 0);    /*16 is returned to ret.*/

        ret = strtol("10x", &p, 2);     /*2 is returned to ret, and pointer to "x" is

                                          returned to area of p.*/

        ret = strtol("2ax3", &p, 16);   /*42 is returned to ret, and pointer to "x" is

                                          returned to area of p.*/