cblc/aulas/12-fgets/README.org

Curso Básico da Linguagem C

• Aula 12: Leitura da entrada padrão com 'fgets'
  • A função 'fgets'
    • Retorno nulo ambíguo
  • O problema da quebra de linha
  • Uma nota sobre o tipo ponteiro para FILE

Aula 12: Leitura da entrada padrão com 'fgets'

Vídeo desta aula

Se, por um lado, a função scanf é conveniente para ler e converter dados na entrada padrão, também é preciso considerar os cuidados que ela exige, especialmente quando lidamos com a passagem dos dados lidos para um buffer de caracteres (geralmente, criado para receber uma string). A sua principal causa de problemas é a falta de um controle simples e explícito da quantidade de bytes que poderão ser escritos na memória. Na função scanf, todo controle possível é aquele que escrevemos em sua string de formato, por exemplo:

char buf[10];
scanf("%9s", buf);

Aqui, 9 primeiros bytes lidos serão consumidos, acrescidos do terminador nulo (totalizando 10 bytes) e copiados para o endereço expresso pelo vetor buf, que foi declarado para receber até 10 bytes (incluindo o terminador nulo). Mas, pode acontecer de, um dia, nós mudarmos de ideia e reduzirmos o limite de buf, digamos, para 8 bytes. Isso exigiria uma alteração na chamada de scanf – o que pode ser facilmente esquecido!

Aliás, essa é uma das justificativas para o uso de constantes simbólicas em vez dos chamados números mágicos. Então, é comum que vetores, como o nosso vetor buf, sejam declarado assim:

#include <stdio.h>
...
#define BUFMAX 10
...
int main(...) {
    char buf[BUFMAX];
    ...
    scanf("%9s", buf);
    ...
}

E isso tornaria ainda mais arriscada qualquer modificação no tamanho definido por BUFMAX.

A função 'fgets'

Segundo sua man page, a função fgets recebe três argumentos:

char *fgets(char s[restrict .size], int size, FILE *restrict stream);

• char s[restrict .size] - Um buffer para receber os dados lidos;
• int size - A quantidade máxima de bytes a serem escritos no buffer;
• FILE *restrict stream - Uma estrutura do tipo FILE representando o fluxo de dados que será lido.

Quando chamada, a função fgets lê, no máximo, a quantidade de bytes expressa por size - 1, inclui o terminador nulo ('\0') e escreve esses bytes no buffer.

Por exemplo:

#include <stdio.h>

#define BUFMAX 10

int main(void) {
    char buf[BUFMAX];
    fgets(buf, BUFMAX, stdin);

    ...
}

Aqui, stdin é uma macro que expande uma estrutura FILE predefinida com o descritor de arquivos 0 (entrada padrão).

De pronto, fica evidente a facilidade que nós termos para alterar o tamanho do vetor buf quando necessário: basta alterar a constante simbólica BUFMAX.

Retorno nulo ambíguo

No caso de sucesso, a função fgets retorna o endereço do buffer ou NULL, no caso de um erro, ou se o fim do arquivo for alcançado sem que algo seja lido (por exemplo, ao ler um arquivo vazio ou numa leitura interativa cancelada com a combinação de teclas Ctrl+D).

Como você pode ver, o significado do retorno NULL é ambíguo, mas isso só será uma preocupação se estivermos lendo arquivos. De todo modo, nós podemos testar o que aconteceu com as funções feof e/ou ferror.

• feof(FILE *stream) - Testa o estado do indicador de fim de arquivo (0 = não difinido).
• ferror(FILE *stream) - Testa o estado do indicador de erros (0 = não definido).

Se isso for relevante, nós podemos chamar a função fgets desta forma:

#include <stdio.h>

#define BUFMAX 10

int main(void) {
    char buf[BUFMAX];
    
    if (fgets(buf, BUFMAX, stdin) == NULL) {
        // Só preciamos testar se o retorno for NULL...
        if (feof(stdin)) {
            // Se feof() retornar algo diferente de zero...  
            fprintf(stderr, "Fim de arquivo alcançado.\n");
        } else if (ferror(stdin)) {
            // Se ferror() retornar algo diferente de zero...
            fprintf(stderr, "Erro de leitura.\n");
        }
        return 1;
    }
    
    ...

    return 0;
}

O problema da quebra de linha

