.\" 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 Garca <gerardo.aburruzaga@uca.es>
.\"
.TH SCANF 3  "7 Marzo 1998" "LINUX" "Manual del Programador de Linux"
.SH NOMBRE
scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf \- conversin de la
entrada con formato
.SH SINOPSIS
.nf
.B #include <stdio.h>
.na
.BI "int scanf( const char *" formato ", ..." );
.br
.BI "int fscanf( FILE *" flujo ", const char *" formato ", ..." );
.br
.BI "int sscanf( const char *" str ", const char *" formato ", ..." );
.sp
.B #include <stdarg.h>
.BI "int vscanf( const char *" formato ", va_list " ap );
.br
.BI "int vsscanf( const char *" str ", const char *" formato ", va_list " ap );
.br
.BI "int vfscanf( FILE *" flujo ", const char *" formato ", va_list " ap );
.ad
.SH DESCRIPCIN
La familia
.B scanf
de funciones escudria la entrada segn un
.I formato
como se describe ms adelante. Este formato puede contener
.IR "especificadores de conversin" ;
los resultados de tales conversiones, si las hay, se guardan donde
apunten los argumentos
.IR punteros .
La funcin
.B scanf
lee la entrada del flujo de entrada estndar
.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 funcin
.B vfscanf
es anloga 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 funcin
.B vscanf
rastrea una lista variable de argumentos de la entrada estndar y la funcin
.B vsscanf
la analiza de una cadena de caracteres; estas funciones son anlogas a
.B vprintf
y
.B vsprintf
respectivamente.
.PP
Cada argumento
.I puntero
sucesivo debe corresponder correctamente con cada especificador de
conversin sucesivo (pero vea ms adelante lo referente a
`supresin'). Todas las conversiones empiezan con el carcter
.B %
(signo de porcentaje). La cadena de caracteres
.I formato
puede tambin contener otros caracteres. El espacio en blanco (como
espacios, tabuladores, o saltos de lnea) 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 anlisis acaba cuando un carcter de
la entrada no concuerda con un carcter del formato. Tambin cuando
una conversin no puede realizarse (vea ms adelante).
.SH CONVERSIONES
Despus del carcter
.B %
que marca el comienzo de una conversin puede haber una serie de
caracteres de
.IR opcin ,
como sigue:
.TP
.B *
Suprime la asignacin. La conversin que sigue ocurre como si nada,
pero no se usa ningn puntero; el resultado de la conversin
simplemente se descarta.
.TP
.B a 
Indica que la conversin 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 opcin no
existe en
.IR "C ANSI" .
.TP
.B h
Indica que la conversin 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 conversin 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 conversin 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 opcin
.BR L .
.TP
.B L
Indica que la conversin ser o bien
.B efg
y el siguiente puntero lo es a un
.IR "long double" 
o bien que la conversin 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 opcin no existe en
.IR "C ANSI" .
.PP
Adems de estas opciones, puede haber una anchura mxima de campo
opcional, expresado como un entero en base diez, entre el signo
.B %
y la conversin. Si no se da la anchura, se supone `infinita' (con una
excepcin, vea ms abajo); si se da, como mucho se miran los
caracteres especificados en ella cuando haya que procesar la
conversin. Antes de que sta comience, la mayora descartan el
espacio en blanco; este espacio no cuenta para la anchura de campo.
.PP
Estn disponibles las siguientes conversiones:
.TP
.B %
Concuerda con un '%' literal. Esto es, `%\&%' en el formato concuerda
con un solo carcter '%' en la entrada. No se hace ninguna conversin,
y no hay ninguna asignacin.
.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 slo 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 dgito. Slo 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 nmero 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 carcter 0 
.B NUL
final.  El anlisis de la cadena de entrada acaba en el siguiente
espacio blanco o cuando se llega a la anchura de campo mxima, lo que
ocurra antes.
.TP
.B c
Concuerda con una secuencia de
.I anchura
caracteres (1 por omisin); el siguiente puntero debe serlo a
.IR char ,
y debe haber suficiente espacio para todos los caracteres (no se aade
el carcter
.B NUL
terminador).  Se suprime el descarte de los blancos iniciales. Para
saltar un espacio en blanco inicial, emplee un espacio explcito en el
formato.
.TP
.B \&[
Concuerda con una secuencia no vaca 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,
ms 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 carcter de corchete de cierre
.BR ] .
El conjunto
.I excluye
esos caracteres si el primero despus del corchete abierto es un
acento circunflejo
.BR ^ .
Para incluir un corchete de cierre en el conjunto, pngalo el primero
tras el corchete abierto o el circunflejo; en cualquiera otra posicin
indicar que termina el conjunto.
El carcter guin
.B -
es tambin especial; cuando se pone entre dos otros caracteres, aade
todos los de enmedio al conjunto. Para incluir un guin, pngalo como
el ltimo carcter antes del corchete de cierre final. Por ejemplo,
`[^]0-9-]' significa el conjunto de `todos los caracteres excepto el
corchete de cierre, los dgitos del cero al nueve, y el guin'.
La cadena acaba con la aparicin de un carcter 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 nmero de
caracteres consumidos o ledos hasta ahora de la entrada en donde
apunte el siguiente puntero, que debe serlo a
.IR int .
Esto
.I no
es una conversin, aunque pueda suprimirse con la opcin
.BR * .
El estndar de C dice: `La ejecucin de una directriz %n no incrementa
el nmero de asignaciones devuelto al final de la ejecucin', pero
el Aadido de Correcciones parece contradecir esto. Probablemente es
lo mejor no hacer ninguna suposicin sobre el efecto de las
conversiones %n en el valor de retorno de la funcin.

.PP
.SH "VALOR DEVUELTO"
Estas funciones devuelven el nmero de elementos de la entrada
asignados, que pueden ser menores que los formatos suministrados para
conversin, o incluso cero, en el caso de un fallo de concordancia.
Cero indica que, mientras haba caracteres disponibles en la entrada,
no ocurri ninguna asignacin; normalmente esto es debido a un
carcter de entrada invlido, como un carcter alfabtico para una
conversin `%d'. Se devuelve el valor
.B EOF
si ha habido un fallo de entrada antes de ninguna conversin, como
cuando se llega al final de la entrada. Si ocurre un error de lectura
o se llega al final de la entrada despus de que se haya hecho alguna
conversin al menos, se devuelve el nmero de conversiones completadas
hasta ese punto con xito.
.SH "VASE TAMBIN"
.BR strtol "(3), " strtoul "(3), " strtod "(3), " getc "(3), " printf (3)
.SH CONFORME A
Las funciones
.BR fscanf ,
.BR scanf ,
y
.BR sscanf
son conformes al estndar ANSI C3.159-1989 (``C ANSI'').
.PP
La opcin
.B q
es la notacin 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 notacin de GNU.
.PP
La versin de Linux de estas funciones se basa en la biblioteca
.I libio
de
.IR GNU .
Eche un vistazo a la documentacin en formato
.I info
de
.I GNU
.I libc (glibc-1.08)
para una descripcin ms concisa.
.SH FALLOS
Todas las funciones son conformes completamente con el estndar ANSI
C3.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 estndar ANSI C3.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 combinacin 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 .