_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


数据的存储位置。Storage location for data.

缓冲区的大小(以单字节或宽字符为单位),这也是要读取的最大字符数。The size of the buffer in single-byte or wide characters, which is also the maximum number of characters to be read.

实际读取的字符数。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

bufferbuffer numberOfElementsnumberOfElements pSizeReadpSizeRead 返回Return 内容缓冲区Contents of buffer
NULLNULL 任何any 任何any EINVALEINVAL n/an/a
NULLnot NULL zero 任何any EINVALEINVAL 未修改not modified
NULLnot NULL 任何any NULLNULL EINVALEINVAL 零长度字符串zero-length string


_cgets_s_cgetws_s从控制台读取字符串并将字符串 (具有 null 结束符) 复制到缓冲区_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. 实际读取的字符数置于pSizeReadThe 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设置为EINVALEINVAL返回。If 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_cgetts_s _cgets_s_cgets_s _cgets_s_cgets_s _cgetws_s_cgetws_s


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

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

请参阅See also

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