Entrada e saída de arquivos em C

Um arquivo é um conjunto de dados armazenados; um fluxo é o canal que um programa em execução usa para acessá-lo. As mesmas funções de fluxo também podem funcionar com um terminal ou um canal entre processos. Inclua <stdio.h> e mantenha o ponteiro do fluxo em uma variável do tipo FILE *.

O que o fluxo mantém

O objeto FILE da biblioteca acompanha um buffer, a posição atual no arquivo e os indicadores de fim de arquivo e de erro. Passe seu ponteiro a funções como fgetc e fprintf; não examine nem altere seus campos. Uma leitura ou escrita avança a posição para depois dos dados processados. Em um arquivo binário que começa com "hello\nworld\n", ler os primeiros seis bytes deixa a próxima leitura no w.

O armazenamento em buffer agrupa pequenas operações em transferências maiores. Uma escrita bem-sucedida pode significar que os dados chegaram a um buffer na memória, com a transferência para o sistema operacional ainda pendente. fflush(fp) envia a saída pendente ao sistema operacional. fclose(fp) faz isso antes de liberar o fluxo. Nenhuma das duas garante que os dados sobreviverão a uma queda repentina de energia.

Arquivos comuns abertos com fopen são totalmente armazenados em buffer. Dispositivos interativos podem usar um armazenamento em buffer diferente. Um terminal ou canal entre processos não fornece posições comuns de arquivo para avançar e retroceder.

Escolha o modo texto ou binário

O modo texto trata linhas legíveis por pessoas. O modo binário preserva os valores dos bytes sem conversões de texto. Acrescente b ao modo de abertura para dados binários: "rb" lê e "wb" grava esses dados. Imagens, dados compactados e registros brutos precisam do modo binário, mesmo que uma versão em modo texto pareça funcionar em seu computador.

No Linux e no macOS, uma nova linha é um byte LF, 0x0A, e os dois modos normalmente se comportam da mesma forma. No Windows, a saída em modo texto converte '\n' nos dois bytes CR LF, 0x0D 0x0A. A entrada em modo texto converte CR LF de volta em um '\n'. A entrada em modo texto da Microsoft também reconhece 0x1A, Ctrl+Z, como fim de arquivo.

Por exemplo, gravar "a\nb\nc\n" em modo texto produz seis bytes no Linux ou no macOS e nove no Windows. Três letras contribuem com três bytes; três finais de linha do Windows contribuem com seis. Ler o arquivo do Windows em modo texto no Windows fornece seis caracteres, enquanto o modo binário expõe todos os nove bytes.

Separe os bytes do arquivo de seu texto

Uma linha criada no Windows e lida no Linux pode manter "\r\n". Remover apenas '\n' deixa '\r', o que pode fazer uma comparação com "yes" falhar. Uma posição em um fluxo de texto também pode refletir o estado da conversão, portanto salve e restaure posições em texto em vez de calcular deslocamentos de bytes.

A garantia de que o texto retornará exatamente como foi gravado em C aplica-se a caracteres imprimíveis, tabulações e novas linhas, sem espaço imediatamente antes de uma nova linha e com uma nova linha ao final da última linha. Outras sequências de bytes devem ser colocadas em fluxos binários. Bytes em C têm pelo menos oito bits; exemplos que envolvem valores de byte de 0 a 255 e formatos de arquivo comuns usam bytes de oito bits.

Escolha um modo de abertura antes de escrever qualquer código de processamento. O modo controla se o arquivo deve existir, se seu conteúdo será preservado e para onde vão as escritas. fopen age imediatamente sobre o arquivo: uma abertura bem-sucedida com "w" apaga um arquivo existente mesmo que nenhuma escrita posterior ocorra.

Escolha o modo adequado à tarefa

Acrescente b para o modo binário; "r+b" e "rb+" significam a mesma coisa. O C11 acrescenta a criação exclusiva com x em modos de escrita, como "wx" e "wbx": a abertura falha se o arquivo existir. Use uma cadeia de modo documentada; letras adicionais de modo não são portáveis.

Verifique antes de usar o ponteiro

fopen retorna um novo ponteiro de fluxo em caso de sucesso e NULL em caso de falha. Arquivos ausentes, caminhos inacessíveis e diretórios ausentes podem causar falha.

FILE *fp = fopen("scores.txt", "r");
if (fp == NULL) {
    fprintf(stderr, "Cannot open scores.txt\n");
    return EXIT_FAILURE;
}
/* Read through fp here. */
if (fclose(fp) == EOF) {
    fprintf(stderr, "Cannot close scores.txt\n");
    return EXIT_FAILURE;
}

O trecho usa <stdio.h> e <stdlib.h>. Funções como fgetc, fprintf e fclose precisam de um fluxo válido; passar NULL causa comportamento indefinido. fflush(NULL) é uma exceção deliberada que descarrega todos os fluxos de saída.

fclose retorna 0 em caso de sucesso e EOF em caso de falha. Depois de chamada, o fluxo está encerrado, inclusive quando o fechamento informa um erro. Não tente novamente fclose no mesmo ponteiro nem o use para mais operações de entrada e saída. Feche os arquivos assim que possível: os fluxos disponíveis são limitados, e C garante suporte a pelo menos oito fluxos abertos, incluindo os três padrão.

Resolva caminhos a partir do programa em execução

Um caminho relativo, como "data/input.txt", começa no diretório de trabalho atual, não na pasta do arquivo-fonte. Iniciar o programa em outro lugar muda o que esse caminho identifica. Barras normais também funcionam com a biblioteca C da Microsoft. Uma barra invertida em uma cadeia de caracteres em C deve ser duplicada, como em "C:\\data\\in.txt"; caso contrário, uma sequência de escape como \n pode alterar a cadeia.