A função fgets lê, no máximo size - 1 bytes, o que é ótimo, mas nem sempre a linha lida terá tantos bytes. Nesses casos, a leitura será interrompida depois de uma quebra de linha (caractere '\n') ou depois de alcançado o fim do arquivo (EOF). Ou seja, se a leitura terminar com uma quebra de linha, o caractere '\n' continuará entre os bytes que serão escritos no buffer.

Observe:

#include <stdio.h>

#define BUFMAX 10

int main(void) {
    char buf[BUFMAX];

    printf("Digite até %d caracteres: ", BUFMAX - 1);
    fgets(buf, BUFMAX, stdin);
    printf("%s\n", buf);
    
    return 0;
}

Executando o programa:

:~$ ./a.out
Digite até 9 caracteres: 123456789
123456789
:~$ ./a.out
Digite até 9 caracteres: 12345
12345

:~$

Quando eu executei o programa pela primeira vez, eu digitei exatamente 9 caracteres e a quebra de linha (inserida com o Enter) não chegou a ser lida por fgets.

        +------+------+------+------+------+------+------+------+------+------+
buf[10] | 0x31 | 0x32 | 0x33 | 0x34 | 0x35 | 0x36 | 0x37 | 0x38 | 0x39 | 0x00 |
        +------+------+------+------+------+------+------+------+------+------+

Mas, na segunda vez, eu digitei apenas 5 caracteres e teclei Enter, totalizando os 6 caracteres lidos por fgets. Sendo assim, a quebra de linha final também foi escrita no buffer e impressa.

        +------+------+------+------+------+------+------+------+------+------+
buf[10] | 0x31 | 0x32 | 0x33 | 0x34 | 0x35 | 0x0A | 0x00 | lixo | lixo | lixo |
        +------+------+------+------+------+------+------+------+------+------+

Pode parecer um inconveniente se estivermos lidando com a digitação de linhas no terminal, mas não remover o caractere '\n' faz todo sentido quando estamos lendo linhas de arquivos!

De todo modo, nós podemos criar uma função para remover a quebra de linha, se for o caso:

void trim_string(char *str, int size) {
    int i = 0;
    while (i < size && str[i] != '\0') {
        if (str[i] == '\n') {
            str[i] = '\0';
            break;
        }
    }
    i++;
}

Se estiver entrando com um buffer muito grande, o tipo de size pode ser alterado para size_t (unsigned long int).

No nosso exemplo, a função trim_string poderia ser utilizada assim:

# include <stdio.h>

#define BUFMAX 10;

// Remove a quebra de linha final do buffer...
void trim_string(char *str, int size);

int main(void) {
    char buf[BUFMAX];

    printf("Digite até %d caracteres: ", BUFMAX - 1);
    fgets(buf, BUFMAX, stdin);
    trim_string(buf, BUFMAX);
    
    printf("%s\n", buf);
    
    return 0;
}

// Remove a quebra de linha final do buffer...
void trim_string(char *str, int size) {
    int i = 0;
    while (i < size && str[i] != '\0') {
        if (str[i] == '\n') {
            str[i] = '\0';
            break;
        }
    }
    i++;
}

Compilando e executando novamente:

:~$ ./a.out
Digite até 9 caracteres: 12345
12345
:~$

E o conteúdo do buffer seria:

        +------+------+------+------+------+------+------+------+------+------+
buf[10] | 0x31 | 0x32 | 0x33 | 0x34 | 0x35 | 0x00 | 0x00 | lixo | lixo | lixo |
        +------+------+------+------+------+------+------+------+------+------+

Uma nota sobre o tipo ponteiro para FILE

No nível do sistema, o acesso a arquivos é sempre estabelecido através de uma estrutura complexa identificada por um número inteiro: o descritor de arquivos, assunto da aula 10. Então, quando utilizamos chamadas de sistema, como read e write, o fluxo de dados (stream) é passado como o número de um descritor de arquivos (ex: 0 ou STDIN_FILENO, numa leitura da entrada padrão).

Nas funções da biblioteca padrão, que abstraem outras estruturas de controle associadas aos descritores de arquivos, os fluxos de dados são passados como ponteiros para essas estruturas através do tipo FILE * (ponteiro para FILE). Os fluxos de dados padrão também são abstraídos como macros definidas na biblioteca de funções:

Macro	Significado
stdin	Ponteiro para FILE associado ao descritor de arquivos 0.
stdout	Ponteiro para FILE associado ao descritor de arquivos 1.
stderr	Ponteiro para FILE associado ao descritor de arquivos 2.