scanf_s、_scanf_s_l、wscanf_s、_wscanf_s_l

發行項
06/09/2015

從標準輸入資料流讀取格式化的資料。這些 scanf、_scanf_l、wscanf、_wscanf_l 版本有安全性增強功能，如 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]... 
);

參數

format
格式控制字串。
argument
選擇性引數。
locale
使用的地區設定。

傳回值

傳回成功轉換和指定的欄位數；傳回值不包括讀取但未指定的欄位。傳回值 0 表示未指定欄位。如果發生錯誤，或者在第一次嘗試讀取字元時遇到檔案結尾字元或字串結尾字元，傳回值是 EOF。如果 format 為 NULL 指標，則叫用無效參數處理常式，如參數驗證中所述。如果允許繼續執行，則 scanf_s 和 wscanf_s 會傳回 EOF，並將 errno 設定為 EINVAL。

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

備註

scanf_s 函式會從標準輸入資料流 stdin 讀取資料並將資料寫入 argument 引數所指定的位置。清單中的所有 argument 都必須是變數的指標，這些變數的類型對應至 format 的類型規範。如果在重疊的字串之間執行複製，則行為是未定義的。

wscanf_s 是 scanf_s 的寬字元版本。 wscanf_s 的 format 引數是寬字元字串。如果資料流是以 ANSI 模式開啟，則 wscanf_s 和 scanf_s 的行為相同。 scanf_s 目前不支援從 UNICODE 資料流輸入。

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

不同於 scanf 和 wscanf，scanf_s 和 wscanf_s 要求類型 c、C、s、S 的所有輸入參數或用 [] 括住的字串控制項集合，必須指定緩衝區大小。緩衝區大小 (以字元為單位) 當做緩衝區或變數指標後的額外參數傳遞。例如，如果您讀取字串，該字串的緩衝區大小將如下所示:

char s[10];

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

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

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

下列範例會說明，緩衝區大小的參數描述最大字元數，而不是位元組。在呼叫 wscanf_s時，由緩衝區型別表示的字元寬度不符合由格式指定名稱所對應的字元寬度。

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

S 格式規範表示為對被函式預設寬度來說「相反」的字元寬度使用。字元寬度是單一位元組，不過函式支援雙位元組字元。這個範例讀入 9 個單一位元組字元字串並將它們放入雙位元組字串緩衝中。字元被視為單一位元組值;前兩個字元儲存在 ws[0] 中，後兩個儲存在ws[1]中，依此類推。

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

char c;

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

當非 null 結尾字串讀取時，整數型別會被用於寬度和大小的訂定。

char c[4];

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

如需詳細資訊，請參閱scanf 寬度規格。

一般文字常式對應

TCHAR.H 常式	未定義 _UNICODE & _MBCS	已定義 _MBCS	已定義 _UNICODE
_tscanf_s	scanf_s	scanf_s	wscanf_s
_tscanf_s_l	_scanf_s_l	_scanf_s_l	_wscanf_s_l

如需詳細資訊，請參閱格式規格欄位：scanf 和 wscanf 函式。

需求

常式	必要的標頭
scanf_s, _scanf_s_l	<stdio.h>
wscanf_s, _wscanf_s_l	<stdio.h> 或 <wchar.h>

Windows 市集應用程式不支援主控台。與主控台關聯的標準資料流控制代碼 (stdin、stdout 和 stderr) 必須重新導向，然後 C 執行階段函式才能在 Windows 市集應用程式中使用它們。如需其他相容性資訊，請參閱相容性。

範例

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

在此程式輸入會產生下列輸出:

71 98.6 h z Byte characters

36 92.3 y n Wide characters