_cgets_s, _cgetws_s

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at _cgets_s, _cgetws_s.

Gets a character string from the console. These versions of _cgets and _cgetws have security enhancements, as described in Security Features in the CRT.

System_CAPS_ICON_important.jpg Important

This API cannot be used in applications that execute in the Windows Runtime. For more information, see CRT functions not supported with /ZW.

errno_t _cgets_s(   
   char *buffer,  
   size_t numberOfElements,  
   size_t *pSizeRead  
);  
errno_t _cgetws_s(  
   wchar_t *buffer  
   size_t numberOfElements,  
   size_t *pSizeRead  
);  
template <size_t size>  
errno_t _cgets_s(   
   char (&buffer)[size],  
   size_t *pSizeRead  
); // C++ only  
template <size_t size>  
errno_t _cgetws_s(  
   wchar_t (&buffer)[size],  
   size_t *pSizeRead  
); // C++ only  

Parameters

[out] buffer
Storage location for data.

[in] numberOfElements
The size of the buffer in single-byte or wide characters, which is also the maximum number of characters to be read.

[in] pSizeRead
The number of characters actually read.

The return value is zero if successful; otherwise, an error code if a failure occurs.

Error Conditions

buffernumberOfElementspSizeReadReturnContents of buffer
NULLanyanyEINVALn/a
not NULLzeroanyEINVALnot modified
not NULLanyNULLEINVALzero-length string

_cgets_s and _cgetws_s read a string from the console and copy the string (with a null terminator) into buffer. _cgetws_s is the wide character version of the function; other than the character size, the behavior of these two functions is identical. The maximum size of the string to be read is passed in as the numberOfElements parameter. This size should include an extra character for the terminating null. The actual number of characters read is placed in pSizeRead.

If an error occurs during the operation or in the validating of the parameters, the invalid parameter handler is invoked, as described in Parameter Validation . If execution is allowed to continue, errno is set to EINVAL and EINVAL is returned.

In C++, the use of these functions is simplified by template overloads; the overloads can infer buffer length automatically, thereby eliminating the need to specify a size argument, and they can automatically replace older, less-secure functions with their newer, more secure counterparts. For more information, see Secure Template Overloads.

Generic-Text Routine Mappings

Tchar.h routine_UNICODE and _MBCS not defined_MBCS defined_UNICODE defined
_cgetts_s_cgets_s_cgets_s_cgetws_s
RoutineRequired header
_cgets_s<conio.h>
_cgetws_s<conio.h> or <wchar.h>

For more compatibility information, see Compatibility.

Not applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.

Console and Port I/O
_getch, _getwch

Show: