SCANF(3)

NOME
scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf - conversão de formato de entrada

SINÓPSE
#include <stdio.h>
int scanf( const char *format, ...);
int fscanf( FILE *stream, const char *format, ...);
int sscanf( const char *str, const char *format, ...);

#include <stdarg.h>
int vscanf( const char *format, va_list ap);
int vsscanf( const char *str, const char *format, va_list ap);
int vfscanf( FILE *stream, const char *format, va_list ap);

DESCRIÇÃO
A família de funções scanf examina entrada de acordo com um format como descrito abaixo. Este formato pode conter especificadores de conversão; os resultados dessas conversões, se houverem, são armazenados por meio dos argumentos ponteiros. A função scanf lê entradas a partir do fluxo de entrada padrão stdin, fscanf lê entradas a partir do ponteiro de fluxo stream, e sscanf lê suas entradas a partir da seqüencia de caracteres indicada por str.

A função vfscanf é análoga a vfprintf(3) e lê entradas a partir do ponteiro de fluxo stream usando uma lista variável de argumentos de ponteiros (veja stdarg(3). A função vscanf examina a lista variável de argumentos a partir da entrada padrão e a função vsscanf a examina a partir de uma seqüencia; estas são análogas às funções vprintf e vsprintf respectivamente.

Cada sucessivo argumento pointeiro deve corresponder apropriadamente a cada sucessivo especificador de conversão (mas veja 'supressão' abaixo). Todas as conversões são iniciadas pelo caracter % (sinal de percentagem). A seqüencia format também pode conter outros caracteres. Espaços em branco (tais como espaços, tabs, ou enter) na seqüencia format correspondem a alguma quantidade de espaços em branco, incluindo nenhum, na entrada. Tudo mais corresponde apenas a si próprio. O exame para quando a entrada não combina com o formato de caracter. O exame também para quando a conversão de uma entrada não pode ser feita (veja abaixo).

CONVERSÕES
Seguindo o caracter % iniciando a conversão deve haver um número de caracteres sinalizadores (flag) como segue:

*   Suprime a tarefa. A conversão que segue ocorre como usual, mas nenhum ponteiro é usado; o resultado da conversão é simplesmente descartado.

a   Indica que a conversão será s, o espaço em memória necessário para a seqüencia será alocado e o seu ponteiro será destinado para a variável indicadora char , que não tem que ser inicializada antes. Este sinalizador não existe em ANSI C.

h   Indica que a conversão será uma entre dioux ou n e o próximo ponteiro é um ponteiro para um short int (ao invés de um int).

l   Indica tanto que a conversão será uma entre dioux ou n e o próximo ponteiro é um ponteiro para um long int (ao invés de um int), como a conversão será uma entre efg e o próximo ponteiro será um ponteiro para um double (ao invés de um float). Especificar dois sinalizadores l é equivalente ao sinalizador L.

L   Indica tanto que a conversão será efg e o próximo ponteiro é um ponteiro para um long double como a conversão será dioux e o próximo ponteiro será um ponteiro para um long long. (Note que long long não é um tipo ANSI C. Qualquer programa que use este tipo não será portável para todas arquiteturas).

q   equivalente a L. Este sinalizador não existe em ANSI C.

Em adicão a estes sinalizadores, pode existir um opcional tamanho máximo de campo, expresso como um decimal inteiro, entre o % e a conversão. Se não for dado o tamanho, o padrão `infinito' é usado (com uma excessão, abaixo); de outro modo a maioria destes caracteres são examinados no processo de conversão. Antes da conversão iniciar, a maioria das conversões salta um espaço em branco; este espaço em branco não é contado com o tamanho do campo.

As seguintes conversões estão disponíveis:

%   Corresponde ao literal `%'. Isto é, `%%' no formato de seqüencia corresponde a entrada simples do caracter `%'. Nenhuma conversão é feita, e não ocorre atribuição.

d   Corresponde a um decimal inteiro opcionalmente sinalizado; o próximo ponteiro deve ser um ponteiro para um int.

D   Equivalente a ld; existe apenas para compatibilidade com versões passadas. (Nota: consequentemente apenas em libc4. Em libc5 e glibc o %D é silenciosamente ignorado, fazendo com que programas antigos falhem misteriosamente.)

i   Corresponde a um inteiro opcionalmente sinalizado; o próximo ponteiro deve ser um ponteiro para um int. O inteiro é lido na base 16 se começar com `0x' ou `0X', na base 8 se começar com `0', e na base 10 nos demais casos. Apenas caracteres que correspondam a base são usados.

o   Corresponde a um octal inteiro sem sinal; o próximo ponteiro deve ser um ponteiro para um unsigned int.

u   Corresponde a um decimal inteiro sem sinal; o próximo ponteiro deve ser um ponteiro para um unsigned int.

x   Corresponde a um haxadecimal inteiro sem sinal; o próximo ponteiro deve ser um ponteiro para um inteiro unsigned int.

X   Equivalente a x

f   Corresponde a um número de ponto-flutuante opcionalmente sinalizado; o próximo ponteiro deve ser um ponteiro para um float(flutuante).

e   Equivalente a f.

g   Equivalente a f.

E   Equivalent a f

s   Corresponde a uma seqüência de caracteres diferentes de espaços em branco; o próximo ponteiro deve ser um ponteiro para um char, e a matriz deve ser grande o suficiente para aceitar toda a seguência e o caractere final NULO. A seqüencia de entrada para no espaço em branco ou no tamanho máximo do campo, o que ocorrer primeiro dos dois.

c   Corresponde a um seqüência de caracteres com tamanho width contado (padrão 1); o próximo ponteiro deverá ser um ponteiro para um char, e deve haver suficiente espaço para todos os caracteres (não é acrescentado o finalizador NULO ). O usual pulo do espaço em branco inicial é suprimido. Para saltar o espacó em branco primeiro, use um espaço explicito no formato.

[   Corresponde a uma seqüência não-vazia de caracteres de um conjunto de caracteres aceitos; o próximo ponteiro deve sere um ponteiro para um char, e deve existir espaço suficiente para todos os caracteres da seqüencia, mais um caractere finalizador NULO. O usual salto do espaço em branco inicial é suprimido. A seqüencia deve ser formada de caracteres de (ou fora de) um conjunto particular; o conjunto é definido pelos caracteres entre abre colchetes [ e fecha colchetes ]. O conjunto exclui estes caracteres se o primeiro caracter depois do abre colchetes for um cincunflexo ^. Para incluir um fecha colchete no conjunto, faça dele o primeiro caracter depois do abre colchete ou do circunflexo; qualquer outra posição encerrará o conjunto. O caracter hífem - também é especial; quando colocado entre dois outros caracteres, ele adiciona todos os caracteres entre os dois no conjunto. Para incluir um hífem, faça dele o último caracter antes do fecha colchete final. Por exemplo, `[^]0-9-]' significa o conjunto de `tudo exceto fecha colchete, zero até nove, e hífem'. A seqüencia termina com a aparição de um caracter que não está (ou, com o circumflexo, que está) no conjunto ou quando exceder o tamanho do campo.

