_itoa_s, _ltoa_s, _ultoa_s, _i64toa_s, _ui64toa_s, _itow_s, _ltow_s, _ultow_s, _i64tow_s, _ui64tow_s
Converts an integer to a string. These functions are versions of the _itoa, _itow functions with security enhancements as described in Security features in the CRT.
Syntax
errno_t _itoa_s( int value, char * buffer, size_t size, int radix );
errno_t _ltoa_s( long value, char * buffer, size_t size, int radix );
errno_t _ultoa_s( unsigned long value, char * buffer, size_t size, int radix );
errno_t _i64toa_s( long long value, char *buffer,
size_t size, int radix );
errno_t _ui64toa_s( unsigned long long value, char *buffer,
size_t size, int radix );
errno_t _itow_s( int value, wchar_t *buffer,
size_t size, int radix );
errno_t _ltow_s( long value, wchar_t *buffer,
size_t size, int radix );
errno_t _ultow_s( unsigned long value, wchar_t *buffer,
size_t size, int radix );
errno_t _i64tow_s( long long value, wchar_t *buffer,
size_t size, int radix );
errno_t _ui64tow_s( unsigned long long value, wchar_t *buffer,
size_t size, int radix
);
// These template functions are C++ only:
template <size_t size>
errno_t _itoa_s( int value, char (&buffer)[size], int radix );
template <size_t size>
errno_t _ltoa_s( long value, char (&buffer)[size], int radix );
template <size_t size>
errno_t _ultoa_s( unsigned long value, char (&buffer)[size], int radix );
template <size_t size>
errno_t _itow_s( int value, wchar_t (&buffer)[size], int radix );
template <size_t size>
errno_t _ltow_s( long value, wchar_t (&buffer)[size], int radix );
template <size_t size>
errno_t _ultow_s( unsigned long value, wchar_t (&buffer)[size], int radix );
Parameters
value
Number to be converted.
buffer
Output buffer that holds the result of the conversion.
size
Size of buffer in characters or wide characters.
radix
The radix or numeric base to use to convert value, which must be in the range 2-36.
Return value
Zero if successful; an error code on failure. If any of the following conditions applies, the function invokes an invalid parameter handler, as described in Parameter validation.
Error conditions
| value | buffer | size | radix | Return |
|---|---|---|---|---|
| any | NULL |
any | any | EINVAL |
| any | any | <=0 | any | EINVAL |
| any | any | <= length of the result string required | any | EINVAL |
| any | any | any | radix < 2 or radix > 36 |
EINVAL |
Security issues
These functions can generate an access violation if buffer doesn't point to valid memory and isn't NULL, or if the length of the buffer isn't long enough to hold the result string.
Remarks
Except for the parameters and return value, the _itoa_s and _itow_s function families have the same behavior as the corresponding less secure _itoa and _itow versions.
In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see Secure template overloads.
The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use _CrtSetDebugFillThreshold.
The CRT includes convenient macros to define the size of the buffer required to convert the longest possible value of each integer type, including the null terminator and sign character, for several common bases. For information, see Maximum conversion count macros.
By default, this function's global state is scoped to the application. To change this behavior, see Global state in the CRT.
Generic-text routine mappings
Tchar.h routine |
_UNICODE and _MBCS not defined |
_MBCS defined |
_UNICODE defined |
|---|---|---|---|
_itot_s |
_itoa_s |
_itoa_s |
_itow_s |
_ltot_s |
_ltoa_s |
_ltoa_s |
_ltow_s |
_ultot_s |
_ultoa_s |
_ultoa_s |
_ultow_s |
_i64tot_s |
_i64toa_s |
_i64toa_s |
_i64tow_s |
_ui64tot_s |
_ui64toa_s |
_ui64toa_s |
_ui64tow_s |
Requirements
| Routine | Required header |
|---|---|
_itoa_s, _ltoa_s, _ultoa_s, _i64toa_s, _ui64toa_s |
<stdlib.h> |
_itow_s, _ltow_s, _ultow_s, _i64tow_s, _ui64tow_s |
<stdlib.h> or <wchar.h> |
These functions are Microsoft-specific. For more compatibility information, see Compatibility.
Example
This sample demonstrates the use of a few of the integer conversion functions. The _countof macro only works to determine buffer size when the array declaration is visible to the compiler, and not for parameters that have decayed to pointers.
// crt_itoa_s.c
// Compile by using: cl /W4 crt_itoa_s.c
#include <stdlib.h> // for _itoa_s functions, _countof, count macro
#include <stdio.h> // for printf
#include <string.h> // for strnlen
int main( void )
{
char buffer[_MAX_U64TOSTR_BASE2_COUNT];
int r;
for ( r = 10; r >= 2; --r )
{
_itoa_s( -1, buffer, _countof(buffer), r );
printf( "base %d: %s (%d chars)\n",
r, buffer, strnlen(buffer, _countof(buffer)) );
}
printf( "\n" );
for ( r = 10; r >= 2; --r )
{
_i64toa_s( -1LL, buffer, _countof(buffer), r );
printf( "base %d: %s (%d chars)\n",
r, buffer, strnlen(buffer, _countof(buffer)) );
}
printf( "\n" );
for ( r = 10; r >= 2; --r )
{
_ui64toa_s( 0xffffffffffffffffULL, buffer, _countof(buffer), r );
printf( "base %d: %s (%d chars)\n",
r, buffer, strnlen(buffer, _countof(buffer)) );
}
}
base 10: -1 (2 chars)
base 9: 12068657453 (11 chars)
base 8: 37777777777 (11 chars)
base 7: 211301422353 (12 chars)
base 6: 1550104015503 (13 chars)
base 5: 32244002423140 (14 chars)
base 4: 3333333333333333 (16 chars)
base 3: 102002022201221111210 (21 chars)
base 2: 11111111111111111111111111111111 (32 chars)
base 10: -1 (2 chars)
base 9: 145808576354216723756 (21 chars)
base 8: 1777777777777777777777 (22 chars)
base 7: 45012021522523134134601 (23 chars)
base 6: 3520522010102100444244423 (25 chars)
base 5: 2214220303114400424121122430 (28 chars)
base 4: 33333333333333333333333333333333 (32 chars)
base 3: 11112220022122120101211020120210210211220 (41 chars)
base 2: 1111111111111111111111111111111111111111111111111111111111111111 (64 chars)
base 10: 18446744073709551615 (20 chars)
base 9: 145808576354216723756 (21 chars)
base 8: 1777777777777777777777 (22 chars)
base 7: 45012021522523134134601 (23 chars)
base 6: 3520522010102100444244423 (25 chars)
base 5: 2214220303114400424121122430 (28 chars)
base 4: 33333333333333333333333333333333 (32 chars)
base 3: 11112220022122120101211020120210210211220 (41 chars)
base 2: 1111111111111111111111111111111111111111111111111111111111111111 (64 chars)