fgets  função

Protótipo

char * fgets (char * string, int tamanho, FILE * fluxo);

Descrição

Lê do fluxo para a cadeia de caracteres string até a quantidade de caracteres (tamanho - 1) ser lida ou até uma nova linha (\n) ou EOF ser encontrado. Após a leitura, a posição atual do fluxo é avançada para o próximo caractere não lido.

Para ler da entrada padrão (stdin) de forma segura, é necessário o uso desta função. Como ela limita o número de caracteres lidos pelo parâmetro tamanho, ela previne buffer overflows que possam causar erros de segurança ou crashes na aplicação.

A função fgets para caso encontre uma nova linha (\n), incluindo-a na string. Ver exemplo 1 para verificar uma aplicação desse fato (imprimir um arquivo verbatim para a saída padrão, stdout). Ver exemplo 2 para entender como contornar isso ao ler da entrada padrão.

A função lê até o (tamanho - 1) pois devemos contar o espaço para o NULL ('\0') no final da string.

Parâmetros

string - Cadeia de caracteres a ser lida.

tamanho - Número máximo de caracteres a serem lidos na cadeia de caracteres string.

fluxo - Ponteiro para um objeto FILE que será utilizado como entrada. Para ler da entrada padrão, utilizar stdin.

Valor de retorno

Em caso de sucesso, a função retorna string.

Caso aconteça um erro ao tentar ler do fluxo, o indicador de erro (ferror) é setado e fgets retorna NULL. O conteúdo da string pode ter sido modificado.

Caso o indicador de fim de arquivo (EOF) seja encontrado ao tentar ler um caractere, o indicador de EOF (feof) é setado. O retorno da função é string com uma exceção: caso o indicador de fim de arquivo EOF seja encontrado antes de qualquer caractere ter sido lido, fgets retorna NULL e a string não foi modificada.

Exemplo
#include <stdio.h>

/* programa com funcionalidade similar ao cat no Unix e type no Windows/DOS */
int main() {
    FILE* arquivo = fopen("arquivo.txt", "r");
    if(arquivo == NULL) {
        fprintf(stderr, "Erro ao abrir o arquivo.txt.");
        return 1;
    }

    char linha[1024];
    while(fgets(linha, sizeof(linha), arquivo) != NULL) {
    	/* note como não precisamos especificar uma nova linha, o fgets já a inclui na string linha quando a encontra */
        printf("%s", linha);
    }

    fclose(arquivo);

    return 0;
}
Exemplo de leitura do stdin
#include <stdio.h>
#include <string.h>

/* Atua como se fosse a fgets sendo chamada com o fluxo da entrada padrão, stdin,
   mas não inclui a nova linha na string */
char* lerStringSeguramente(char* string, int tamanho) {
	if(fgets(string, tamanho, stdin) != NULL) {
		/* Remove a nova linha (\n), caso ela tenha sido lida pelo fgets */
		int indiceUltimoCaractere = strlen(string) - 1;
		if(string[indiceUltimoCaractere] == '\n') {
			string[indiceUltimoCaractere] = '\0';
		}
		return string;
	}

	return NULL;
}

int main() {
	char string[1024]; /* uma linha é representada, normalmente, por 1024 caracteres */

	printf("Nome: ");

	/* Não existe a possibilidade de buffer overflows utilizando esse código */
	lerStringSeguramente(string, sizeof(string));
	if(lerStringSeguramente(string, sizeof(string)) != NULL) {
		printf("Seu nome é %s\n", string);
	} else {
		puts("Erro ao ler da entrada padrão.");
	}

	return 0;
}
Veja também

gets função