fgets, fgetws

  • Artigo

Obter uma cadeia de caracteres de um fluxo.

Sintaxe

char *fgets(
   char *str,
   int numChars,
   FILE *stream
);
wchar_t *fgetws(
   wchar_t *str,
   int numChars,
   FILE *stream
);

Parâmetros

str
Local de armazenamento de dados.

numChars
O número máximo de caracteres a serem lidos.

stream
Ponteiro para a estrutura FILE.

Valor retornado

Cada uma dessas funções retorna str. NULL é retornado para indicar um erro ou uma condição de fim de arquivo. Use feof ou ferror para determinar se ocorreu um erro. Se str ou stream for um ponteiro nulo ou for menor ou numChars igual a zero, essa função invocará o manipulador de parâmetro inválido, conforme descrito em Validação de parâmetro. Se a execução tiver permissão para continuar, errno será definido como EINVAL e a função retornará NULL.

Para obter mais informações sobre códigos de retorno, confira errno, _doserrno, _sys_errlist e _sys_nerr.

Comentários

A função fgets lê uma cadeia de caracteres do argumento stream de entrada e o armazena em str. fgets lê os caracteres da posição atual do fluxo, incluindo o primeiro caractere de nova linha, ao final do fluxo ou até que o número de caracteres lido seja igual a numChars – 1, o que ocorrer primeiro. O resultado armazenado em str é acrescentado com um caractere nulo. O caractere de nova linha, se lido, é incluído na cadeia de caracteres.

fgetws é uma versão de caractere largo de fgets.

fgetws lê o argumento str de caractere largo como uma cadeia de caracteres multibyte ou como uma cadeia de caracteres largos quando stream é aberto no modo de texto ou no modo binário, respectivamente. Para obter mais informações sobre como usar modos de texto e binários em Unicode e E/S de fluxo multibyte, confira E/S de arquivo de modo binário e E/S de fluxo Unicode em modos de texto e binário.

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

Mapeamentos da rotina de texto genérico

Rotina TCHAR.H _UNICODE e _MBCS não definidos _MBCS definido _UNICODE definido
_fgetts fgets fgets fgetws

Requisitos

Função Cabeçalho necessário
fgets <stdio.h>
fgetws <stdio.h> ou <wchar.h>

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

Exemplo

// crt_fgets.c
// This program uses fgets to display
// the first line from a file.

#include <stdio.h>

int main( void )
{
   FILE *stream;
   char line[100];

   if( fopen_s( &stream, "crt_fgets.txt", "r" ) == 0 )
   {
      if( fgets( line, 100, stream ) == NULL)
         printf( "fgets error\numChars" );
      else
         printf( "%s", line);
      fclose( stream );
   }
}

Entrada: crt_fgets.txt

Line one.
Line two.

Saída

Line one.

Confira também

E/S de fluxo
fputs, fputws
gets, _getws
puts, _putws