sscanf_s, _sscanf_s_l, swscanf_s, _swscanf_s_l

Lê dados formatados de uma cadeia de caracteres. Essas versões dosscanf , _sscanf_l, swscanftêm _swscanf_l aprimoramentos de segurança, conforme descrito em Recursos de segurança no CRT.

Sintaxe

int sscanf_s(
   const char *buffer,
   const char *format [,
   argument ] ...
);
int _sscanf_s_l(
   const char *buffer,
   const char *format,
   _locale_t locale [,
   argument ] ...
);
int swscanf_s(
   const wchar_t *buffer,
   const wchar_t *format [,
   argument ] ...
);
int _swscanf_s_l(
   const wchar_t *buffer,
   const wchar_t *format,
   _locale_t locale [,
   argument ] ...
);

Parâmetros

buffer
Dados armazenados

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

argument
Argumentos opcionais

locale
A localidade a ser usada

Valor Retornado

Cada uma dessas funções retorna o número de campos que são 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 será EOF para um erro ou se o fim da cadeia de caracteres for alcançado antes da primeira conversão.

Se buffer ou format for um ponteiro NULL, o manipulador de parâmetro inválido será invocado, conforme descrito em Validação de parâmetro. Se a execução for permitida, essas funções retornarão -1 e definirão errno como EINVAL

Para obter informações sobre esses e outros códigos de erro, consulteerrno , _doserrno_sys_errlist, e _sys_nerr.

Comentários

A função sscanf_s lê dados de buffer no local fornecido por cada argument. Os argumentos após a cadeia de caracteres de formato especificam ponteiros para variáveis que têm um tipo que corresponde a um especificador de tipo no formato . Ao contrário da versão menos segura sscanf, um parâmetro de tamanho do buffer é necessário quando você usa os caracteres de campo de tipo c, C, s, S ou conjuntos de controle de cadeia de caracteres contidos em []. O tamanho do buffer em caracteres deve ser fornecido como um parâmetro adicional imediatamente após cada parâmetro de buffer que precisa dele. 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:

wchar_t ws[10];
swscanf_s(in_str, L"%9s", ws, (unsigned)_countof(ws)); // buffer size is 10, width specification is 9

O tamanho do buffer inclui o nulo de terminação. Um campo de especificação de largura pode ser usado para garantir que o token lido caiba 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 no buffer.

No caso de caracteres, um único caractere pode ser lido como demonstrado a seguir:

wchar_t wc;
swscanf_s(in_str, L"%c", &wc, 1);

Este exemplo lê um único caractere da cadeia de caracteres de entrada e o armazena em um buffer de caractere largo. Quando vários caracteres para cadeias de caracteres terminadas em não nulo são lidos, inteiros sem sinal são usados como a especificação de largura e o tamanho do buffer.

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

Para obter mais informações, consultescanf_s , _scanf_s_l, wscanf_se _wscanf_s_lCaracteres de camposcanf de tipo.

Observação

O parâmetro de tamanho é do tipo unsigned, não size_t. Ao compilar para destinos de 64 bits, use uma conversão estática para converter os resultados _countof ou sizeof para o tamanho correto.

O argumento format controla a interpretação dos campos de entrada e tem o mesmo formato e a mesma função que o argumento format para a função scanf_s. Se ocorrer cópia entre cadeias de caracteres que se sobrepõem, o comportamento será indefinido.

swscanf_s é uma versão de caractere largo de sscanf_s; os argumentos para swscanf_s são cadeias de caracteres largas. sscanf_s não manipula caracteres hexadecimais multibyte. swscanf_s não manipula hexadecimal de largura total do Unicode nem caracteres de "zona de compatibilidade". Caso contrário, swscanf_s e sscanf_s comportam-se de modo idêntico.

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

Mapeamentos da rotina de texto genérico

TCHAR.H Rotina _UNICODE&_MBCS não definido _MBCS Definido _UNICODE Definido
_stscanf_s sscanf_s sscanf_s swscanf_s
_stscanf_s_l _sscanf_s_l _sscanf_s_l _swscanf_s_l

Requisitos

Rotina Cabeçalho necessário
sscanf_s, _sscanf_s_l <stdio.h>
swscanf_s, _swscanf_s_l <stdio.h> ou <wchar.h>

Para obter mais informações sobre compatibilidade, consulte Compatibilidade.

Exemplo

// crt_sscanf_s.c
// This program uses sscanf_s to read data items
// from a string named tokenstring, then displays them.

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

int main( void )
{
   char  tokenstring[] = "15 12 14...";
   char  s[81];
   char  c;
   int   i;
   float fp;

   // Input various data from tokenstring:
   // max 80 character string plus null terminator
   sscanf_s( tokenstring, "%s", s, (unsigned)_countof(s) );
   sscanf_s( tokenstring, "%c", &c, (unsigned)sizeof(char) );
   sscanf_s( tokenstring, "%d", &i );
   sscanf_s( tokenstring, "%f", &fp );

   // Output the data read
   printf_s( "String    = %s\n", s );
   printf_s( "Character = %c\n", c );
   printf_s( "Integer:  = %d\n", i );
   printf_s( "Real:     = %f\n", fp );
}
String    = 15
Character = 1
Integer:  = 15
Real:     = 15.000000

Confira também

E/S de fluxo
fscanf, _fscanf_l, fwscanf, _fwscanf_l
scanf, _scanf_l, wscanf, _wscanf_l
sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
snprintf, _snprintf, _snprintf_l, _snwprintf, _snwprintf_l