_cgets_s、_cgetws_s_cgets_s, _cgetws_s

从控制台获取字符串。Gets a character string from the console. CRT 中的安全功能所述,这些 _cgets 和 _cgetws 版本具有安全性增强功能。These versions of _cgets and _cgetws have security enhancements, as described in Security Features in the CRT.


此 API 不能用于在 Windows 运行时中执行的应用程序。This API cannot be used in applications that execute in the Windows Runtime. 有关详细信息,请参阅通用 Windows 平台应用中不支持的 CRT 函数For more information, see CRT functions not supported in Universal Windows Platform apps.


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  


[out] buffer[out] buffer
数据的存储位置。Storage location for data.

[in] numberOfElements[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[in] pSizeRead
实际读取的字符数。The number of characters actually read.

返回值Return Value

如果成功,则返回值为零;否则,如果发生失败,则是错误代码。The return value is zero if successful; otherwise, an error code if a failure occurs.

错误条件Error Conditions

buffer numberOfElements pSizeRead 返回Return buffer 的内容Contents of buffer
NULL 任何any 任何any EINVAL 不可用n/a
NULLnot NULL zero 任何any EINVAL 未修改not modified
NULLnot NULL 任何any NULL EINVAL 零长度字符串zero-length string


_cgets_s_cgetws_s 从控制台读取字符串,然后将该字符串(带有 null 结束符)复制到 buffer_cgets_s and _cgetws_s read a string from the console and copy the string (with a null terminator) into buffer. _cgetws_s 是函数的宽字符版本;除了字符大小之外,这两个函数的行为相同。_cgetws_s is the wide character version of the function; other than the character size, the behavior of these two functions is identical. 要读取的字符串的最大大小作为 numberOfElements 参数传入。The maximum size of the string to be read is passed in as the numberOfElements parameter. 此大小应包括用于终止 null 的额外字符。This size should include an extra character for the terminating null. 读取的实际字符数置于 pSizeRead 中。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 . 如果允许执行继续,则将 errno 设置为 EINVAL 并返回 EINVALIf execution is allowed to continue, errno is set to EINVAL and EINVAL is returned.

在 C++ 中,模板重载简化了这些函数的使用;重载可以自动推断缓冲区长度,从而无需指定大小自变量,并且它们可以自动将较旧、不安全的函数替换为更新、更安全的函数。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. 有关详细信息,请参阅 Secure Template OverloadsFor more information, see Secure Template Overloads.

一般文本例程映射Generic-Text Routine Mappings

Tchar.h 例程Tchar.h routine 未定义 _UNICODE 和 _MBCS_UNICODE and _MBCS not defined 已定义 _MBCS_MBCS defined 已定义 _UNICODE_UNICODE defined
_cgetts_s _cgets_s _cgets_s _cgetws_s


例程Routine 必需的标头Required header
_cgets_s <conio.h><conio.h>
_cgetws_s <conio.h> 或 <wchar.h><conio.h> or <wchar.h>

有关更多兼容性信息,请参阅 兼容性For more compatibility information, see Compatibility.

请参阅See Also

控制台和端口 I/O Console and Port I/O
_getch、_getwch_getch, _getwch