scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l

Lê dados formatados do fluxo de entrada padrão. Essas versões do , _scanf_l, wscanf, _wscanf_l têm aprimoramentos descanf segurança, conforme descrito em Recursos de segurança no CRT.

Sintaxe

int scanf_s(
   const char *format [,
   argument]...
);
int _scanf_s_l(
   const char *format,
   _locale_t locale [,
   argument]...
);
int wscanf_s(
   const wchar_t *format [,
   argument]...
);
int _wscanf_s_l(
   const wchar_t *format,
   _locale_t locale [,
   argument]...
);

Parâmetros

format
Cadeia de caracteres de controle de formato.

argument
Argumentos opcionais.

locale
A localidade a ser usada.

Valor retornado

Retorna o número de campos convertidos e atribuídos com êxito. O valor retornado não inclui campos que foram lidos, mas não atribuídos. Um valor retornado igual a 0 indica que nenhum campo foi atribuído. O valor retornado é EOF para um erro ou se o caractere de fim de arquivo ou o caractere de fim de cadeia de caracteres for encontrado na primeira tentativa de ler um caractere. Se format for um NULL ponteiro, o manipulador de parâmetro inválido será invocado, conforme descrito em Validação de parâmetro. Se a execução tiver permissão para continuar, scanf_s e wscanf_s retornarão EOF e definirão errno como EINVAL.

Para obter informações sobre esses e outros códigos de erro, confira errno, _doserrno, _sys_errlist e _sys_nerr.

Comentários

A função scanf_s lê dados do fluxo de entrada padrão stdin e a grava em argument. Cada argument deve ser um ponteiro para um tipo de variável que corresponde ao especificador de tipo em format. Se ocorrer cópia entre cadeias de caracteres que se sobrepõem, o comportamento será indefinido.

A função wscanf_s é uma versão de caractere largo da função scanf_s; o argumento format para wscanf_s é uma cadeia de caracteres larga. wscanf_s e scanf_s terão comportamento idêntico se o fluxo for aberto no modo ANSI. Atualmente, scanf_s não dá suporte à entrada de um fluxo UNICODE.

As versões dessas funções que têm o _l sufixo são idênticas, exceto que usam o locale parâmetro em vez da localidade do thread atual.

Diferente de scanf e wscanf, scanf_s e wscanf_s exigirão que você especifique tamanhos de buffer para alguns parâmetros. Especifique os tamanhos para todos, c, C, s, S ou parâmetros [] de conjunto de controle de cadeia de caracteres. O tamanho do buffer em caracteres é passado como outro parâmetro. Ele segue imediatamente o ponteiro para o buffer ou variável. Por exemplo, se você estiver lendo uma cadeia de caracteres, o tamanho do buffer para essa cadeia de caracteres será passado conforme demonstrado a seguir:

char s[10];
scanf_s("%9s", s, (unsigned)_countof(s)); // buffer size is 10, width specification is 9

O tamanho do buffer inclui o nulo de terminal. Você pode usar um campo de especificação de largura para garantir que o token que é lido caiba no buffer. Quando um token é muito grande para caber, nada é gravado no buffer, a menos que haja uma especificação de largura.

O tamanho do buffer descreve o número máximo de caracteres, não de bytes. Neste exemplo, a largura do tipo de buffer não corresponde à largura do especificador de formato.

wchar_t ws[10];
wscanf_s(L"%9S", ws, (unsigned)_countof(ws));

O especificador de formato S indica o uso da largura de caractere que é "oposta" à largura padrão com suporte pela função. A largura do caractere é de um byte, mas a função dá suporte a caracteres de dois bytes. Este exemplo lê uma cadeia de caracteres de até nove caracteres com um byte de largura e coloca-os em um buffer de caracteres com dois bytes de largura. Os caracteres são tratados como valores de byte único; os dois primeiros caracteres são armazenados em ws[0], os próximos dois são armazenados em ws[1] e assim por diante.

Este exemplo lê um único caractere:

char c;
scanf_s("%c", &c, 1);

Quando vários caracteres para cadeias de caracteres terminadas em não nulo são lidos, inteiros são usados como a especificação de largura e o tamanho do buffer.

char c[4];
scanf_s("%4c", c, (unsigned)_countof(c)); // not null terminated

Para obter mais informações, consulte Especificação de largura de scanf.

Mapeamentos de rotina de texto genérico

Para obter mais informações, consulte Campos de especificação de formato: scanf e wscanf funções.

Requisitos

Não há suporte para o console em aplicativos UWP (Plataforma Universal do Windows). Os identificadores de fluxo padrão stdin, stdout e stderr, devem ser redirecionados antes que as funções em tempo de execução C possam usá-los em aplicativos UWP. Para obter informações sobre compatibilidade, consulte Compatibilidade.

Exemplo

// crt_scanf_s.c
// This program uses the scanf_s and wscanf_s functions
// to read formatted input.

#include <stdio.h>
#include <stdlib.h>

int main( void )
{
   int      i,
            result;
   float    fp;
   char     c,
            s[80];
   wchar_t  wc,
            ws[80];

   result = scanf_s( "%d %f %c %C %s %S", &i, &fp, &c, 1,
                     &wc, 1, s, (unsigned)_countof(s), ws, (unsigned)_countof(ws) );
   printf( "The number of fields input is %d\n", result );
   printf( "The contents are: %d %f %c %C %s %S\n", i, fp, c,
           wc, s, ws);
   result = wscanf_s( L"%d %f %hc %lc %S %ls", &i, &fp, &c, 2,
                      &wc, 1, s, (unsigned)_countof(s), ws, (unsigned)_countof(ws) );
   wprintf( L"The number of fields input is %d\n", result );
   wprintf( L"The contents are: %d %f %C %c %hs %s\n", i, fp,
            c, wc, s, ws);
}

Este programa produz a seguinte saída quando recebe essa entrada:

71 98.6 h z Byte characters
36 92.3 y n Wide characters

The number of fields input is 6
The contents are: 71 98.599998 h z Byte characters
The number of fields input is 6
The contents are: 36 92.300003 y n Wide characters

Confira também

Suporte matemático e de ponto flutuante
E/S de fluxo
Localidade
fscanf, _fscanf_l, fwscanf, _fwscanf_l
printf, _printf_l, wprintf, _wprintf_l
sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
sscanf, _sscanf_l, swscanf, _swscanf_l