scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l

Lê dados formatados do fluxo de entrada padrão. Essas versões do , , , _wscanf_ltêm aprimoramentos de segurança, _scanf_lwscanfconforme descrito em Recursos de scanfsegurança na 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.

Retornar valor

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 de retorno é 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âmetros inválido será chamado, 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 sufixo são idênticas, exceto que usam o _llocale 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.

Observação

O parâmetro de tamanho é do tipo unsigned, não size_t. Use uma conversão estática para converter um valor size_t em unsigned para configurações de build de 64 bits.

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

Rotina TCHAR.H	_UNICODE e _MBCS não definidos	_MBCS definido	_UNICODE definido
_tscanf_s	scanf_s	scanf_s	wscanf_s
_tscanf_s_l	_scanf_s_l	_scanf_s_l	_wscanf_s_l

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

Requisitos

Rotina	Cabeçalho necessário
scanf_s, _scanf_s_l	<stdio.h>
wscanf_s, _wscanf_s_l	<stdio.h> ou <wchar.h>

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 a matemática e 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