Namespaces
Variants

scanf, fscanf, sscanf, scanf_s, fscanf_s, sscanf_s

From cppreference.net
< c ‎ | io
C
File input/output
Types and objects
Functions
File access
Unformatted input/output
Formatted input
scanf fscanf sscanf scanf_s fscanf_s sscanf_s
(C11) (C11) (C11)
(C95) (C95) (C95) (C11) (C11) (C11)
Definido en el encabezado <stdio.h>
(1)
int scanf ( const char * format, ... ) ;
(hasta C99)
int scanf ( const char * restrict format, ... ) ;
(desde C99)
(2)
int fscanf ( FILE * stream, const char * format, ... ) ;
(hasta C99)
int fscanf ( FILE * restrict stream, const char * restrict format, ... ) ;
(desde C99)
(3)
int sscanf ( const char * buffer, const char * format, ... ) ;
(hasta C99)
int sscanf ( const char * restrict buffer, const char * restrict format, ... ) ;
(desde C99)
int scanf_s ( const char * restrict format, ... ) ;
(4) (desde C11)
int fscanf_s ( FILE * restrict stream, const char * restrict format, ... ) ;
(5) (desde C11)
int sscanf_s ( const char * restrict buffer, const char * restrict format, ... ) ;
(6) (desde C11)

Lee datos de una variedad de fuentes, los interpreta según el format y almacena los resultados en las ubicaciones indicadas.

