_cgets, _cgetws
Gets a character string from the console. More secure versions of these functions are available; see _cgets_s, _cgetws_s.
Important
These functions are obsolete. Beginning in Visual Studio 2015, they are not available in the CRT. The secure versions of these functions, _cgets_s and _cgetws_s, are still available. For information on these alternative functions, see _cgets_s, _cgetws_s.
Important
This API cannot be used in applications that execute in the Windows Runtime. For more information, see CRT functions not supported in Universal Windows Platform apps.
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
_cgets and _cgetws return a pointer to the start of the string, at buffer[2]. If buffer is NULL, these functions invoke the invalid parameter handler, as described in Parameter validation. If execution is allowed to continue, they return NULL and set errno to EINVAL.
Remarks
These functions read a string of characters from the console and store the string and its length in the location pointed to by buffer. The buffer parameter must be a pointer to a character array. The first element of the array, buffer[0], must contain the maximum length (in characters) of the string to be read. The array must contain enough elements to hold the string, a terminating null character ('\0'), and 2 extra bytes. The function reads characters until a carriage return-line feed (CR-LF) combination or the specified number of characters is read. The string is stored starting at buffer[2]. If the function reads a CR-LF, it stores the null character ('\0'). The function then stores the actual length of the string in the second array element, buffer[1].
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.
In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see Secure template overloads.
By default, this function's global state is scoped to the application. To change this behavior, see Global state in the CRT.
Generic-text routine mappings
| Tchar.h routine | _UNICODE and _MBCS not defined |
_MBCS defined |
_UNICODE defined |
|---|---|---|---|
_cgetts |
_cgets |
_cgets |
_cgetws |
Requirements
| Routine | Required header |
|---|---|
_cgets |
<conio.h> |
_cgetws |
<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.