Para nomes fornecidos na linha de comando, use int main(int argc, char *argv[]). Em um comando de cópia com dois nomes, argc deve ser 3, argv[1] é o nome da entrada e argv[2] é o nome da saída. Abra primeiro a entrada para que um nome de entrada digitado incorretamente não crie nem apague a saída. Se a abertura da saída falhar, feche a entrada já aberta. Use arquivos distintos para entrada e saída: abrir primeiro a entrada não a protege se o nome da saída identificar o mesmo arquivo.

Um retorno normal de main ou exit fecha os fluxos, mas fechamentos explícitos permitem que o programa detecte erros de saída tardios. Um encerramento inesperado pode causar perda de dados armazenados em buffer; abort não oferece a garantia de liberação de recursos de uma saída normal.

Um programa em C começa com três fluxos abertos: entrada padrão stdin, saída padrão stdout e saída de erro padrão stderr. Eles geralmente se conectam ao terminal, mas o shell pode conectá-los a arquivos ou outros programas. Você pode passá-los diretamente às funções de fluxo.

Mantenha resultados separados de diagnósticos

printf escreve em stdout; scanf lê de stdin. getchar() lê um caractere de stdin, e putchar(c) escreve um em stdout. puts(s) escreve uma cadeia de caracteres em stdout e acrescenta uma nova linha. Suas formas com fluxo permitem que o mesmo código funcione com um arquivo:

void print_total(FILE *out, int total)
{
    fprintf(out, "Total: %d\n", total);
}

Chamar print_total(stdout, 12) exibe um resultado; passar um ponteiro de arquivo aberto direciona o mesmo formato a um arquivo. Em código de produção, faça a função auxiliar informar uma falha de escrita à função chamadora.

Escreva diagnósticos com fprintf(stderr, ...). Assim, um programa de processamento de dados pode produzir um arquivo de resultados sem mensagens misturadas e explicar falhas separadamente. Um erro exibido em stdout pode corromper os dados que outro programa espera ler.

Deixe o shell escolher as conexões

Em um shell semelhante ao Unix, este comando separa os três fluxos:

./sortnums < numbers.txt > sorted.txt 2> errors.txt

< fornece a entrada, > cria ou substitui a saída, >> acrescenta à saída e 2> redireciona erros. Os operadores de redirecionamento também funcionam no Prompt de Comando do Windows, onde o nome do programa costuma ser escrito como sortnums.exe. Um canal entre processos, como em generate | sortnums, envia a saída padrão do primeiro programa para a entrada padrão do segundo. Por padrão, ele não transporta stderr.

Um filtro pode aceitar um nome de entrada opcional e, caso contrário, ler stdin. Acompanhe a responsabilidade pela liberação: feche um fluxo que sua função abriu, mas deixe um fluxo emprestado para quem é responsável por ele. Para um filtro simples de linha de comando, if (in != stdin) identifica o arquivo que ele próprio abriu.

Descarregue mensagens antes de esperar pela entrada

Um terminal geralmente faz stdout ser armazenado em buffer por linha. Um arquivo redirecionado ou canal entre processos geralmente faz com que seja totalmente armazenado em buffer. stderr não é totalmente armazenado em buffer. Isso explica por que a ordem da saída pode mudar quando ambos os fluxos são enviados ao mesmo destino.

Após printf("Saving..."), o texto pode permanecer no buffer porque não há nova linha. Use fflush(stdout) e verifique se houve EOF quando ele precisar aparecer antes da próxima operação. Descarregar envia a saída pendente; não lê nem descarta entrada. O padrão C não define fflush(stdin) como uma operação de limpeza de entrada. Para descartar uma linha, leia caracteres até '\n' ou EOF.

Se um programa exibir duas linhas em stdout e um aviso em stderr entre elas, um terminal geralmente mostrará a ordem do programa. Com > out.txt 2>&1, o aviso pode chegar ao arquivo antes da saída padrão armazenada em buffer. Não use a ordem de exibição de fluxos misturados como registro da ordem de execução.

Retorne um resultado utilizável por scripts

Retorne EXIT_SUCCESS ou 0 quando o trabalho completo for bem-sucedido e EXIT_FAILURE quando falhar. Ambas as macros são declaradas em <stdlib.h>. Um comando de shell como convert in.csv out.txt && echo done executa o segundo comando somente após o sucesso. Um código de saída fiel ao resultado é tão importante quanto um diagnóstico útil.

A entrada e saída de caracteres é útil quando cada caractere determina o que acontece em seguida: contar separadores, mudar entre maiúsculas e minúsculas ou reconhecer um formato de texto simples. fgetc lê um caractere, e fputc grava um. Ambas são declaradas em <stdio.h>.

Mantenha o valor de retorno em um int

fgetc(fp) retorna o caractere como um unsigned char convertido para int, ou a constante negativa EOF quando nenhum caractere está disponível porque a entrada terminou ou uma leitura falhou. Nos sistemas usuais com bytes de oito bits, os valores válidos de byte vão de 0 a 255. Um int mantém esses valores distintos de EOF.

int c;
while ((c = fgetc(in)) != EOF) {
    if (fputc(c, out) == EOF) {
        /* Report a write failure and clean up. */
        break;
    }
}
/* Check ferror(in) before declaring the input complete. */

Um char simples pode perder essa distinção. Com char com sinal, o byte 0xFF pode se tornar -1 e parecer fim de arquivo. Com char sem sinal, o valor negativo EOF é convertido em byte e nunca pode ser comparado como igual a EOF.

