_cgets、_cgetws_cgets, _cgetws

从控制台获取字符串。Gets a character string from the console. 提供这些函数的更多安全版本;请参阅 _cgets_s, _cgetws_sMore secure versions of these functions are available; see _cgets_s, _cgetws_s.

重要

这些函数已过时。These functions are obsolete. 从 Visual Studio 2015 开始,CRT 中不再提供这些函数。Beginning in Visual Studio 2015, they are not available in the CRT. 这些函数(_cgets_s 和 _cgetws_s)的安全版本仍然可用。The secure versions of these functions, _cgets_s and _cgetws_s, are still available. 有关这些备用函数的信息,请参阅 _cgets_s, _cgetws_sFor information on these alternative functions, see _cgets_s, _cgetws_s.

重要

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

语法Syntax

char *_cgets(   
   char *buffer   
);  
wchar_t *_cgetws(  
   wchar_t *buffer  
);  
template <size_t size>  
char *_cgets(   
   char (&buffer)[size]  
); // C++ only  
template <size_t size>  
wchar_t *_cgetws(  
   wchar_t (&buffer)[size]  
); // C++ only  

参数Parameters

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

返回值Return Value

buffer[2]_cgets_cgetws 返回指向字符串起始位置的指针。_cgets and _cgetws return a pointer to the start of the string, at buffer[2]. 如果 bufferNULL,这些函数则会调用无效的参数处理程序,如 Parameter ValidationIf buffer is NULL, these functions invoke the invalid parameter handler, as described in Parameter Validation. 如果允许继续执行,这些函数则返回 NULL,并将 errno 设置为 EINVALIf execution is allowed to continue, they return NULL and set errno to EINVAL.

备注Remarks

这些函数从控制台读取字符构成的字符串,并将该字符串及其长度存储在 buffer指向的位置。These functions read a string of characters from the console and store the string and its length in the location pointed to by buffer. buffer 参数必须是指向字符数组的指针。The buffer parameter must be a pointer to a character array. 数组的第一个元素 buffer[0]必须包含要读取的字符串的最大长度(以字符为单位)。The first element of the array, buffer[0], must contain the maximum length (in characters) of the string to be read. 该数组必须包含足够的元素,以保存该字符串、终止 null 字符 ('\0') 和 2 个其他字节。The array must contain enough elements to hold the string, a terminating null character ('\0'), and 2 additional bytes. 此函数会读取字符,直至读取回车符 - 换行符 (CR-LF) 组合或指定的字符数。The function reads characters until a carriage return-line feed (CR-LF) combination or the specified number of characters is read. 字符串以开头 buffer[2]进行存储。The string is stored starting at buffer[2]. 如果此函数读取 CR-LF,它会存储 null 字符 ('\0')。If the function reads a CR-LF, it stores the null character ('\0'). 然后,此函数会在第二个数组元素 buffer[1]中存储字符串的实际长度。The function then stores the actual length of the string in the second array element, buffer[1].

因为处于控制台窗口中时,如果调用 _cgets_cgetws ,所有编辑键都会处于活动状态,所以按 F3 键可以重复最后一个输入的项。Because all editing keys are active when _cgets or _cgetws is called while in a console window, pressing the F3 key repeats the last entered entry.

在 C++ 中,这些函数具有模板重载,以调用这些函数的更新、更安全副本。In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. 有关详细信息,请参阅 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 _cgets _cgets _cgetws

要求Requirements

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

有关兼容性的详细信息,请参阅兼容性For more compatibility information, see Compatibility.

示例Example

// crt_cgets.c  
// compile with: /c /W3  
// This program creates a buffer and initializes  
// the first byte to the size of the buffer. Next, the  
// program accepts an input string using _cgets and displays  
// the size and text of that string.  

#include <conio.h>  
#include <stdio.h>  
#include <errno.h>  

int main( void )  
{  
   char buffer[83] = { 80 };  // Maximum characters in 1st byte  
   char *result;  

   printf( "Input line of text, followed by carriage return:\n");  

   // Input a line of text:  
   result = _cgets( buffer ); // C4996  
   // Note: _cgets is deprecated; consider using _cgets_s  
   if (!result)  
   {  
      printf( "An error occurred reading from the console:"  
              " error code %d\n", errno);  
   }  
   else  
   {     
      printf( "\nLine length = %d\nText = %s\n",  
              buffer[1], result );  
   }  
}  

      A line of input.Input line of text, followed by carriage return:  
Line Length = 16  
Text = A line of input.  

另请参阅See Also

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