1) lee los datos desde stdin
2) lee los datos del flujo de archivo stream
3) lee los datos de la cadena de caracteres terminada en nulo buffer . Alcanzar el final de la cadena es equivalente a alcanzar la condición de fin de archivo para fscanf
4-6) Igual que (1-3) , excepto que % c , % s , y % [ esperan cada uno dos argumentos (el puntero habitual y un valor de tipo rsize_t que indica el tamaño del array receptor, que puede ser 1 al leer con % c en un solo char) y excepto que los siguientes errores se detectan en tiempo de ejecución y llaman a la función manejadora de restricciones actualmente instalada:
  • cualquiera de los argumentos de tipo puntero es un puntero nulo
  • format , stream , o buffer es un puntero nulo
  • el número de caracteres que serían escritos por % c , % s , o % [ , más el carácter nulo terminador, excedería el segundo argumento ( rsize_t ) proporcionado para cada uno de esos especificadores de conversión
  • opcionalmente, cualquier otro error detectable, como un especificador de conversión desconocido
Como con todas las funciones con verificación de límites, scanf_s , fscanf_s , y sscanf_s solo están garantizadas de estar disponibles si __STDC_LIB_EXT1__ está definido por la implementación y si el usuario define __STDC_WANT_LIB_EXT1__ como la constante entera 1 antes de incluir <stdio.h> .

Contenidos

Parámetros

stream - flujo de archivo de entrada desde el cual leer
buffer - puntero a una cadena de caracteres terminada en nulo desde la cual leer
format - puntero a una cadena de caracteres terminada en nulo que especifica cómo leer la entrada
... - argumentos receptores.


La cadena de formato consiste en

  • caracteres multibyte que no son espacios en blanco excepto % : cada uno de estos caracteres en la cadena de formato consume exactamente un carácter idéntico del flujo de entrada, o provoca que la función falle si el siguiente carácter en el flujo no es igual.
  • caracteres de espacio en blanco: cualquier carácter individual de espacio en blanco en la cadena de formato consume todos los caracteres consecutivos de espacio en blanco disponibles en la entrada (determinado como si se llamara a isspace en un bucle). Nótese que no hay diferencia entre " \n " , " " , " \t \t " , u otros espacios en blanco en la cadena de formato.
  • especificaciones de conversión. Cada especificación de conversión tiene el siguiente formato:
  • carácter introductorio % .
  • (opcional) carácter de supresión de asignación * . Si esta opción está presente, la función no asigna el resultado de la conversión a ningún argumento receptor.
  • (opcional) número entero (mayor que cero) que especifica el ancho máximo de campo , es decir, el número máximo de caracteres que la función puede consumir al realizar la conversión especificada por la especificación de conversión actual. Nótese que % s y % [ pueden provocar desbordamiento de búfer si no se proporciona el ancho.
  • (opcional) modificador de longitud que especifica el tamaño del argumento receptor, es decir, el tipo de destino real. Esto afecta la precisión de conversión y las reglas de desbordamiento. El tipo de destino predeterminado es diferente para cada tipo de conversión (ver tabla abajo).
  • especificador de formato de conversión.

Los siguientes especificadores de formato están disponibles:

Especificador
de conversión 		Explicación Tipo de
argumento esperado
Modificador de Longitud→ hh h ninguno l ll j z t L
Solo disponible desde C99→ Sí Sí Sí Sí Sí
%
Coincide con el literal % .
N/A N/A N/A N/A N/A N/A N/A N/A N/A
c

Coincide con un carácter o una secuencia de caracteres .

  • Si se utiliza un especificador de ancho, coincide exactamente con ancho caracteres (el argumento debe ser un puntero a un array con espacio suficiente).
  • A diferencia de %s y %[, no añade el carácter nulo al array.
N/A N/A
char *
wchar_t *
N/A N/A N/A N/A N/A
s

Coincide con una secuencia de caracteres que no son espacios en blanco (una cadena ).

  • Si se utiliza el especificador de ancho, coincide hasta width o hasta el primer carácter de espacio en blanco, lo que ocurra primero.
  • Siempre almacena un carácter nulo además de los caracteres coincidentes (por lo que el arreglo de argumentos debe tener espacio para al menos width+1 caracteres).
[ set  ]

Coincide con una secuencia no vacía de caracteres del set de caracteres.

  • Si el primer carácter del set es ^ , entonces coinciden todos los caracteres que no están en el set.
  • Si el set comienza con ] o ^] entonces el carácter ] también se incluye en el set.
  • Está definido por la implementación si el carácter - en posición no inicial en el scanset puede indicar un rango, como en [0-9] .
  • Si se utiliza el especificador de ancho, coincide solo hasta width .
  • Siempre almacena un carácter nulo además de los caracteres coincidentes (por lo que el array de argumento debe tener espacio para al menos width+1 caracteres).
d

Coincide con un entero decimal .

  • El formato del número es el mismo que se espera por strtol con el valor 10 para el argumento base .
signed char * o unsigned char *
signed short * o unsigned short *
signed int * o unsigned int *
signed long * o unsigned long *
signed long long * o unsigned long long *
N/A
i

Coincide con un entero .

  • El formato del número es el mismo que espera strtol con el valor ​ 0 ​ para el argumento base (la base se determina por los primeros caracteres analizados).
u

Coincide con un entero decimal sin signo .

  • El formato del número es el mismo que se espera por strtoul con el valor 10 para el argumento base .
o

Coincide con un entero octal sin signo .

  • El formato del número es el mismo que se espera por strtoul con el valor 8 para el argumento base .
x
X

Coincide con un entero hexadecimal sin signo .

  • El formato del número es el mismo que el esperado por strtoul con el valor 16 para el argumento base .
n

Devuelve el número de caracteres leídos hasta el momento .

  • No se consume ninguna entrada. No incrementa el contador de asignaciones.
  • Si el especificador tiene definido el operador de supresión de asignación, el comportamiento es indefinido.
a (C99)
A (C99)
e
E
f
F (C99)
g
G

Coincide con un número de punto flotante .

  • El formato del número es el mismo esperado por strtof .
N/A N/A
float *
double *
N/A N/A N/A N/A
long double *
p

Coincide con la secuencia de caracteres definida por la implementación que define un puntero .

  • printf la familia de funciones debería producir la misma secuencia usando el %p especificador de formato.
N/A N/A
void **
N/A N/A N/A N/A N/A N/A
Notas

Para cada especificador de conversión distinto de n , la secuencia más larga de caracteres de entrada que no exceda el ancho de campo especificado y que sea exactamente lo que el especificador de conversión espera o sea un prefijo de una secuencia que esperaría, es lo que se consume del flujo. El primer carácter, si existe, después de esta secuencia consumida permanece sin leer. Si la secuencia consumida tiene longitud cero o si la secuencia consumida no puede convertirse como se especificó anteriormente, ocurre un fallo de coincidencia a menos que el fin de archivo, un error de codificación o un error de lectura impidieran la entrada del flujo, en cuyo caso es un fallo de entrada.

Todos los especificadores de conversión distintos de [ , c , y n consumen y descartan todos los caracteres de espacio en blanco iniciales (determinados como si se llamara a isspace ) antes de intentar analizar la entrada. Estos caracteres consumidos no cuentan para el ancho de campo máximo especificado.

Los especificadores de conversión lc , ls , y l [ realizan conversión de caracteres multibyte a ancho como si se llamara a mbrtowc con un objeto mbstate_t inicializado a cero antes de convertir el primer carácter.

Los especificadores de conversión s y [ siempre almacenan el terminador nulo además de los caracteres coincidentes. El tamaño del array de destino debe ser al menos uno mayor que el ancho de campo especificado. El uso de % s o % [ , sin especificar el tamaño del array de destino, es tan inseguro como gets .

Las especificaciones de conversión correctas para los tipos de enteros de ancho fijo ( int8_t , etc.) se definen en el encabezado <inttypes.h> (aunque SCNdMAX , SCNuMAX , etc. son sinónimos de % jd , % ju , etc.).

Hay un punto de secuencia después de la acción de cada especificador de conversión; esto permite almacenar múltiples campos en la misma variable "receptora".

Al analizar un valor de coma flotante incompleto que termina en el exponente sin dígitos, como analizar "100er" con el especificador de conversión % f , la secuencia "100e" (el prefijo más largo de un posible número de coma flotante válido) se consume, resultando en un error de coincidencia (la secuencia consumida no puede convertirse a un número de coma flotante), con "r" restante. Algunas implementaciones existentes no siguen esta regla y retroceden para consumir solo "100" , dejando "er" , por ejemplo, glibc bug 1765 .

Si una especificación de conversión es inválida, el comportamiento es indefinido.

Si una especificación de conversión es inválida, el comportamiento es indefinido.

Valor de retorno

1-3) Número de argumentos receptores asignados exitosamente (que puede ser cero en caso de que ocurriera un error de coincidencia antes de que se asignara el primer argumento receptor), o EOF si ocurre un fallo de entrada antes de que se asignara el primer argumento receptor.
4-6) Lo mismo que (1-3) , excepto que EOF también se devuelve si hay una violación de restricción en tiempo de ejecución.

Complejidad

No está garantizado. Notablemente, algunas implementaciones de sscanf son O(N) , donde N = strlen ( buffer ) [1] .

Notas

Debido a que la mayoría de especificadores de conversión primero consumen todos los espacios en blanco consecutivos, código como 

scanf("%d", &a);
scanf("%d", &b);

leerá dos enteros que se ingresen en líneas diferentes (el segundo % d consumirá el salto de línea dejado por el primero) o en la misma línea, separados por espacios o tabulaciones (el segundo % d consumirá los espacios o tabulaciones).

The conversion specifiers that do not consume leading whitespace, such as % c , can be made to do so by using a whitespace character in the format string: 
scanf("%d", &a);
scanf(" %c", &c); // consumir todo el espacio en blanco consecutivo después de %d, luego leer un carácter

Ejemplo

Ejecutar este código 
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
#include <stddef.h>
#include <locale.h>
int main(void)
{
    int i, j;
    float x, y;
    char str1[10], str2[4];
    wchar_t warr[2];
    setlocale(LC_ALL, "en_US.utf8");
    char input[] = "25 54.32E-1 Thompson 56789 0123 56ß水";
    /* analizar como sigue:
       %d: un entero
       %f: un valor de punto flotante
       %9s: una cadena de máximo 9 caracteres que no sean espacios
       %2d: entero de dos dígitos (dígitos 5 y 6)
       %f:  un valor de punto flotante (dígitos 7, 8, 9)
       %*d: un entero que no se almacena en ningún lugar
       ' ': todos los espacios consecutivos
       %3[0-9]: una cadena de máximo 3 dígitos decimales (dígitos 5 y 6)
       %2lc: dos caracteres anchos, usando conversión de multibyte a ancho  */
    int ret = sscanf(input, "%d%f%9s%2d%f%*d %3[0-9]%2lc",
                     &i, &x, str1, &j, &y, str2, warr);
    printf("Converted %d fields:\n"
           "i = %d\n"
           "x = %f\n"
           "str1 = %s\n"
           "j = %d\n"
           "y = %f\n"
           "str2 = %s\n"
           "warr[0] = U+%x\n"
           "warr[1] = U+%x\n",
           ret, i, x, str1, j, y, str2, warr[0], warr[1]);
#ifdef __STDC_LIB_EXT1__
    int n = sscanf_s(input, "%d%f%s", &i, &x, str1, (rsize_t)sizeof str1);
    // escribe 25 en i, 5.432 en x, los 9 bytes "Thompson\0" en str1, y 3 en n.
#endif
}

Salida posible: 

Converted 7 fields:
i = 25
x = 5.432000
str1 = Thompson
j = 56
y = 789.000000
str2 = 56
warr[0] = U+df
warr[1] = U+6c34

Referencias

  • Estándar C17 (ISO/IEC 9899:2018):
  • 7.21.6.2 La función fscanf (p: 231-236)
  • 7.21.6.4 La función scanf (p: 236-237)
  • 7.21.6.7 La función sscanf (p: 238-239)
  • K.3.5.3.2 La función fscanf_s (p: 430-431)
  • K.3.5.3.4 La función scanf_s (p: 432)
  • K.3.5.3.7 La función sscanf_s (p: 433)
  • Estándar C11 (ISO/IEC 9899:2011):
  • 7.21.6.2 La función fscanf (p: 317-324)
  • 7.21.6.4 La función scanf (p: 325)
  • 7.21.6.7 La función sscanf (p: 326)
  • K.3.5.3.2 La función fscanf_s (p: 592-593)
  • K.3.5.3.4 La función scanf_s (p: 594)
  • K.3.5.3.7 La función sscanf_s (p: 596)
  • Estándar C99 (ISO/IEC 9899:1999):
  • 7.19.6.2 La función fscanf (p: 282-289)
  • 7.19.6.4 La función scanf (p: 290)
  • 7.19.6.7 La función sscanf (p: 291)
  • Estándar C89/C90 (ISO/IEC 9899:1990):
  • 4.9.6.2 La función fscanf
  • 4.9.6.4 La función scanf
  • 4.9.6.6 La función sscanf

Véase también

(C99) (C99) (C99) (C11) (C11) (C11)
lee entrada formateada desde stdin , un flujo de archivo o un búfer
usando una lista de argumentos variables
(función)
obtiene una cadena de caracteres desde un flujo de archivo
(función)
(C99) (C11) (C11) (C11) (C11)
imprime salida formateada hacia stdout , un flujo de archivo o un búfer
(función)
Documentación de C++ para scanf , fscanf , sscanf