_cgets_s, _cgetws_s

Gets a character string from the console. This is a version of _cgets and _cgetws with security enhancements as described in Security Features in the CRT.

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.

Return Value

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

Error Conditions

buffer

numberOfElements

pSizeRead

Return

Contents of buffer

NULL

any

any

EINVAL

n/a

not NULL

zero

any

EINVAL

not modified

not NULL

any

NULL

EINVAL

zero-length string

Remarks

_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 validating 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++, 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.

Generic-Text Routine Mappings

Tchar.h routine

_UNICODE and _MBCS not defined

_MBCS defined

_UNICODE defined

_cgetts_s

_cgets_s

_cgets_s

_cgetws_s

Requirements

Routine

Required header

_cgets_s

<conio.h>

_cgetws_s

<conio.h> or <wchar.h>

For more compatibility information, see Compatibility in the Introduction.

.NET Framework Equivalent

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

See Also

Reference

Console and Port I/O

_getch, _getwch