SCANF(3) Manual del Programador de Linux SCANF(3)
scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf - conversión de la
entrada con formato
#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);
La familia scanf de funciones escudriña la entrada según un formato
como se describe más adelante. Este formato puede contener especifi‐
cadores 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 pun‐
tero a FILE flujo utilizando una lista variable de argumentos de pun‐
teros (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 con‐
cuerda 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).
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 con‐
versió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 pun‐
tero 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 pun‐
tero 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 pun‐
tero 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 carac‐
teres 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 con‐
cuerda 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 misto‐
rioso 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 corre‐
spondan 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 pun‐
tero 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 blan‐
cos 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 carac‐
teres 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 direc‐
triz %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.
Estas funciones devuelven el número de elementos de la entrada asigna‐
dos, que pueden ser menores que los formatos suministrados para con‐
versió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 con‐
versió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.
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, mien‐
tras 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.
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 sen‐
tido en C ANSI (p.ej., %Ld). Aunque pueden tener un comportamiento
bien definido en Linux, esto no tiene por qué ser asà en otras arqui‐
tecturas. 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 combi‐
nación con conversiones diouxX o ll.
El empleo de q no es el mismo que en BSD 4.4, puesto que puede uti‐
lizarse en conversiones de coma flotante de forma equivalente a L.
LINUX 1 noviembre 1995 SCANF(3)