Mantenha os dois parênteses ao redor da atribuição. Em c = fgetc(in) != EOF, a comparação ocorre primeiro, portanto c recebe 1 ou 0 em vez do caractere. getc faz o mesmo trabalho de leitura e pode ser uma macro; fputc retorna o caractere gravado ou EOF.

Conte leituras bem-sucedidas, não tentativas

A condição do laço deve executar a leitura. feof descreve uma tentativa anterior que chegou ao fim; ela não pode prever a próxima tentativa. Um laço que verifica !feof(in) e depois conta incondicionalmente acrescenta uma passagem extra ao final.

Para o texto "hi\nyo\n", seis leituras bem-sucedidas fornecem seis caracteres e dois caracteres de nova linha. Contar apenas caracteres de nova linha funciona para linhas terminadas em nova linha. O texto "red\ngreen\nblue" tem duas novas linhas, mas três linhas, pois o "blue" final ainda é uma linha.

Para incluir uma linha final sem nova linha, acompanhe também o último caractere:

size_t lines = 0;
int c, last = '\n';
while ((c = fgetc(in)) != EOF) {
    if (c == '\n') ++lines;
    last = c;
}
if (last != '\n') ++lines;

Iniciar last com '\n' faz um arquivo vazio contar como zero linhas. Um erro de leitura ainda exige um caminho de falha separado; uma contagem parcial não é um resultado completo.

Transforme ou examine o próximo caractere

toupper de <ctype.h> pode mudar letras antes da escrita. Um resultado bem-sucedido de fgetc já está na faixa de entrada válida para toupper, portanto fputc(toupper(c), out) é seguro dentro do laço. Valores arbitrários de char com sinal precisam ser convertidos para unsigned char antes de serem passados a funções de classificação de caracteres.

ungetc(c, in) devolve um caractere ao fluxo para que a próxima leitura o retorne novamente. A devolução de um caractere é garantida; verifique se houve EOF para detectar falha na devolução. Isso ajuda um analisador a examinar o próximo caractere sem perdê-lo. Uma operação de posicionamento descarta o caractere devolvido.

A contagem descreve o que o modo de fluxo selecionado fornece. No Windows, o modo texto conta um par CR LF como um '\n'; o modo binário expõe ambos os bytes. Portanto, uma contagem de caracteres por um fluxo de texto não precisa ser igual à contagem de bytes armazenados.

A entrada e saída formatada converte valores de C em texto legível e vice-versa. fprintf grava no formato que você escolher; fscanf lê valores que correspondem a um formato. Suas especificações de conversão parecem semelhantes, mas a entrada exige ponteiros para os tipos corretos de destino.

Escreva valores legíveis

Use %d para um int, %ld para um long, %zu para um size_t, %s para uma cadeia de caracteres e %c para um caractere. Na saída, %f exibe um double; um argumento float é promovido a double. %% exibe um sinal de porcentagem.

int result = fprintf(fp, "%-8s%6.2f\n", "Oslo", 3.14159);
if (result < 0) {
    /* Handle a write failure. */
}

%-8s alinha "Oslo" à esquerda em oito colunas; %6.2f alinha "3.14" à direita em seis. A linha resultante é "Oslo 3.14\n", e o retorno é 15 caracteres. A largura de campo é um mínimo, não um limite de comprimento da saída. A precisão também altera a informação armazenada: %.2f grava 3.14159 como "3.14", portanto esses dígitos adicionais não podem ser recuperados do arquivo.

Um programa simples de escrita de CSV pode gerar "Lima,2024,19.5" com uma ordem fixa e vírgulas entre os campos. Texto que contém vírgulas, aspas ou novas linhas precisa de delimitação de campos CSV com aspas. Delimite esse campo com aspas duplas e duplique qualquer aspa dentro dele. Um programa de escrita que usa apenas %s é adequado somente quando os campos de texto não contêm esses caracteres.

Formate em um arranjo com limite

sprintf não tem argumento de tamanho de destino. Formatar "007.jpg" exige oito bytes, incluindo o terminador nulo. Prefira snprintf:

char name[32];
int n = snprintf(name, sizeof name, "%03d.jpg", 7);
if (n < 0 || (size_t)n >= sizeof name) {
    /* Formatting failed or the full result did not fit. */
}

O retorno não negativo é o comprimento que o texto completo exigiria, excluindo o terminador nulo. Um valor igual ao tamanho do buffer já significa truncamento. Verifique se o resultado é negativo antes de convertê-lo para size_t.

Leia a quantidade esperada de valores

char name[20];
int age;
int matched = fscanf(fp, "%19s %d", name, &age);

Essa chamada só é totalmente bem-sucedida se retornar 2. A largura 19 deixa um byte para o terminador. O nome do arranjo fornece seu endereço; o inteiro precisa de &age. Para entrada, %f precisa de float *, enquanto %lf precisa de double *. Uma incompatibilidade causa comportamento indefinido, não uma conversão inofensiva.

A maioria das conversões pula caracteres de espaço em branco iniciais, incluindo novas linhas. Portanto, fscanf não exige um registro por linha, e %s não consegue ler "New York" como um único valor. Um conjunto de leitura como %19[^,] lê até uma vírgula; a leitura da linha inteira costuma ser mais clara para registros.

Em "10 abc 20", %d primeiro armazena 10 e retorna 1. A próxima chamada retorna 0 porque "abc" não corresponde; esse texto permanece sem leitura. Testar != EOF repete a falha indefinidamente. Teste == 1 e depois trate dados inválidos separadamente do fim da entrada ou de um erro de fluxo. Um resultado de conversão é uma contagem de valores atribuídos, não um valor de verdade para o arquivo inteiro.