p   Corresponde a um valor de ponteiro (como impresso por `%p' em printf(3); o próximo ponteiro deve ser um ponteiro para void.

n   Nada é esperado; ao invés, o número de caracteres consumidos até então pela entrada é armazenado através do próximo ponteiro, que deve ser um ponteiro para um int. Esta não é uma conversão, embora possa ser suprimida com o sinalizador *. O padrão C diz que: 'A execução de uma diretiva %n não incrementa a contador de atribuições retornado ao completar a execução' mas o Corrigendum parece contradizer isto. Provavelmente é prudente não fazer nenhuma inferência sobre o efeito das conversões %n no valor retornado.

VALORES RETORNADOS
Estas funções retornam o número de itens de entrada designados, que pode ser menor que o passado para elas, ou mesmo zero, em caso de falha na correspondência. Zero indica que, enquanto houve entrada disponível, nenhuma conversão foi designada; tipicamente isto é devido a um caracter de entrada inválido, como um caracter alfabético para uma conversão `%d'. O valor EOF é retornado se ocorrer uma falha de entrada antes de alguma conversão como quando ocorre final de arquivo. Se um erro ou final de arquivo ocorrer depois que da conversão ter iniciado, o número de conversões que forem completadas com sucesso é retornado.

VEJA TAMBÉM
strtol(3), strtoul(3), strtod(3), getc(3), printf(3).

DE ACORDO COM
As funções fscanf, scanf, e sscanf estão de acordo com ANSI X3.159-1989 ('ANSI C').

O sinalizador q é a notação BSD 4.4 para long long, enquanto ll ou o uso de L em conversões de inteiros é a notação GNU.

A versão Linux destas funções é baseada na biblioteca GNU libio. Dê uma olhada na documentação info da GNU libc (glibc-1.08) para uma descrição mais concisa.

PROBLEMAS
Todas as funções são completamente de acordo com ANSI X3.159-1989 , mas provê os sinalizadores adicionais q e a bem como um comportamento adicional dos sinalizadores L e l. O último pode ser considerado como um problema, como ele muda o comportamento dos sinalizadores definidos em ANSI X3.159-1989.

Algumas combinações de sinalizadores definidos por ANSI C não estão fazendo sentido em ANSI C (por exemplo, %Ld). Enquanto eles podem ter um comportamento bem definido no Linux, isto pode não acontecer em outras arquiteturas. Portanto usualmente é melhor usar sinalizadores que não são definidos pelo ANSI C em geral, isto é. usar q ao invés de L em combinação com conversões diouxX ou ll.

O uso de q não é o mesmo que em BSD 4.4, como pode ser usado em conversões de flutuantes de forma equivalente a L.

TRADUZIDO POR LDP-BR em 30/05/2001.

  Tradução:
Orlando Vieira de Castro <orlandovieira@yahoo.com>

  Revisão.:
Silvio Gissi Fonseca <gissi@mackenzie.com.br>