_cgets, _cgetws

Obtém uma cadeia de caracteres do console. Versões mais seguras dessas funções estão disponíveis; confira _cgets_s, _cgetws_s.

Importante

Essas funções estão obsoletas. A partir do Visual Studio 2015, elas não estão disponíveis no CRT. As versões seguras dessas funções, _cgets_s e _cgetws_s, ainda estão disponíveis. Para obter informações sobre essas funções alternativas, confira _cgets_s, _cgetws_s.

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

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

Valor retornado

_cgets e _cgetws retornam um ponteiro para o início da cadeia de caracteres, em buffer[2]. Se buffer for NULL, essas funções invocam o manipulador de parâmetro inválido, conforme descrito em Validação de parâmetro. Se a execução puder continuar, elas retornarão NULL e definirão errno como EINVAL.

Comentários

Essas funções leem uma cadeia de caracteres do console e armazenam a cadeia de caracteres e seu comprimento no local apontado por buffer. O parâmetro buffer deve ser um ponteiro para uma matriz de caracteres. O primeiro elemento da matriz, buffer[0], deve conter o tamanho máximo (em caracteres) da cadeia de caracteres a ser lida. A matriz deve conter elementos suficientes para conter a cadeia de caracteres, um caractere nulo de terminação ('\0') e 2 bytes extras. A função lê caracteres até uma combinação de CR-LF (retorno de carro – alimentação de linha) ou o número especificado de caracteres ser lido. A cadeia de caracteres é armazenada começando em buffer[2]. Se a função ler CR-LF, ela armazenará o caractere nulo ('\0'). A função então armazena o tamanho real da cadeia de caracteres no segundo elemento de matriz, buffer[1].

Uma vez que todas as chaves de edição estão ativas quando _cgets ou _cgetws é chamado enquanto estiver em uma janela do console, pressionar a tecla F3 repete a última entrada digitada.

No C++, essas funções têm sobrecargas de modelo que invocam os equivalentes mais novos e seguros dessas funções. Para obter mais informações, consulte Sobrecargas de modelo seguras.

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

Mapeamentos de rotina de texto genérico

Rotina Tchar.h	_UNICODE e _MBCS não definidos	_MBCS definido	_UNICODE definido
_cgetts	_cgets	_cgets	_cgetws

Requisitos

Rotina	Cabeçalho necessário
_cgets	<conio.h>
_cgetws	<conio.h> ou <wchar.h>

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

Exemplo

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

Confira também

E/S de console e porta
_getch, _getwch