.\" Copyright (c) 1990, 1991 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Chris Torek and the American National Standards Committee X3,
.\" on Information Processing Systems.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)scanf.3	6.14 (Berkeley) 1/8/93
.\"
.\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu
.\" modified to resemble the GNU libio setup used in the Linux libc 
.\" used in versions 4.x (x>4) and 5   Helmut.Geyer@iwr.uni-heidelberg.de
.\" Modified, aeb, 970121
.\"
.\" Translated into Spanish Sat Mar  7 20:01:47 CET 1998 by Gerardo
.\" Aburruzaga García <gerardo.aburruzaga@uca.es>
.\" Traducción revisada por Miguel Pérez Ibars <mpi79470@alu.um.es> el 3-febrero-2005
.\"
.TH SCANF 3  "1 noviembre 1995" "LINUX" "Manual del Programador de Linux"
.SH NOMBRE
scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf \- conversión de la
entrada con formato
.SH SINOPSIS
.nf
.B #include <stdio.h>
.na
.BI "int scanf(const char *" format ", ..." );
.br
.BI "int fscanf(FILE *" stream ", const char *" format ", ..." );
.br
.BI "int sscanf(const char *" str ", const char *" format ", ..." );
.sp
.B #include <stdarg.h>
.BI "int vscanf(const char *" format ", va_list " ap );
.br
.BI "int vsscanf(const char *" str ", const char *" format ", va_list " ap );
.br
.BI "int vfscanf(FILE *" stream ", const char *" format ", va_list " ap );
.ad
.SH DESCRIPCIÓN
La familia
.B scanf
de funciones escudriña la entrada según un
.I formato
como se describe más adelante. Este formato puede contener
.IR "especificadores de conversión" ;
los resultados de tales conversiones, si las hay, se guardan donde
apunten los argumentos
.IR punteros .
La función
.B scanf
lee la entrada del flujo de entrada estándar
.IR stdin ,
.B fscanf
lee su entrada del puntero a FILE
.IR flujo ,
y
.B sscanf
lee su entrada de la cadena de caracteres a la que apunte
.IR str .
.PP
La función
.B vfscanf
es análoga a
.BR vfprintf (3)
y lee la entrada del puntero a FILE
.I flujo
utilizando una lista variable de argumentos de punteros (vea
.BR stdarg (3)).
La función
.B vscanf
rastrea una lista variable de argumentos de la entrada estándar y la función
.B vsscanf
la analiza de una cadena de caracteres; estas funciones son análogas a
.B vprintf
y
.B vsprintf
respectivamente.
.PP
Cada argumento
.I 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
.B %
(signo de porcentaje). La cadena de caracteres
.I formato
puede también contener otros caracteres. El espacio en blanco (como
espacios, tabuladores, o saltos de línea) en la cadena de
.I 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).
.SH CONVERSIONES
Después del carácter
.B %
que marca el comienzo de una conversión puede haber una serie de
caracteres de
.IR opción ,
como sigue:
.TP
.B *
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.
.TP
.B a 
(glibc) Indica que la conversión será
.BR s ,
el espacio de memoria necesario para la cadena se obtendrá mediante
malloc() y el puntero a ella se asignará a la variable puntero
.IR  char ,
que no tiene que haber sido inicializada anteriormente. Esta opción no
existe en
.IR "C ANSI"
(C89) y tiene un significado diferente en C99.
.TP
.B a
(C99) Equivalente a
.BR f .
.TP
.B h
Indica que la conversión será una de
.B dioux
o
.B n
y que el puntero siguiente lo es a un
.I short  int
(en vez de a un
.IR int ).
.TP
.B l
Indica bien que la conversión será una de
.B dioux
o
.B n
y el puntero siguiente lo es a un
.I long  int
(en vez de a un
.IR int ),
o bien que la conversión será una de
.B efg
y el puntero siguiente lo es a un
.I double
(en vez de a un
.IR float ).
Especificar dos opciones
.B l
equivale a la opción
.BR L .
.TP
.B L
Indica que la conversión será o bien
.B efg
y el siguiente puntero lo es a un
.IR "long double" 
o bien que la conversión será
.B dioux
y el siguiente puntero lo será a un
.IR "long long" .
(Observe que long long no es un tipo de
.IR "C ANSI" .
Un programa que utilice esto no será transportable a todas las
arquitecturas). 
.TP
.B q
equivalente a L.
Esta opción no existe en
.IR "C ANSI" .
.PP
Además de estas opciones, puede haber una anchura máxima de campo
opcional, expresado como un entero en base diez, entre el signo
.B %
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.
.PP
Están disponibles las siguientes conversiones:
.TP
.B %
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.
.TP
.B d
Concuerda con un entero en base diez con signo opcional; el siguiente
puntero debe serlo a
.IR int .
.TP
.B D
Equivalente a
.BR 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.)
.TP
.B i
Concuerda con un entero con signo opcional; el siguiente puntero debe
serlo a
.IR 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.
.TP
.B o
Concuerda con un entero octal sin signo; el siguiente puntero debe
serlo a 
.IR "unsigned int" .
.TP
.B u
Concuerda con un entero en base diez sin signo; el siguiente puntero
debe serlo a
.IR "unsigned int" .
.TP
.B x .
Concuerda con un entero hexadecimal sin signo; el siguiente puntero
debe serlo a 
.IR "unsigned int" .
.TP
.B X
Equivalente a
.B x 
.TP
.B f .
Concuerda con un número en coma flotante con signo opcional; el
siguiente puntero debe serlo a
.IR float .
.TP
.B e
Equivalente a
.BR f .
.TP
.B g
Equivalente a
.BR f .
.TP
.B E
Equivalente a
.BR f 
.TP
.B s
Concuerda con una secuencia de caracteres distintos de blancos; el
siguiente puntero debe serlo a
.IR char ,
y el vector debe ser lo suficientemente grande como para aceptar toda
la secuencia y el carácter 0 ó
.B 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.
.TP
.B c
Concuerda con una secuencia de
.I anchura
caracteres (1 por omisión); el siguiente puntero debe serlo a
.IR char ,
y debe haber suficiente espacio para todos los caracteres (no se añade
el carácter
.B 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.
.TP
.B \&[
Concuerda con una secuencia no vacía de caracteres del conjunto
especificado de caracteres aceptados; el siguiente puntero debe serlo a
.IR char ,
y debe haber bastante sitio para todos los caracteres en la cadena,
más un
.B 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
.B [
y un carácter de corchete de cierre
.BR ] .
El conjunto
.I excluye
esos caracteres si el primero después del corchete abierto es un
acento circunflejo
.BR ^ .
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
.B -
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.
.TP
.B p
Concuerda con un valor de tipo puntero (como se imprima por `%p' en
.BR printf (3));
el siguiente puntero debe serlo a
.IR void .
.TP
.B 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
.IR int .
Esto
.I no
es una conversión, aunque pueda suprimirse con la opción
.BR * .
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.

.PP
.SH "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
.B 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.
.SH "VÉASE TAMBIÉN"
.BR strtol (3),
.BR strtoul (3),
.BR strtod (3),
.BR getc (3),
.BR printf (3)
.SH CONFORME A
Las funciones
.BR fscanf ,
.BR scanf ,
y
.BR sscanf
son conformes al estándar ANSI X3.159-1989 (``C ANSI'').
.PP
La opción
.B q
es la notación de
.I BSD 4.4
para el tipo
.IR "long long" ,
mientras que
.B ll
o el empleo de
.B L
en conversiones de enteros, es la notación de GNU.
.PP
La versión de Linux de estas funciones se basa en la biblioteca
.I libio
de
.IR GNU .
Eche un vistazo a la documentación en formato
.I info
de
.I GNU
.I libc (glibc-1.08)
para una descripción más concisa.
.SH FALLOS
Todas las funciones son conformes completamente con el estándar ANSI
X3.159-1989, pero proporcionan las opciones adicionales
.B q
y
.B a
así como un comportamiento adicional de las opciones
.B L
y
.BR 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.
.PP
Algunas combinaciones de opciones definidas por C
.I ANSI
no tienen sentido en
.IR "C ANSI" 
(p.ej.,
.BR "%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
.I ANSI
en absoluto, i.e., usar
.B q
en vez de
.B L
en combinación con conversiones
.B diouxX
o
.BR ll .
.PP
El empleo de
.B q
no es el mismo que en
.IR "BSD 4.4" ,
puesto que puede utilizarse en conversiones de coma flotante de forma
equivalente a
.BR L .