conteúdo da aula 12

aulas/12-fgets/README.org

@@ -0,0 +1,287 @@
+#+title: Curso Básico da Linguagem C
+#+subtitle: Aula 12: Leitura da entrada padrão com 'fgets'
+#+author: Blau Araujo
+#+startup: show2levels
+#+options: toc:3
+
+* Aula 12: Leitura da entrada padrão com 'fgets'
+
+[[https://youtu.be/ZZr9HBPo0Oc][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:
+
+#+begin_src c
+char buf[10];
+scanf("%9s", buf);
+#+end_src
+
+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:
+
+#+begin_src c
+#include <stdio.h>
+...
+#define BUFMAX 10
+...
+int main(...) {
+    char buf[BUFMAX];
+    ...
+    scanf("%9s", buf);
+    ...
+}
+#+end_src
+
+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:
+
+#+begin_example
+char *fgets(char s[restrict .size], int size, FILE *restrict stream);
+#+end_example
+
+- =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:
+
+#+begin_src c
+#include <stdio.h>
+
+#define BUFMAX 10
+
+int main(void) {
+    char buf[BUFMAX];
+    fgets(buf, BUFMAX, stdin);
+
+    ...
+}
+#+end_src
+
+#+begin_quote
+Aqui, =stdin= é uma macro que expande uma estrutura =FILE= predefinida com o
+descritor de arquivos =0= (entrada padrão).
+#+end_quote
+
+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:
+
+#+begin_src c
+#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;
+}
+#+end_src
+
+** 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:
+
+#+begin_src c
+#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;
+}
+#+end_src
+
+Executando o programa:
+
+#+begin_example
+:~$ ./a.out
+Digite até 9 caracteres: 123456789
+123456789
+:~$ ./a.out
+Digite até 9 caracteres: 12345
+12345
+
+:~$
+#+end_example
+
+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=.
+
+#+begin_example
+        +------+------+------+------+------+------+------+------+------+------+
+buf[10] | 0x31 | 0x32 | 0x33 | 0x34 | 0x35 | 0x36 | 0x37 | 0x38 | 0x39 | 0x00 |
+        +------+------+------+------+------+------+------+------+------+------+
+#+end_example
+
+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.
+
+#+begin_example
+        +------+------+------+------+------+------+------+------+------+------+
+buf[10] | 0x31 | 0x32 | 0x33 | 0x34 | 0x35 | 0x0A | 0x00 | lixo | lixo | lixo |
+        +------+------+------+------+------+------+------+------+------+------+
+#+end_example
+
+
+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:
+
+#+begin_src c
+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++;
+}
+#+end_src
+
+#+begin_quote
+Se estiver entrando com um buffer muito grande, o tipo de =size= pode ser
+alterado para =size_t= (=unsigned long int=).
+#+end_quote
+
+No nosso exemplo, a função =trim_string= poderia ser utilizada assim:
+
+#+begin_src c
+# 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++;
+}
+#+end_src
+
+Compilando e executando novamente:
+
+#+begin_example
+:~$ ./a.out
+Digite até 9 caracteres: 12345
+12345
+:~$
+#+end_example
+
+E o conteúdo do buffer seria:
+
+#+begin_example
+        +------+------+------+------+------+------+------+------+------+------+
+buf[10] | 0x31 | 0x32 | 0x33 | 0x34 | 0x35 | 0x00 | 0x00 | lixo | lixo | lixo |
+        +------+------+------+------+------+------+------+------+------+------+
+#+end_example
+
+** 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 [[../10-dataio/README.org#headline-2][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=. |