bg_leia_linha
Gerada por tools/gerar_documentacao.py. Definição: src/biblioteca/consola.c:23.
Lê uma linha inteira de um FILE para um buffer limitado, sem perder a sincronização do fluxo em linha longa.
Tipo: função C · Visibilidade: pública · Arquivo: src/biblioteca/consola.c.
Assinatura e expansão
bool bg_leia_linha(FILE *entrada, char *destino, size_t capacidade)
Parâmetros formais: FILE *entrada, char *destino, size_t capacidade.
Declarações públicas localizadas:
Lê uma linha de
entradaemdestino, sem ultrapassarcapacidade. Remove LF, CRLF ou CR final. Linha vazia é sucesso; EOF sem bytes, erro de leitura, NUL embutido ou linha longa são falhas. Em linha longa, o restante é consumido para manter o fluxo sincronizado. Em falha, destino utilizável fica vazio. A capacidade inclui o byte NUL. @return true se a linha foi lida inteira; false em argumento inválido, EOF, erro de E/S, NUL embutido ou truncamento.
Como funciona
Consome bytes com fgetc até LF, CR, CRLF ou EOF. Remove o terminador, rejeita NUL embutido e continua consumindo a linha quando ela não cabe. Linha vazia terminada por newline é sucesso; EOF sem nenhum byte é falha. Verifica ferror e o resultado de ungetc.
Retorno: true somente quando a linha inteira coube e foi lida sem erro. Em falha, um destino válido fica vazio; capacidade zero não autoriza escrita.
- capacidade inclui o NUL: capacidade 1 só comporta linha vazia.
- Não interpreta UTF-8; limites são bytes.
- Uma última linha sem newline antes de EOF é aceita se couber.
Exemplo de uso
TEXTO_FIXO(linha, 128);
SE bg_leia_linha(stdin, linha, TAMANHO_DE(linha)) ENTAO
ESCREVAL(linha);
FIM_SE
Comentário do fonte
chamada _Noreturn: fim inalcançável (MSVC C4702)
Implementação completa · 55 linhas
{
size_t usados = 0;
bool leu_algum = false;
bool truncou = false;
bool invalida = false;
bool falha_io = false;
if (destino != NULL && capacidade > 0) {
destino[0] = '\0';
}
if (entrada == NULL || destino == NULL || capacidade == 0) {
return false;
}
for (;;) {
int c = fgetc(entrada);
if (c == EOF) {
falha_io = ferror(entrada) != 0;
break;
}
leu_algum = true;
if (c == '\n') {
break;
}
if (c == '\r') {
int seguinte = fgetc(entrada);
if (seguinte != '\n' && seguinte != EOF
&& ungetc(seguinte, entrada) == EOF) {
falha_io = true;
}
if (seguinte == EOF && ferror(entrada)) {
falha_io = true;
}
break;
}
if (c == '\0') {
invalida = true;
continue;
}
if (usados < capacidade - 1) {
destino[usados++] = (char) c;
} else {
truncou = true;
}
}
if (falha_io || !leu_algum || truncou || invalida) {
destino[0] = '\0';
return false;
}
destino[usados] = '\0';
return true;
}
Como este símbolo aparece nos testes
17 ocorrência(s) em 2 arquivo(s) de teste. Os links apontam para linhas exatas; os trechos mostram o contexto local. Uma menção não prova que todos os ramos foi executado.
tests/portabilidade/fronteira.c
Contexto: fronteira.c. Linhas: 294, 295, 296. Tipo de evidência: código; via bg_leia_linha.
Linhas 292–298 · abrir contexto
EXIGE(bg_escreva_linha(stdout, NULL) == false);
EXIGE(bg_escreva_texto(stdout, "fronteira: ok (") == true);
EXIGE(bg_leia_linha(NULL, dst, 4) == false);
EXIGE(bg_leia_linha(stdin, NULL, 4) == false);
EXIGE(bg_leia_linha(stdin, dst, 0) == false);
EXIGE(bg_leia_inteiro(NULL) == false);
EXIGE(bg_leia_real(NULL) == false);
tests/test_biblioteca.c
Contexto: testa_console. Linhas: 58, 60, 62, 64, 66, 68, 70, 72, 76, 78, 80, 82, 94, 96. Tipo de evidência: código; via bg_leia_linha.
Linhas 56–84 · abrir contexto
}
VERIFICA(bg_leia_linha(entrada, buffer, sizeof buffer));
VERIFICA(strcmp(buffer, "abc") == 0);
VERIFICA(bg_leia_linha(entrada, buffer, sizeof buffer));
VERIFICA(strcmp(buffer, "1234567") == 0);
VERIFICA(bg_leia_linha(entrada, buffer, 5) == false);
VERIFICA(buffer[0] == '\0');
VERIFICA(bg_leia_linha(entrada, buffer, sizeof buffer));
VERIFICA(buffer[0] == '\0'); /* linha vazia é sucesso */
VERIFICA(bg_leia_linha(entrada, buffer, sizeof buffer));
VERIFICA(strcmp(buffer, "crlf") == 0);
VERIFICA(bg_leia_linha(entrada, buffer, sizeof buffer));
VERIFICA(strcmp(buffer, "final") == 0); /* última linha sem LF */
VERIFICA(!bg_leia_linha(entrada, buffer, sizeof buffer));
VERIFICA(buffer[0] == '\0');
VERIFICA(!bg_leia_linha(NULL, buffer, sizeof buffer));
VERIFICA(buffer[0] == '\0');
(void) fclose(entrada);
VERIFICA(!bg_leia_linha(limite, uma_posicao, 0));
VERIFICA(uma_posicao[0] == 'x'); /* capacidade zero não autoriza escrita */
VERIFICA(!bg_leia_linha(limite, uma_posicao, sizeof uma_posicao));
VERIFICA(uma_posicao[0] == '\0'); /* nenhum byte cabe além do NUL */
VERIFICA(bg_leia_linha(limite, uma_posicao, sizeof uma_posicao));
VERIFICA(uma_posicao[0] == '\0'); /* linha vazia cabe até em capacidade 1 */
VERIFICA(!bg_leia_linha(limite, NULL, 1));
(void) fclose(limite);
Linhas 92–98 · abrir contexto
(void) fputs("ok\n", entrada);
rewind(entrada);
VERIFICA(!bg_leia_linha(entrada, buffer, sizeof buffer));
VERIFICA(buffer[0] == '\0');
VERIFICA(bg_leia_linha(entrada, buffer, sizeof buffer));
VERIFICA(strcmp(buffer, "ok") == 0);
(void) fclose(entrada);
Modos de integração/falha fatal
--stdin— invocação L42:if printf '42\nlinha de texto\n-7\n3.5\n' | "$TESTE" --stdin > "$TMP/out" 2> "$TMP/err" \--stdin-invalido— invocação L50:if printf 'abc\n1e9999\n' | "$TESTE" --stdin-invalido > "$TMP/out" 2> "$TMP/err" \--stdin-texto-longo— invocação L58:if printf 'linha-longa\nok\n' | "$TESTE" --stdin-texto-longo > "$TMP/out" 2> "$TMP/err" \
Evidência indireta
Estes símbolos chamam/encaminham para este nome. As referências deles ajudam a rastrear o caminho, mas não substituem um teste específico deste símbolo.
bg_leia_texto→ tests/test_biblioteca.cbg_leia_inteiro_de→ tests/test_biblioteca.cbg_leia_real_de→ tests/test_biblioteca.c
Compiladores, padrão C e sistema operacional
Nenhum ramo condicional externo foi detectado para este símbolo. A implementação é compartilhada no fonte; isso não certifica compiladores ou sistemas não executados.
- LF, CRLF e CR são tratados explicitamente, não se presume mode-binário do stdin.
- O comportamento de streams e ferror é fornecido pela libc do sistema.
A matriz histórica distingue executado, compilado, avaliado e não testado. Consulte a matriz, os compiladores e os logs atuais dos workflows antes de chamar um alvo de suportado.
Checklist de integração
- Compile com C11: o cabeçalho seleciona formatos e divisões com
_Generic, e C99/C89 são recusados com mensagem explícita. - Declare pelo cabeçalho (
include/basicgol/consola.h) e liguebuild/libbasicgol.a; não copie o corpo desrc/biblioteca/consola.cpara o seu arquivo. - Rode
make test(oumake test-bibliotecapara a biblioteca) antes de integrar.
make
cc -std=c11 -Wall -Wextra -Wformat=2 -I include programa.c \
build/libbasicgol.a -lm -o programa
Perguntas frequentes
Perguntas reunidas a partir da definição, do contrato editorial e dos testes de bg_leia_linha. As respostas repetem apenas o que o repositório mostra; quando não há evidência, isso é dito.
Em uma frase, o que bg_leia_linha faz?
Lê uma linha inteira de um FILE para um buffer limitado, sem perder a sincronização do fluxo em linha longa.
Qual é a assinatura e o tipo de retorno de bg_leia_linha?
Assinatura extraída de src/biblioteca/consola.c; visibilidade pública.
Retorno: true somente quando a linha inteira coube e foi lida sem erro. Em falha, um destino válido fica vazio; capacidade zero não autoriza escrita.
bool bg_leia_linha(FILE *entrada, char *destino, size_t capacidade)
Como usar bg_leia_linha em um programa?
Exemplo editorial mantido em tools/documentacao/contratos.json e conferido contra a assinatura real:
TEXTO_FIXO(linha, 128);
SE bg_leia_linha(stdin, linha, TAMANHO_DE(linha)) ENTAO
ESCREVAL(linha);
FIM_SE
Onde bg_leia_linha é exercitado nos testes?
Há 17 ocorrência(s) em 2 arquivo(s): tests/portabilidade/fronteira.c, tests/test_biblioteca.c. Os links da seção de evidência apontam para a linha exata; uma menção não prova que todos os ramos foram executados.
bg_leia_linha depende de compilador, padrão C ou sistema operacional?
bg_leia_linha exige C11 como o restante da linguagem; largura de tipo, libc e CRT continuam sendo os do alvo.
Ressalvas registradas: LF, CRLF e CR são tratados explicitamente, não se presume mode-binário do stdin. O comportamento de streams e ferror é fornecido pela libc do sistema.
Quais armadilhas preciso evitar ao usar bg_leia_linha?
O contrato editorial registra: “capacidade inclui o NUL: capacidade 1 só comporta linha vazia.” “Não interpreta UTF-8; limites são bytes.” “Uma última linha sem newline antes de EOF é aceita se couber.”