Ler uma linha completa antes de analisá-la mantém cada registro de texto separado. Se um registro for inválido, você pode informar o número da linha e continuar com o próximo. fgets limita o quanto grava, mas você ainda precisa lidar com novas linhas mantidas e linhas maiores que o arranjo.

Leia para um buffer de capacidade conhecida

char line[256];
while (fgets(line, sizeof line, fp) != NULL) {
    /* Process this successful read. */
}
if (ferror(fp)) {
    /* Report an interrupted read. */
}

fgets lê no máximo um caractere a menos que a capacidade, para após uma nova linha se encontrar uma e acrescenta um terminador nulo. Retorna o buffer em caso de sucesso. Um resultado NULL significa que não havia caracteres disponíveis no fim do arquivo ou que ocorreu um erro; não processe o buffer após um erro de leitura.

sizeof line fornece a capacidade do arranjo nesse escopo. Em uma função auxiliar cujo parâmetro é char *line, ele é o tamanho do ponteiro. Passe a capacidade real separadamente. A antiga função gets não consegue limitar a entrada e foi removida no C11.

Reconheça partes de linhas longas

Com char buf[8], "temperature\n" chega como "tempera" e depois "ture\n". A primeira chamada usa sete bytes para caracteres e um para o terminador. Uma leitura bem-sucedida sem nova linha pode ser uma parte de uma linha longa ou a parte final sem nova linha no fim do arquivo.

Escolha uma política: una as partes em um registro maior, processe-as como uma sequência contínua ou rejeite o registro e descarte todas as partes restantes. Para um limite de tamanho, examine o próximo caractere antes de rejeitar um buffer exatamente cheio. Uma nova linha em seguida completa o registro; EOF sem erro de fluxo completa uma linha final sem nova linha; outro caractere significa que há mais conteúdo. Devolva um caractere ao fluxo somente se o código posterior precisar lê-lo novamente.

Remova apenas um final de linha encontrado

Depois de decidir se o registro está completo, remova os finais de linha:

line[strcspn(line, "\r\n")] = '\0';

strcspn de <string.h> encontra o primeiro caractere listado ou o terminador existente se nenhum dos dois ocorrer. Isso trata tanto CR LF mantido quanto LF. Excluir line[strlen(line) - 1] incondicionalmente pode remover dados reais de uma linha final sem nova linha e é inválido para uma cadeia vazia.

fputs(line, out) grava a cadeia sem acrescentar uma nova linha; puts(line) grava em stdout e acrescenta uma. Uma cópia de texto pode passar cada parte lida com sucesso por fgets para fputs, verificando se houve falha, mesmo quando uma linha longa ocupa várias partes. Para obter exatamente os bytes originais, use entrada e saída binária em blocos.

Analise e valide separadamente

sscanf(line, "%d %9s", &qty, item) retorna 2 para "7 apples" e 0 para "seven apples". Uma análise malsucedida não deixa um elemento inválido preso no fluxo de entrada porque a linha já foi lida. Conversões numéricas com sscanf ainda exigem entrada representável; use strtol para uma verificação rigorosa de faixa.

Para strtol, limpe errno, passe um ponteiro de fim da conversão e verifique a ausência de dígitos, ERANGE e texto inesperado ao final. Em "42abc", o resultado 42 é apenas um prefixo numérico. Para um campo de número inteiro, permita os caracteres de espaço em branco finais escolhidos e depois exija o fim da cadeia. Verifique a faixa do tipo de destino antes de converter um long válido para int, de faixa menor.

A entrada e saída binária transfere os bytes de objetos sem convertê-los em números ou palavras legíveis. fread e fwrite recebem um endereço, um tamanho de elemento, uma quantidade de elementos e um fluxo. Seus valores de retorno contam elementos completos, portanto a escolha do tamanho do elemento determina o que você pode saber pelo resultado.

Grave e leia arranjos

int a[5] = {1, 2, 3, 4, 5};
if (fwrite(a, sizeof a[0], 5, out) != 5) {
    /* Handle a write failure. */
}

Em um sistema com int de quatro bytes, isso grava 20 bytes e retorna 5. A leitura para outro arranjo de cinco elementos com a mesma representação pode recuperar os valores. Use "wb" e "rb" para que conversões de texto não alterem os bytes.

Para um único objeto, passe seu endereço: fwrite(&rec, sizeof rec, 1, out). Para objetos acessados por um ponteiro p, use fwrite(p, sizeof *p, count, out). sizeof p mede o ponteiro, e &p aponta para a própria variável ponteiro. Nenhum dos dois expressa a transferência de dados pretendida. Quando o tamanho ou a quantidade de elementos é zero, ambas as funções retornam zero sem transferir dados.

Copie exatamente os bytes lidos

unsigned char buf[512];
size_t n;
while ((n = fread(buf, 1, sizeof buf, in)) > 0) {
    if (fwrite(buf, 1, n, out) != n) {
        /* Handle failure and stop copying. */
        break;
    }
}

Um tamanho de elemento de 1 faz de n uma contagem de bytes. Uma entrada de 1300 bytes fornece 512, 512 e 276 bytes, depois zero. A última escrita deve usar 276, não a capacidade 512. Gravar o buffer inteiro acrescenta 236 bytes restantes de leituras anteriores.

Com fread(buf, 512, 1, in), a mesma entrada retorna 1, 1 e depois 0. Os últimos 276 bytes são apenas um elemento parcial; eles não são contados, e o valor desse elemento parcial é indeterminado. Escolha elementos de um byte quando um bloco final parcial for útil. Escolha elementos do tamanho de um registro quando registros incompletos precisarem ser rejeitados.

Um retorno menor que o solicitado de fread pode significar fim de arquivo ou erro. Verifique ferror após a cópia e verifique fclose na saída: uma escrita aceita em um buffer pode falhar mais tarde. Um cabeçalho ou registro parcial nunca deve ser tratado como um objeto completo.

Examine assinaturas e objetos armazenados

Use unsigned char para bytes brutos; em sistemas com bytes de oito bits, ele armazena valores de 0 a 255 sem valores negativos. Dados JPEG começam com 0xFF 0xD8. Fotos de câmeras e celulares frequentemente continuam com um marcador APPn, produzindo o padrão de recuperação de FF D8 FF E0 a FF D8 FF EF. Esse padrão é um teste útil para identificar candidatos; valide o formato antes de confiar nele. Alguns arquivos JPEG usam um segmento seguinte diferente.

Uma estrutura com char name[20] e um int score costuma ocupar 24 bytes. Uma escrita bruta inclui todos os seus bytes armazenados, inclusive o preenchimento de alinhamento. Um membro ponteiro salva um endereço, não a cadeia para a qual aponta. Use um arranjo dentro da estrutura ou grave o comprimento e os caracteres da cadeia separadamente.

Texto legível pode ocupar mais espaço: "1000000\n" usa oito bytes no Linux e nove no modo texto do Windows. Um inteiro de 32 bits codificado explicitamente usa quatro bytes de oito bits. O armazenamento bruto de objetos é compacto, mas vincula o arquivo à representação usada por quem o produziu.

Um fluxo binário preserva bytes, mas duas máquinas podem interpretar os mesmos bytes de formas diferentes. Um formato portável define o significado de cada byte em vez de adotar qualquer leiaute que o compilador atribua a um objeto.

Especifique tamanhos, ordem e leiaute

Três aspectos tornam uma cópia bruta de objeto dependente da máquina:

A ordem do byte menos significativo primeiro armazena esse byte primeiro. A ordem do byte mais significativo primeiro armazena esse byte primeiro. O valor 258, hexadecimal 0x00000102, é 02 01 00 00 na ordem do byte menos significativo primeiro e 00 00 01 02 na ordem do byte mais significativo primeiro.

Um leiaute comum de estrutura para um char seguido de um int ocupa oito bytes: um byte para o caractere, três bytes de preenchimento de alinhamento e quatro para o inteiro. Os valores do preenchimento não são especificados. Tipos de largura exata de <stdint.h>, como uint32_t, fixam as larguras em bits quando disponíveis; eles não fixam a ordem dos bytes nem removem o preenchimento. Exemplos de formatos de arquivo comuns pressupõem bytes de oito bits e a disponibilidade desses tipos.

Decodifique campos explicitamente

Leia quatro bytes por completo antes de interpretá-los. Para um campo na ordem do byte menos significativo primeiro:

uint32_t v = (uint32_t)b[0]
           | (uint32_t)b[1] << 8
           | (uint32_t)b[2] << 16
           | (uint32_t)b[3] << 24;

Aqui, b é um arranjo de bytes sem sinal. Cada conversão explícita de tipo ocorre antes do deslocamento, portanto a operação aritmética tem a largura sem sinal necessária. Para codificar, extraia os oito bits menos significativos, depois os oito seguintes e assim por diante. Verifique cada operação de saída. Gravar v diretamente com fwrite colocaria novamente no formato a ordem dos bytes da máquina.

Defina um formato pequeno e completo

Um formato de pontuações pode usar "SCR1" como assinatura de quatro bytes, uma contagem de quatro bytes na ordem do byte menos significativo primeiro e registros compostos de 20 bytes para o nome mais quatro bytes para a pontuação nessa mesma ordem. A assinatura também identifica a versão. O cabeçalho tem oito bytes; cada registro tem exatamente 24 bytes.

Cinco registros ocupam 128 bytes. O registro de índice 3 começa no byte 80: pule os oito bytes do cabeçalho e três registros completos. Em um formato real, indique a codificação do campo de nome e a regra de terminação ou preenchimento; um campo de nome fixo de 20 bytes não é automaticamente uma cadeia de caracteres em C.

Verifique o comprimento completo e a assinatura de um cabeçalho antes de usar seus campos. Depois, verifique as contagens e os comprimentos em relação a limites razoáveis e aos dados disponíveis antes de alocar memória. Uma contagem plausível não basta se faltarem registros posteriores.

Leia a estrutura real do formato

Alguns arquivos PCM WAV têm um cabeçalho simples de 44 bytes, com a taxa de amostragem nos bytes 24 a 27. Os bytes 44 AC 00 00 são decodificados como 44.100 amostras por segundo. Outros arquivos WAV contêm blocos adicionais, portanto um leitor geral acompanha os identificadores e tamanhos dos blocos para localizar o bloco fmt . Supor um leiaute fixo de cabeçalho para todos os arquivos pode fazer com que um campo sem relação seja lido como a taxa.

Texto como CSV evita problemas de tamanho de inteiro, ordem dos bytes e preenchimento de alinhamento de estruturas e é fácil de examinar. Ele ainda precisa de um leiaute de campos definido, regras de delimitação com aspas e análise verificada. Escolha-o quando legibilidade e intercâmbio forem mais importantes que uma representação binária compacta.

Leituras sequenciais percorrem os dados em ordem. O acesso aleatório permite que um programa salte para um local conhecido, como um registro em um arquivo grande. O posicionamento só funciona quando o fluxo subjacente oferece suporte a ele, e o significado de uma posição difere entre fluxos binários e de texto.

Consulte e altere a posição

ftell(fp) retorna uma posição long ou -1L em caso de falha. Em um arquivo binário, uma posição conta os bytes desde o início. fseek(fp, offset, whence) move em relação a um ponto de referência selecionado e retorna 0 em caso de sucesso e um valor diferente de zero em caso de falha.

Por exemplo, fseek(fp, -4L, SEEK_END) solicita a posição dos últimos quatro bytes de um arquivo binário em um sistema que aceite posicionamento relativo ao fim. Verifique o resultado antes de ler. Uma solicitação em um canal entre processos ou terminal, ou para uma posição anterior ao início de um arquivo comum, pode falhar.

Calcule a posição de um registro

Para registros binários de tamanho fixo sem cabeçalho, o índice iniciado em zero multiplicado pela largura do registro fornece o deslocamento inicial. Com registros de 24 bytes, o índice 3 começa no byte 72. Após a leitura do registro inteiro, a posição é 96.

long offset = 3L * (long)sizeof(struct record);
if (fseek(fp, offset, SEEK_SET) != 0) {
    /* Handle the failed move before reading. */
}

Este exemplo pressupõe que o arquivo foi gravado com o mesmo leiaute de estrutura. Um formato portável especificado usa a largura de registro definida por ele. Inclua os bytes do cabeçalho quando houver um. O terceiro registro contado a partir de 1 tem índice 2, não índice 3. Para índices grandes, valide a multiplicação e verifique se o resultado cabe em long antes de posicionar o fluxo.

Nos sistemas mais comuns, posicionar no fim e usar ftell pode medir um arquivo binário: um arquivo de 120 bytes com registros de 24 bytes contém cinco registros. Verifique ambas as chamadas e restaure a posição depois. O padrão C não exige um SEEK_END significativo para todo fluxo binário, portanto o método depende do suporte desse fluxo.

Salve posições em texto sem operações aritméticas

O modo texto pode converter finais de linha. Uma posição em texto retornada é uma informação para voltar a um local, não uma contagem à qual somar ou da qual subtrair. Um posicionamento em texto com deslocamento diferente de zero usa um valor retornado anteriormente por ftell para o mesmo arquivo, com SEEK_SET. Um deslocamento zero é permitido com qualquer ponto de referência.

rewind(fp) retorna ao início e limpa os indicadores de fim de arquivo e de erro. Ela não retorna resultado, portanto use fseek(fp, 0L, SEEK_SET) com verificação quando for necessário confirmar que a movimentação teve sucesso. Uma chamada bem-sucedida a fseek limpa o indicador de fim de arquivo e descarta o caractere devolvido com ungetc, mas mantém ativado um indicador de erro existente.

Mantenha um valor de posição

fgetpos(fp, &pos) salva uma posição em fpos_t; fsetpos(fp, &pos) a restaura. Verifique se ambas retornam um valor diferente de zero, que indica falha. Trate fpos_t como um valor opaco, sem operações aritméticas. Ele pode conter informações de posição além de uma simples contagem de bytes.

fseek e ftell usam long, que costuma ter 32 bits no Windows e limita as posições representáveis a cerca de 2 GiB. Um valor de posição evita vincular a interface a long, mas o tamanho de arquivo aceito ainda depende da implementação e da configuração.

Um fluxo de atualização lê e grava no mesmo arquivo. Use "r+b" para preservar um arquivo binário existente enquanto altera seus registros. "w+b" apaga imediatamente o arquivo antigo, e modos de acréscimo forçam toda escrita a ocorrer no fim.

Torne válidas as mudanças de direção

Um fluxo de atualização tem duas regras de alternância:

As funções de posicionamento incluem fseek, fsetpos e rewind. Verifique as funções que informam um resultado antes de continuar. Uma mudança de direção sem a ação necessária causa comportamento indefinido; você não pode prever que ela apenas afetará o próximo registro.

Atualize um registro completo

Suponha que um arquivo sem cabeçalho contenha cinco registros de 24 bytes na mesma representação de struct record. Para alterar o índice 3:

1. Abra com "r+b" e verifique o ponteiro.
2. Posicione no byte 72 e verifique se houve sucesso.
3. Leia exatamente um registro completo.
4. Altere seu membro score para 99.
5. Volte à posição inicial do registro.
6. Grave exatamente um registro e verifique o resultado do fechamento.

As principais operações intermediárias são:

if (fread(&rec, sizeof rec, 1, fp) != 1) {
    /* Report the incomplete input, then clean up. */
    goto cleanup;
}
rec.score = 99;
if (fseek(fp, -(long)sizeof rec, SEEK_CUR) != 0) {
    /* Report the failed seek, then clean up. */
    goto cleanup;
}
if (fwrite(&rec, sizeof rec, 1, fp) != 1) {
    /* Report the failed write, then clean up. */
    goto cleanup;
}

A função que contém esse trecho fornece um rótulo cleanup que fecha seu fluxo e retorna falha nesses ramos. Após a leitura, a posição é 96. Voltar 24 bytes seleciona o registro original e permite a alternância de leitura para escrita. Uma substituição bem-sucedida deixa o arquivo com 120 bytes e cinco registros. Restaurar uma posição inicial salva é outra forma válida de fazer a atualização.

Decida quando regravar

Acrescentar um registro de 24 bytes aumenta esse arquivo para 144 bytes. Posicionar no início de um fluxo "ab" ou "a+b" não transforma sua próxima escrita em sobrescrita; a escrita ainda ocorre no fim atual.

Uma substituição no próprio local deve caber no espaço que substitui. Alterar "Bo,7" para "Bo,9" cabe. Gravar "Bo,12" sobre "Bo,7\n" consome a nova linha e une o texto seguinte ao registro. Para aumentar ou reduzir registros, grave um novo arquivo corrigido. O padrão C não tem função de fluxo que remova uma faixa de bytes do meio de um arquivo. Em vez disso, a exclusão pode copiar todos os registros mantidos ou marcar um registro de tamanho fixo como excluído.

Mantenha a substituição recuperável

Verifique remove e rename; ambas retornam 0 em caso de sucesso. A substituição ou não de um destino existente por rename é definida pela implementação. Linux e macOS permitem a substituição; a biblioteca C da Microsoft falha quando o destino existe.

Um plano portável de recuperação grava e fecha o novo arquivo, renomeia o original para um nome distinto de backup e renomeia o novo arquivo para o nome original. Se a instalação falhar, mantenha o backup disponível para restauração e informe onde ele está. Exclua o backup somente após a instalação ser bem-sucedida. Essa sequência permite recuperação; ela não é uma transação atômica portável nem uma garantia contra falhas de energia.

Um arquivo pode ser aberto com sucesso e ainda assim falhar durante a leitura, a escrita, o posicionamento ou o fechamento. Um programa robusto verifica o resultado da operação que realmente tentou executar. Ele distingue uma leitura concluída de uma entrada interrompida e dados malformados de uma falha no fluxo.

Conheça cada sinal de falha

rewind, clearerr e perror não retornam valor. Se for necessário verificar se a movimentação até o início teve sucesso, use fseek em vez de depender de um resultado de rewind.

Examine o fluxo após uma leitura parar

O fluxo mantém indicadores separados de fim de arquivo e erro. feof(fp) testa o primeiro; ferror(fp) testa o segundo. Cada uma retorna um valor diferente de zero se seu indicador estiver ativado.

while (fgets(line, sizeof line, fp) != NULL) {
    /* Process successful input. */
}
if (ferror(fp)) {
    fprintf(stderr, "Input could not be completed\n");
    /* Return failure after cleanup. */
}

O retorno de fgets sozinho não distingue os dois motivos de parada. Da mesma forma, fgetc retorna EOF e fread retorna uma contagem menor que a solicitada tanto no fim do arquivo quanto em uma falha de leitura. Não teste feof antes da leitura para prever se restam dados.

Os indicadores persistem. clearerr limpa ambos, assim como rewind. Uma chamada bem-sucedida a fseek ou fsetpos limpa o indicador de fim de arquivo, mas não um erro existente. Limpar um indicador reconhece sua ocorrência; isso não reconecta uma unidade removida nem repara um arquivo danificado. Tente novamente somente quando a causa tiver sido resolvida.

Separe dados inválidos de falhas de acesso

Se fscanf(fp, "%d", &value) retornar 0 em "abc", a conversão falhou antes de qualquer atribuição. Não é necessário que tenha ocorrido fim de arquivo ou erro de leitura. Informe que o campo é inválido, de preferência com o número da linha. Uma mensagem sobre o disco descreveria o problema errado.

Se um cabeçalho obrigatório for lido como um elemento e fread retornar 0, o cabeçalho está incompleto. Não examine esse objeto parcialmente preenchido. Se ferror estiver ativado, informe um erro de entrada; se o arquivo tiver terminado, informe dados truncados. Um arquivo vazio e um cabeçalho parcial podem produzir a mesma contagem de elementos, portanto o formato esperado estabelece a exigência de que o cabeçalho exista.

Detecte falhas tardias de saída

Um disco pode ficar cheio depois que o programa abriu sua saída. Escritas armazenadas em buffer podem parecer bem-sucedidas até que fflush ou fclose realmente transfira os bytes pendentes. Verifique o fechamento final e permita que ele transforme um trabalho que seria bem-sucedido em falha. Não feche o mesmo fluxo novamente depois disso.

Em um terminal, Ctrl+D no início de uma linha no Linux ou no macOS, ou Ctrl+Z seguido de Enter no Windows, geralmente sinaliza o fim da entrada. clearerr(stdin) limpa o indicador resultante se o programa precisar de outra tentativa. A ação no terminal e um erro de leitura continuam sendo causas diferentes.

Um valor de retorno informa que uma operação falhou. Um código de erro pode ajudar a explicar por quê. Use errno apenas no contexto do comportamento documentado da operação e preserve-o antes que chamadas de biblioteca não relacionadas possam alterá-lo.

Deixe a operação estabelecer a falha

errno é uma expressão int modificável de <errno.h>, com duração de armazenamento local à thread no C11. Ele começa em zero. Chamadas de biblioteca não o redefinem como zero, e uma chamada bem-sucedida pode deixar ou definir um valor diferente de zero. Portanto, testar errno após uma chamada bem-sucedida a fopen não informa que a abertura falhou.

Em sistemas POSIX, uma chamada malsucedida a fopen define um código de erro. A biblioteca C da Microsoft também fornece códigos de erro de arquivo. O padrão C não exige que fopen defina errno. Uma forma portável de informar o erro pode limpá-lo antes da abertura e usar uma mensagem geral se nenhum código for fornecido:

errno = 0;
FILE *fp = fopen(name, "r");
if (fp == NULL) {
    int saved = errno;
    if (saved != 0)
        fprintf(stderr, "Cannot open %s: %s\n",
                name, strerror(saved));
    else
        fprintf(stderr, "Cannot open %s\n", name);
    return EXIT_FAILURE;
}

Esse trecho também precisa de <stdio.h>, <stdlib.h> e <string.h>. Salvar o código imediatamente impede que chamadas posteriores para informar o erro ou liberar recursos substituam o motivo original. Um código salvo é útil mesmo que a mensagem final seja exibida muito mais tarde.

Escolha uma função de mensagem

perror(label) escreve em stderr o rótulo, dois-pontos e um espaço, a mensagem de erro atual e uma nova linha. Uma mensagem típica de arquivo ausente é "missing.txt: No such file or directory"; a redação exata depende do sistema.

