_cgets_s, _cgetws_s

Obtém uma cadeia de caracteres do console. Essas versões e têm aprimoramentos de segurança, conforme descrito em Recursos de _cgetws_cgets segurança na CRT.

Importante

Esta API não pode ser usada em aplicativos executados no Windows Runtime. Para obter mais informações, confira Funções do CRT sem suporte em aplicativos da Plataforma Universal do Windows.

Sintaxe

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
Local de armazenamento de dados.

numberOfElements
O tamanho do buffer em caracteres de byte único ou largos, que também é o número máximo de caracteres a serem lido.

pSizeRead
O número de caracteres de fato lidos.

Retornar valor

O valor retornado será zero se obtiver sucesso; caso contrário, um código de erro será gerado se ocorrer uma falha.

Condições de erro

buffer	numberOfElements	pSizeRead	Retorno	Conteúdo de buffer
NULL	qualquer	qualquer	EINVAL	N/D
não é NULL	zero	qualquer	EINVAL	não modificado
não é NULL	qualquer	NULL	EINVAL	cadeia de caracteres de comprimento zero

Comentários

_cgets_s e _cgetws_s leem uma cadeia de caracteres do console e copiam a cadeia de caracteres (com um terminador nulo) para buffer. _cgetws_s é a versão de caractere largo da função; além do tamanho de caractere, o comportamento dessas duas funções é idêntico. O tamanho máximo da cadeia de caracteres a ser lido é passado como no parâmetro numberOfElements. Esse tamanho deve incluir um caractere extra para a terminação nula. O número real de caracteres lidos é colocado em pSizeRead.

Se ocorrer um erro durante a operação ou na validação dos parâmetros, o manipulador de parâmetros inválido será chamado, conforme descrito em Validação de parâmetro. Se a execução tiver permissão para continuar, errno será definido como EINVALe EINVAL retornado.

No C++, o uso dessas funções é simplificado por sobrecargas de modelo. As sobrecargas podem inferir automaticamente o tamanho do buffer, o que elimina a necessidade de especificar um argumento de tamanho. Eles também podem substituir automaticamente funções mais antigas e menos seguras por suas contrapartes mais novas e mais seguras. Para obter mais informações, consulte Sobrecargas de modelo seguras.

As versões de biblioteca de depuração dessas funções preenchem o buffer com 0xFE. Para desabilitar esse comportamento, use _CrtSetDebugFillThreshold.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, consulte Estado global na CRT.

Mapeamentos de rotina de texto genérico

Rotina Tchar.h	_UNICODE e _MBCS não definidos	_MBCS definido	_UNICODE definido
_cgetts_s	_cgets_s	_cgets_s	_cgetws_s

Requisitos

Rotina	Cabeçalho necessário
_cgets_s	<conio.h>
_cgetws_s	<conio.h> ou <wchar.h>

Para obter informações sobre compatibilidade, consulte Compatibilidade.

Confira também

E/S de console e porta
_getch, _getwch