sscanf_s、_sscanf_s_l、swscanf_s、_swscanf_s_l

發行項
06/09/2015

從字串讀取格式化的資料。這些 sscanf、_sscanf_l、swscanf、_swscanf_l 版本有安全性增強功能，如 CRT 中的安全性功能中所述。

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 ] ...
);

參數

buffer
預存資料
format
格式控制字串。如需詳細資訊，請參閱格式規格欄位：scanf 和 wscanf 函式。
argument
選擇性引數
locale
要使用的地區設定。

傳回值

每個這些函式都會傳回成功轉換和指派的欄位數；傳回值不包括已讀取但未指派的欄位。傳回值 0 表示未指定欄位。如果發生錯誤，或者在第一個轉換前就已經到達字串結尾，則傳回值是 EOF。

如果 buffer 或 format 為 NULL 指標，則叫用無效參數處理常式，如參數驗證中所述。如果允許繼續執行，這些函式會傳回 -1 並將errno 設定為 EINVAL

如需有關這些錯誤碼及其他錯誤碼的詳細資訊，請參閱 errno、_doserrno、_sys_errlist 和 _sys_nerr。

備註

sscanf_s 函式會將 buffer 的資料寫入 argument指定的位置。在格式字串後的引數會指定變數的指標，這些變數的類型對應至 format 的類型規範。不同於較不安全版本 sscanf，當您使用類型欄位字元 c、C、s、S 或用 [] 括住的字串控制項集合時，需要緩衝區大小參數。緩衝區大小 (以字元為單位) 必須當做在需要它的每個緩衝區參數之後的額外參數提供。例如，如果您讀取字串，該字串的緩衝區大小將如下所示:

wchar_t ws[10];

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

緩衝區大小包括終止 null。寬度規格欄位可用來確保讀入的語彙基元會放入緩衝區。如果沒有使用寬度規格欄位，而且讀入的語彙基元太大而無法放入緩衝區中，則沒有任何資料寫入該緩衝區。

在字元的情況下，單一字元可能看起來如下:

wchar_t wc;

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

這個範例以寬字元緩衝區讀取輸入字串的單一字元並儲存它。當你讀取非 null 結尾字串時，不帶正負號的整數會被用於寬度和大小的訂定。

char c[4];

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

如需詳細資訊，請參閱scanf_s、_scanf_s_l、wscanf_s、_wscanf_s_l與scanf 類型欄位字元。

注意事項
大小參數的類型是 unsigned，不是 size_t。

format 引數控制輸入欄位的解譯，而且在形式和功能上與 scanf_s 函式的 format 引數相同。如果在重疊的字串之間執行複製，則行為是未定義的。

swscanf_s 是 sscanf_s; 的寬字元版本；swscanf_s 的引數是寬字元字串。 sscanf_s 不會處理多位元組十六位元字元。 swscanf_s 不會處理 Unicode 全形十六位元或「相容性區域」字元。否則 swscanf_s 和 sscanf_s 的行為相同。

這些有 _l 尾碼的函式版本是一樣的，不同之處在於它們會使用傳入的地區設定，而不使用目前的執行緒地區設定。

一般文字常式對應

TCHAR.H 常式	未定義 _UNICODE & _MBCS	已定義 _MBCS	已定義 _UNICODE
_stscanf_s	sscanf_s	sscanf_s	swscanf_s
_stscanf_s_l	_sscanf_s_l	_sscanf_s_l	_swscanf_s_l

需求

常式	必要的標頭
sscanf_s, _sscanf_s_l	<stdio.h>
swscanf_s, _swscanf_s_l	<stdio.h> 或 <wchar.h>

如需其他相容性資訊，請參閱相容性。

範例

// 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, _countof(s) );
   sscanf_s( tokenstring, "%c", &c, 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 );
}