scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l

Artigo
06/09/2015

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

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 de retorno

Retorna o número de campos que com êxito são convertidos e atribuídos; o valor de retorno não inclui os campos que foram lidos mas não atribuídos. Um valor de retorno 0 indica que nenhum campo foi atribuído. O valor de retorno é EOF para um erro, ou se o caractere final do arquivo ou caractere final da cadeia de caracteres for localizado na primeira tentativa de leitura de caractere. Se format é um ponteiro NULL, o parâmetro de manipulador inválido é invocado, como descrito em Validação do parâmetro. Se a execução puder continuar, scanf_s e wscanf_s retornam EOF e configuram errno para EINVAL.

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

Comentários

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

wscanf_s é uma versão de caractere longo de scanf_s; o argumento format para wscanf_s é uma cadeia de caractere longo. wscanf_s e scanf_s se comportarão de forma idêntica se o fluxo for aberto no modo de ANSI. scanf_s não oferece suporte a entrada de um fluxo de UNICODE.

As versões dessas funções que têm o sufixo de _l são idênticas a qual delass usam o parâmetro de localidade que é passado em vez de localidade do thread atual.

Ao contrário de scanf e de wscanf, scanf_s e wscanf_s requerem que o tamanho do buffer seja especificado para todos os parâmetros de entrada do tipo c, C, s, S, ou conjuntos de controle de cadeia de caracteres que estão incluídos no []. O tamanho do buffer em caracteres é passado como um parâmetro adicional, imediatamente após o ponteiro para o buffer ou a variável. Por exemplo, se você está lendo uma cadeia de caracteres, o tamanho do buffer para a cadeia de caracteres é passado como segue:

char s[10];

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

O tamanho do buffer inclui a terminação nula. Você pode usar um campo da especificação de largura para garantir que o token que é lido se ajuste no buffer. Se nenhum campo de especificação de largura for usado e o token lido for muito grande para caber no buffer, nada será gravado ao buffer.

Dica

O parâmetro de tamanho é do tipo unsigned, e não size_t.

O exemplo a seguir mostra que o parâmetro de tamanho do buffer descreve o número máximo de caracteres, não em bytes. Na chamada de wscanf_s, a largura do caractere que é indicada pelo tipo de buffer não corresponde à largura do caractere que é indicada pelo especificador de formato.

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

O especificador do formato de S indica o uso da largura do caractere que é “oposto” para a largura padrão que tem suporte da função. A largura do caractere é um byte, mas os caracteres de byte duplo da suporte à função. Este exemplo lê em uma cadeia de caracteres de até 9 caracteres único-byte- todo o servidor e inseri-los em um buffer dobro-byte- amplo de caractere. Os caracteres são tratados como valores de byte único; os dois primeiros caracteres são armazenados em ws[0], os dois segundos são armazenados em ws[1], e assim por diante.

No caso de caracteres, um único caractere pode ser lido como segue:

char c;

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

Quando vários caracteres para cadeias de caracteres encerradas não nulos são lidos, integers são usados como a especificação de largura e o tamanho do buffer.

char c[4];

scanf_s("%4c", &c, _countof(c)); // not null terminated

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

Mapeamentos da rotina de texto genérico

Rotina TCHAR.H	_UNICODE & _MBCS não definido	_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 Campos de especificação de formato: funções scanf e wscanf.

Requisitos

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

O console não tem suporte em aplicativos do Windows Store. Os manipuladores de fluxo padrão associados ao console — stdin, stdout e stderr — devem ser redirecionados antes que as funções de tempo de execução do C possam utilizá-los em aplicativos do Windows Store. Para obter informações adicionais 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, _countof(s), ws, _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, _countof(s), ws, _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);
}

Esse programa gerencia a seguinte saída quando na entrada:

71 98.6 h z Byte characters

36 92.3 y n Wide characters