_cgets, _cgetws

Obtiene una cadena de caracteres de la consola. Hay disponibles versiones más seguras de estas funciones; consulte _cgets_s, _cgetws_s.

Importante

Estas funciones están obsoletas. A partir de Visual Studio 2015, no están disponibles en CRT. Las versiones seguras de estas funciones, _cgets_s y _cgetws_s, siguen estando disponibles. Para obtener información sobre estas funciones alternativas, vea _cgets_s, _cgetws_s.

Importante

Esta API no se puede usar en aplicaciones que se ejecutan en Windows en tiempo de ejecución. Para obtener más información, vea Funciones de CRT no admitidas en aplicaciones de la Plataforma universal de Windows.

Sintaxis

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

Parámetros

buffer
Ubicación de almacenamiento de los datos.

Valor devuelto

_cgets y _cgetws devuelven un puntero al principio de la cadena, en buffer[2]. Si buffer es NULL, estas funciones invocan al controlador de parámetros no válidos, como se describe en Validación de parámetros. Si la ejecución puede continuar, devuelven NULL y establecen errno en EINVAL.

Comentarios

Estas funciones leen una cadena de caracteres de la consola y almacenan la cadena y su longitud en la ubicación que indica buffer. El parámetro buffer debe ser un puntero a una matriz de caracteres. El primer elemento de la matriz, buffer[0], debe contener la longitud máxima (en caracteres) de la cadena que se va a leer. La matriz debe contener suficientes elementos para contener la cadena, un carácter nulo de terminación ('\0') y 2 bytes adicionales. La función lee los caracteres hasta una combinación de retorno de carro–salto de línea (CR-LF), o hasta que se lee el número de caracteres especificado. La cadena se almacena a partir de buffer[2]. Si la función lee una combinación CR-LF, almacena el carácter nulo ('\0'). A continuación, la función almacena la longitud real de la cadena en el segundo elemento de la matriz, buffer[1].

Como todas las claves de edición están activas cuando se llama a _cgets o _cgetws desde una ventana de la consola, al presionar F3 se repite la última entrada.

En C++, estas funciones tienen sobrecargas de plantilla que invocan los homólogos seguros más recientes de estas funciones. Para obtener más información, consulte Sobrecargas de plantillas seguras.

De manera predeterminada, el estado global de esta función está limitado a la aplicación. Para cambiar este comportamiento, consulte Estado global en CRT.

Asignaciones de rutinas de texto genérico

Rutina Tchar.h	_UNICODE y _MBCS no definidos	_MBCS definido	_UNICODE definido
_cgetts	_cgets	_cgets	_cgetws

Requisitos

Routine	Encabezado necesario
_cgets	<conio.h>
_cgetws	<conio.h> o <wchar.h>

Para obtener más información sobre compatibilidad, consulte Compatibilidad.

Ejemplo

// 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.

Consulte también

E/S de consola y puerto
_getch, _getwch