scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l

Artigo
03/12/2013

Dados formatados de leitura de fluxo de entrada padrão.Essas são versões de scanf, _scanf_l, wscanf, _wscanf_l com aprimoramentos de segurança conforme 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 formato do controle.
argument
Argumentos opcionais.
locale
A localidade a ser usada.

Valor de retorno

Retorna o número de campos com êxito convertidos e atribuído; o valor de retorno não inclui os campos que foram lidos mas não atribuído.Um valor de retorno de 0 indica que nenhuma propriedade esteve atribuído.O valor de retorno é EOFpara um erro ou se o caractere de final de Arquivo ou o caractere de fim de cadeia de caracteres estão localizados na primeira tentativa de ler um caractere.Se format é um ponteiro de NULL , o manipulador inválido do parâmetro é invocado, como descrito em Validação de parâmetro.Se a execução é permitida continuar, scanf_s e wscanf_s retornam EOF e errno defina a EINVAL.

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

Comentários

A função de scanf_sler dados de fluxo de entrada padrão stdine grava os dados na localidade determinada por argument.Cada argument deve ser um ponteiro a uma variável de um tipo que corresponde a um especificador de tipo em format.Se copiar ocorre entre as cadeias de caracteres que sobrepostos, o comportamento é indefinido.

wscanf_sé uma versão de largo- caractere de scanf_s; o argumento de format a wscanf_sé uma cadeia de caracteres de largo- caractere.wscanf_se scanf_sse comportam de forma idêntica mesmo se o fluxo é aberta no modo ANSI.scanf_s não tem suporte para a entrada de um fluxo de UNICODE.

As versões dessas funções com o sufixo de _l são idênticas exceto que usam o parâmetro de localidade passado em vez de localidade atual da thread.

Ao contrário de scanfe de wscanf, scanf_se wscanf_srequerem o tamanho do buffer ser especificados para todos os parâmetros de entrada do tipo c, C, s, S, ou [.O tamanho do buffer caracteres em é passado como um parâmetro adicional imediatamente após o ponteiro ao buffer ou à variável.Por exemplo, se ler uma cadeia de caracteres, o tamanho do buffer para essa cadeia de caracteres é passada como segue:

char s[10];

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

O tamanho do buffer inclui o zero de terminação.Um campo de especificação de largura pode ser usado para garantir que o símbolo lê caiba no buffer.Se nenhum campo de especificação de largura é usado, e a leitura do símbolo é muito grande caber no buffer, nada será escrito no buffer.

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

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

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

O especificador de formato indica S o uso da largura de caracteres que é “oposto” largura padrão que é suportada pela função.A largura de caractere é único byte, mas caracteres de byte duplo de suporte da função.Este exemplo lê uma cadeia de caracteres de até 9 caracteres de largura único-byte- e os coloca em um buffer dobro-byte- largo de caracteres.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, se possível ler um único caractere seguinte maneira:

char c;

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

Ao ler mais caracteres para cadeias de caracteres terminadas não anuláveis, inteiros 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 scanf especificação de largura.

Mapeamentos da rotina de Genérico- texto

Rotina de TCHAR.H	_UNICODE & _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 — funções de scanf e funções de 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 é suportado em aplicativos de Windows Store .Identificadores padrões de fluxo associadas ao console, stdin, stdout, e stderr, devem ser redirecionada antes que as funções de tempo de execução das C pode usar em aplicativos de Windows Store .Para informações extras de compatibilidade Compatibilidade na introdução, consulte.

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);
}