strerror(code) retorna a mensagem da biblioteca para um código fornecido, portanto serve para um diagnóstico personalizado que indique o programa, a operação e o arquivo. Não modifique a cadeia retornada. Use strerror(saved) após a liberação de recursos em vez de consultar o novo valor de errno.

C define EDOM, ERANGE e EILSEQ. Códigos de arquivo comuns, como ENOENT, EACCES, EEXIST e ENOSPC, são fornecidos pelo POSIX e por bibliotecas C amplamente disponíveis. Ajuste seu código à interface e à plataforma de destino. Não suponha que valores numéricos de códigos ou o texto exato das mensagens em inglês sejam universais.

Trate um valor de retorno ambíguo

Para algumas funções, o resultado sozinho não consegue distinguir sucesso de um erro de faixa. strtol pode retornar LONG_MAX como número válido ou como resultado de estouro. Limpe errno antes da conversão e depois examine o código de faixa documentado:

errno = 0;
char *end;
long value = strtol(text, &end, 10);
if (end == text) {
    /* No digits were converted. */
} else if (errno == ERANGE) {
    /* The value is outside the long range. */
} else {
    /* Validate trailing characters and the target range. */
}

Um diagnóstico útil dá ao usuário informações para agir. Informe o arquivo e a ação tentada; preserve o motivo indicado pelo sistema quando estiver disponível. Envie-o para stderr, deixando stdout disponível para dados válidos de resultado.

O tratamento de erros só está completo quando os recursos são liberados e o programa informa o resultado real. Planeje a responsabilidade pela liberação ao abrir um fluxo e faça com que todos os caminhos posteriores respeitem esse plano.

Feche cada fluxo aberto uma vez

Se a abertura da entrada falhar, não há fluxo para fechar. Se a abertura da saída falhar após a entrada ter sido aberta com sucesso, feche a entrada. Se a cópia falhar depois que ambos forem abertos, feche os dois, verifique o fechamento da saída e mantenha um código de falha. Fechar um ponteiro duas vezes não é uma proteção adicional; isso usa um fluxo já encerrado.

Código com retorno antecipado geralmente fecha recursos na ordem inversa. Um rótulo compartilhado de liberação de recursos é útil quando vários caminhos de falha precisam do mesmo trabalho. Inicialize ponteiros com NULL, mantenha um código de falha por padrão e defina sucesso somente após o término da fase de processamento.

O programa completo a seguir copia arquivos distintos de entrada e saída em modo binário. Ele usa mensagens genéricas porque o padrão C não exige que toda falha de stdio forneça errno.

#include <stdio.h>
#include <stdlib.h>

int main(int argc, char *argv[])
{
    FILE *in = NULL, *out = NULL;
    int status = EXIT_FAILURE;
    int output_acquired = 0;
    unsigned char buf[512];
    size_t n;

    if (argc != 3) {
        fprintf(stderr, "Usage: %s input output\n", argv[0]);
        return EXIT_FAILURE;
    }
    in = fopen(argv[1], "rb");
    if (in == NULL) {
        fprintf(stderr, "Cannot open input: %s\n", argv[1]);
        goto cleanup;
    }
    out = fopen(argv[2], "wb");
    if (out == NULL) {
        fprintf(stderr, "Cannot open output: %s\n", argv[2]);
        goto cleanup;
    }
    output_acquired = 1;
    while ((n = fread(buf, 1, sizeof buf, in)) > 0) {
        if (fwrite(buf, 1, n, out) != n) {
            fprintf(stderr, "Write failed: %s\n", argv[2]);
            goto cleanup;
        }
    }
    if (ferror(in)) {
        fprintf(stderr, "Read failed: %s\n", argv[1]);
        goto cleanup;
    }
    status = EXIT_SUCCESS;

cleanup:
    if (out != NULL && fclose(out) == EOF) {
        fprintf(stderr, "Close failed: %s\n", argv[2]);
        status = EXIT_FAILURE;
    }
    if (in != NULL && fclose(in) == EOF) {
        fprintf(stderr, "Close failed: %s\n", argv[1]);
        status = EXIT_FAILURE;
    }
    if (output_acquired && status != EXIT_SUCCESS) {
        if (remove(argv[2]) != 0)
            fprintf(stderr, "Cannot remove incomplete output: %s\n",
                    argv[2]);
    }
    return status;
}

O laço de entrada processa apenas os bytes efetivamente lidos. Uma escrita incompleta salta para a liberação de recursos; um erro de entrada é verificado após o laço. O fechamento da saída ainda pode transformar o sucesso em falha. A remoção é tentada somente quando esta execução abriu a saída com sucesso, portanto uma falha de abertura não provoca a exclusão de um arquivo não relacionado. A exigência de arquivos distintos é importante: "wb" apagaria a entrada se os dois nomes identificassem o mesmo arquivo.

Preserve dados existentes importantes

Abrir diretamente a saída não permite desfazer o truncamento. Para substituir dados valiosos, grave primeiro sob um nome temporário separado. Verifique cada escrita e o fechamento final antes de renomear. Mantenha o original sob um nome de backup até que o novo arquivo esteja instalado; verifique cada chamada a rename e remove. Se a instalação falhar, informe a localização do arquivo recuperável em vez de excluí-lo.

Uma função auxiliar deve fechar o que abriu e retornar um resultado de sucesso ou falha à função chamadora. A função chamadora pode decidir se tentará novamente ou encerrará o programa. Retornar EXIT_FAILURE após qualquer etapa incompleta permite que um script pare antes de uma ação dependente, como excluir o original após um backup.