NOMBRE¶
scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf - conversión de la entrada
con formato
SINOPSIS¶
#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);
DESCRIPCIÓN¶
La familia
scanf de funciones escudriña la entrada según un
formato como se describe más adelante. Este formato puede contener
especificadores de conversión; los resultados de tales
conversiones, si las hay, se guardan donde apunten los argumentos
punteros. La función
scanf lee la entrada del flujo de
entrada estándar
stdin,
fscanf lee su entrada del puntero a
FILE
flujo, y
sscanf lee su entrada de la cadena de caracteres a
la que apunte
str.
La función
vfscanf es análoga a
vfprintf(3) y lee la
entrada del puntero a FILE
flujo utilizando una lista variable de
argumentos de punteros (vea
stdarg(3)). La función
vscanf
rastrea una lista variable de argumentos de la entrada estándar y la
función
vsscanf la analiza de una cadena de caracteres; estas
funciones son análogas a
vprintf y
vsprintf
respectivamente.
Cada argumento
puntero sucesivo debe corresponder correctamente con cada
especificador de conversión sucesivo (pero vea más adelante lo
referente a `supresión'). Todas las conversiones empiezan con el
carácter
% (signo de porcentaje). La cadena de caracteres
formato puede también contener otros caracteres. El espacio en
blanco (como espacios, tabuladores, o saltos de línea) en la cadena de
formato concuerda con cualquier cantidad de espacio en blanco,
incluyendo ninguna, en la entrada. Cualquier otra cosa concuerda solamente
consigo misma. El análisis acaba cuando un carácter de la entrada no
concuerda con un carácter del formato. También cuando una
conversión no puede realizarse (vea más adelante).
CONVERSIONES¶
Después del carácter
% que marca el comienzo de una
conversión puede haber una serie de caracteres de
opción,
como sigue:
- *
- Suprime la asignación. La conversión que sigue
ocurre como si nada, pero no se usa ningún puntero; el resultado de
la conversión simplemente se descarta.
- a
- (glibc) Indica que la conversión será s,
el espacio de memoria necesario para la cadena se obtendrá mediante
malloc() y el puntero a ella se asignará a la variable puntero
char, que no tiene que haber sido inicializada anteriormente. Esta
opción no existe en C ANSI (C89) y tiene un significado
diferente en C99.
- a
- (C99) Equivalente a f.
- h
- Indica que la conversión será una de dioux
o n y que el puntero siguiente lo es a un short int (en vez
de a un int).
- l
- Indica bien que la conversión será una de
dioux o n y el puntero siguiente lo es a un long int
(en vez de a un int), o bien que la conversión será una
de efg y el puntero siguiente lo es a un double (en vez de a
un float). Especificar dos opciones l equivale a la
opción L.
- L
- Indica que la conversión será o bien efg y
el siguiente puntero lo es a un long double o bien que la
conversión será dioux y el siguiente puntero lo será
a un long long. (Observe que long long no es un tipo de C
ANSI. Un programa que utilice esto no será transportable a todas
las arquitecturas).
- q
- equivalente a L. Esta opción no existe en C
ANSI.
Además de estas opciones, puede haber una anchura máxima de campo
opcional, expresado como un entero en base diez, entre el signo
% y la
conversión. Si no se da la anchura, se supone `infinita' (con una
excepción, vea más abajo); si se da, como mucho se miran los
caracteres especificados en ella cuando haya que procesar la conversión.
Antes de que ésta comience, la mayoría descartan el espacio en
blanco; este espacio no cuenta para la anchura de campo.
Están disponibles las siguientes conversiones:
- %
- Concuerda con un '%' literal. Esto es, `%%' en el formato
concuerda con un solo carácter '%' en la entrada. No se hace ninguna
conversión, y no hay ninguna asignación.
- d
- Concuerda con un entero en base diez con signo opcional; el
siguiente puntero debe serlo a int.
- D
- Equivalente a ld; esto existe solamente por
compatibilidad con una forma antigua. (Nota: esto ocurre sólo en
libc4. En libc5 y glibc %D se ignora silenciosamente, provocando el fallo
mistorioso de programas antiguos.)
- i
- Concuerda con un entero con signo opcional; el siguiente
puntero debe serlo a int. El entero se lee en base 16 si empieza
por `0x' ó `0X'; en base 8 si empieza por `0', y en base 10 si
empieza por otro dígito. Sólo se usan caracteres que
correspondan a la base.
- o
- Concuerda con un entero octal sin signo; el siguiente
puntero debe serlo a unsigned int.
- u
- Concuerda con un entero en base diez sin signo; el
siguiente puntero debe serlo a unsigned int.
- x .
- Concuerda con un entero hexadecimal sin signo; el siguiente
puntero debe serlo a unsigned int.
- X
- Equivalente a x
- f .
- Concuerda con un número en coma flotante con signo
opcional; el siguiente puntero debe serlo a float.
- e
- Equivalente a f.
- g
- Equivalente a f.
- E
- Equivalente a f
- s
- Concuerda con una secuencia de caracteres distintos de
blancos; el siguiente puntero debe serlo a char, y el vector debe
ser lo suficientemente grande como para aceptar toda la secuencia y el
carácter 0 ó NUL final. El análisis de la cadena de
entrada acaba en el siguiente espacio blanco o cuando se llega a la
anchura de campo máxima, lo que ocurra antes.
- c
- Concuerda con una secuencia de anchura caracteres (1
por omisión); el siguiente puntero debe serlo a char, y debe
haber suficiente espacio para todos los caracteres (no se añade el
carácter NUL terminador). Se suprime el descarte de los
blancos iniciales. Para saltar un espacio en blanco inicial, emplee un
espacio explícito en el formato.
- [
- Concuerda con una secuencia no vacía de caracteres del
conjunto especificado de caracteres aceptados; el siguiente puntero debe
serlo a char, y debe haber bastante sitio para todos los caracteres
en la cadena, más un NUL terminal. Se suprime el descarte
usual de los espacios en blanco iniciales. La cadena se forma con
caracteres de (o no de) un conjunto particular; el conjunto se define por
los caracteres entre el corchete abierto [ y un carácter de
corchete de cierre ]. El conjunto excluye esos caracteres si
el primero después del corchete abierto es un acento circunflejo
^. Para incluir un corchete de cierre en el conjunto, póngalo
el primero tras el corchete abierto o el circunflejo; en cualquiera otra
posición indicará que termina el conjunto. El carácter
guión - es también especial; cuando se pone entre dos
otros caracteres, añade todos los de enmedio al conjunto. Para
incluir un guión, póngalo como el último carácter
antes del corchete de cierre final. Por ejemplo, `[^]0-9-]' significa el
conjunto de `todos los caracteres excepto el corchete de cierre, los
dígitos del cero al nueve, y el guión'. La cadena acaba con la
aparición de un carácter que no es (o, con un circunflejo, que
sí es) del conjunto, o cuando se llega a la anchura opcional
especificada.
- p
- Concuerda con un valor de tipo puntero (como se imprima por
`%p' en printf(3)); el siguiente puntero debe serlo a
void.
- n
- No se espera concordar con nada; en su lugar, se guarda el
número de caracteres consumidos o leídos hasta ahora de la
entrada en donde apunte el siguiente puntero, que debe serlo a int.
Esto no es una conversión, aunque pueda suprimirse con la
opción *. El estándar de C dice: `La ejecución de
una directriz %n no incrementa el número de asignaciones devuelto al
final de la ejecución', pero el Añadido de Correcciones parece
contradecir esto. Probablemente es lo mejor no hacer ninguna
suposición sobre el efecto de las conversiones %n en el valor de
retorno de la función.
VALOR DEVUELTO¶
Estas funciones devuelven el número de elementos de la entrada asignados,
que pueden ser menores que los formatos suministrados para conversión, o
incluso cero, en el caso de un fallo de concordancia. Cero indica que,
mientras había caracteres disponibles en la entrada, no ocurrió
ninguna asignación; normalmente esto es debido a un carácter de
entrada inválido, como un carácter alfabético para una
conversión `%d'. Se devuelve el valor
EOF si ha habido un fallo de
entrada antes de ninguna conversión, como cuando se llega al final de la
entrada. Si ocurre un error de lectura o se llega al final de la entrada
después de que se haya hecho alguna conversión al menos, se devuelve
el número de conversiones completadas hasta ese punto con éxito.
VÉASE TAMBIÉN¶
strtol(3),
strtoul(3),
strtod(3),
getc(3),
printf(3)
Las funciones
fscanf,
scanf, y
sscanf son conformes al
estándar ANSI X3.159-1989 (``C ANSI'').
La opción
q es la notación de
BSD 4.4 para el tipo
long long, mientras que
ll o el empleo de
L en
conversiones de enteros, es la notación de GNU.
La versión de Linux de estas funciones se basa en la biblioteca
libio de
GNU. Eche un vistazo a la documentación en formato
info de
GNU libc (glibc-1.08) para una descripción
más concisa.
FALLOS¶
Todas las funciones son conformes completamente con el estándar ANSI
X3.159-1989, pero proporcionan las opciones adicionales
q y
a
así como un comportamiento adicional de las opciones
L y
l.
Lo último puede ser considerado como un fallo, puesto que cambia el
comportamiento de las opciones definidas en el estándar ANSI X3.159-1989.
Algunas combinaciones de opciones definidas por C
ANSI no tienen sentido
en
C ANSI (p.ej.,
%Ld). Aunque pueden tener un comportamiento
bien definido en Linux, esto no tiene por qué ser así en otras
arquitecturas. Por lo tanto es normalmente mejor usar opciones que no son
definidas por C
ANSI en absoluto, i.e., usar
q en vez de
L en combinación con conversiones
diouxX o
ll.
El empleo de
q no es el mismo que en
BSD 4.4, puesto que puede
utilizarse en conversiones de coma flotante de forma equivalente a
L.