_gcvt_s

 

For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

Converts a floating-point value to a string. This is a version of _gcvt with security enhancements as described in Security Features in the CRT.

errno_t _gcvt_s(   
   char *buffer,  
   size_t sizeInBytes,  
   double value,  
   int digits   
);  
template <size_t cchStr>  
errno_t _gcvt_s(   
   char (&buffer)[cchStr],  
   double value,  
   int digits   
); // C++ only  

Parameters

[out] buffer
Buffer to store the result of the conversion.

[in] sizeInBytes
Size of the buffer.

[in] value
Value to be converted.

[in] digits
Number of significant digits stored.

Zero if successful. If a failure occurs due to an invalid parameter (see the following table for invalid values), the invalid parameter handler is invoked as described in Parameter Validation. If execution is allowed to continue, an error code is returned. Error codes are defined in Errno.h. For a listing of these errors, see errno, _doserrno, _sys_errlist, and _sys_nerr.

Error Conditions

buffersizeInBytesvaluedigitsReturnValue in buffer
NULLanyanyanyEINVALNot modified.
Not NULL (points to valid memory)zeroanyanyEINVALNot modified.
Not NULL (points to valid memory)anyany>= sizeInBytesEINVALNot modified.

Security Issues

_gcvt_s can generate an access violation if buffer does not point to valid memory and is not NULL.

The _gcvt_s function converts a floating-point value to a character string (which includes a decimal point and a possible sign byte) and stores the string in buffer. buffer should be large enough to accommodate the converted value plus a terminating null character, which is appended automatically. A buffer of length _CVTBUFSIZE is sufficient for any floating point value. If a buffer size of digits + 1 is used, the function will not overwrite the end of the buffer, so be sure to supply a sufficient buffer for this operation. _gcvt_s attempts to produce digits digits in decimal format. If it cannot, it produces digits digits in exponential format. Trailing zeros can be suppressed in the conversion.

In C++, using this function is simplified by a template overload; the overload can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see Secure Template Overloads.

The debug version of this function first fills the buffer with 0xFD. To disable this behavior, use _CrtSetDebugFillThreshold.

RoutineRequired headerOptional header
_gcvt_s<stdlib.h><error.h>

For more compatibility information, see Compatibility in the Introduction.

// crt_gcvt_s.c  
#include <stdio.h>  
#include <stdlib.h>  
#include <errno.h>  
  
int main()  
{  
  char buf[_CVTBUFSIZE];  
  int decimal;  
  int sign;  
  int err;  
  
  err = _gcvt_s(buf, _CVTBUFSIZE, 1.2, 5);  
  
  if (err != 0)  
  {  
     printf("_gcvt_s failed with error code %d\n", err);  
     exit(1);  
  }  
  
  printf("Converted value: %s\n", buf);    
  
}  

Converted value: 1.2  

ToString

Data Conversion
Floating-Point Support
atof, _atof_l, _wtof, _wtof_l
_ecvt_s
_fcvt_s
_gcvt

Show: