_cgets_s, _cgetws_s

Obtiene una cadena de caracteres de la consola. Estas versiones de y _cgetwstienen mejoras de seguridad, como se describe en Características de _cgets seguridad de CRT.

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

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

Parámetros

buffer
Ubicación de almacenamiento de los datos.

numberOfElements
Tamaño del búfer en caracteres anchos o de un solo byte, que también es el número máximo de caracteres que se va a leer.

pSizeRead
Número de caracteres que realmente se va a leer.

Valor devuelto

El valor devuelto es cero si es correcto; en caso contrario, un código de error si se produce un error.

Condiciones de error

buffer	numberOfElements	pSizeRead	Return	Contenido de buffer
NULL	cualquiera	cualquiera	EINVAL	N/D
no NULL	zero	cualquiera	EINVAL	no modificado
no NULL	cualquiera	NULL	EINVAL	cadena de longitud cero

Comentarios

_cgets_s y _cgetws_s leen una cadena de la consola y la copian (con un terminador null) en buffer. _cgetws_s es la versión de caracteres anchos de la función; aparte del tamaño de carácter, el comportamiento de estas dos funciones es idéntico. El tamaño máximo de la cadena que se va a leer se pasa como parámetro numberOfElements. Este tamaño debe incluir un carácter adicional para el carácter null de terminación. El número real de caracteres que se leen se coloca en pSizeRead.

Si se produce un error durante la operación o en la validación de los parámetros, se invoca al controlador de parámetros no válidos, como se describe en Validación de parámetros. Si la ejecución puede continuar, errno se establece en EINVALy EINVAL se devuelve .

En C++, las sobrecargas de plantilla simplifican el uso de estas funciones. Las sobrecargas pueden deducir automáticamente la longitud del búfer, lo que elimina la necesidad de especificar un argumento size. También pueden reemplazar automáticamente las funciones más antiguas y menos seguras por sus homólogos más recientes y seguros. Para obtener más información, consulte Sobrecargas de plantillas seguras.

Las versiones de la biblioteca de depuración de estas funciones rellenan primero el búfer con 0xFE. Para deshabilitar este comportamiento, use _CrtSetDebugFillThreshold.

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_s	_cgets_s	_cgets_s	_cgetws_s

Requisitos

Routine	Encabezado necesario
_cgets_s	<conio.h>
_cgetws_s	<conio.h> o <wchar.h>

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

Consulte también

E/S de consola y puerto
_getch, _getwch