freopen_s、_wfreopen_s

發行項
06/09/2015

重新指派檔案指標。 fopen,_wfopen 的這些版本有安全性增強功能，如 CRT 中的安全性功能中所述。

errno_t freopen( 
   FILE** pFile,
   const char *path,
   const char *mode,
   FILE *stream 
);
errno_t _wfreopen( 
   FILE** pFile,
   const wchar_t *path,
   const wchar_t *mode,
   FILE *stream 
);

參數

[out] pFile
指向由呼叫提供的檔案指標之指標。
[in] path
新的檔案路徑。
[in] mode
允許存取的型別。
[in] stream
指向 FILE 結構的指標。

傳回值

這些函式都會傳回錯誤碼。如果發生錯誤，原始檔案已關閉。

備註

freopen_s 函式會關閉目前與 stream 相關聯的檔案並重新指派 stream 到 path. 指定的檔案。_wfreopen_s 是 _freopen_s 的寬字元版本；_wfreopen_s 的 path 和 mode 參數為寬字元字串。 _wfreopen_s 和 _freopen_s 其餘行為相同。

如果任何 pFile、path、mode 或 stream 為 NULL，或者如果 path 為一空字串，則這些函式會觸發無效參數處理常式，如參數驗證中所述。如果允許繼續執行，這些函式會將 errno 設定為 EINVAL 並傳回 EINVAL。

一般文字常式對應

TCHAR.H 常式	未定義 _UNICODE & _MBCS	已定義 _MBCS	已定義 _UNICODE
_tfreopen_s	freopen_s	freopen_s	_wfreopen_s

freopen_s 通常用來將目前開啟的檔案 stdin、 stdout和 stderr 重新導向至使用者指定的檔案。與 stream 相關聯的新檔案將與 mode 一起開啟，其是指定檔案要求的存取類型的字串，如下：

"r"
開啟以讀取。如果檔案不存在或找不到，freopen_s 呼叫就會失敗。
"w"
開啟空白檔案以寫入。如果指定的檔案已存在，其內容將被終結。
"a"
開啟以撰寫在檔案結束時 (附加)，將新資料加入檔案之前沒有移除 EOF 標記；如果檔案不存在，則會先建立檔案。
"r+"
開啟以進行讀取和寫入。(檔案必須存在。)
"w+"
開啟空白檔案以進行讀取和寫入。如果指定的檔案已存在，其內容將被終結。
"a+"
開啟檔案以讀取和附加；附加作業包括在新資料寫入檔案之前移除 EOF 標記，且在寫入完成後還原 EOF 標記；如果檔案不存在則會先建立檔案。

請使用 "w" 和 "w+" 型別請注意，它們可以終結現有檔案。

使用 "a" 或 "a+" 存取類型開啟檔案時，所有寫入作業都會在檔案結尾進行。雖然檔案指標可以使用 fseek 或 rewind 重新調整位置，但是在執行任何寫入作業之前，檔案指標永遠會移回至檔案結尾。因此，無法覆寫現有資料。

在附加到檔案之前，"a" 模式不會移除 EOF 標記。進行附加之後，MS-DOS TYPE 命令只顯示到原始 EOF 標記為止的資料，任何附加至檔案的資料都不會出現。 "a+" 模式會在附加到檔案之前移除 EOF 標記。附加之後，MS-DOS TYPE 命令會顯示檔案中的所有資料。附加至以 CTRL+Z EOF 標記終止的資料流檔案時，需要使用 "a+" 模式。

指定 "r+",、"w+", 或 "a+" 存取類型時，同時允許讀取和寫入 (表示檔案是要開啟以供「更新」之用)。然而，當您在讀取和寫入之間切換時，必定會有干擾的 fsetpos、 fseek或回溯作業。如果需要，目前位置可以為 fsetpos 或 fseek 作業指定。除了上述值之外，下列其中一個字元可能包含在 mode 字串，以為新行指定平移模式。

t
以文字 (平移) 模式開啟；歸位字元與換行字元組合會在輸入時轉譯成單一換行字元，而換行字元會在輸出時轉譯成歸位字元與換行字元組合。此外， CTRL+Z 將解譯成輸入的檔案結尾字元。在開啟用來撰寫或讀取並且以 "a+" 讀取的檔案，執行階段程式庫檢查檔案結尾是否有 CTRL+Z，若有則移除它。之所以這樣做，是因為使用 fseek 和 ftell 在以 CTRL+Z 結束的檔案內移動可能會讓 fseek 在檔案結尾附近產生不正確的行為。 t 選項為 Microsoft 擴充功能，不可在需要 ANSI 可攜性的時候使用。
b
以二進位 (未轉譯的) 模式開啟；上述轉譯會隱藏。

如果 mode 中未指定 t 或 b，則預設轉譯模式由全域變數 _fmode 定義。如果引數前置 t 或 b，則函式失敗並傳回 NULL。

如需文字和二進位模式的討論，請參閱文字和二進位模式檔案 I/O。

需求

Function	必要的標頭
freopen_s	<stdio.h>
_wfreopen_s	<stdio.h> 或 <wchar.h>

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

範例

// crt_freopen_s.c
// This program reassigns stderr to the file
// named FREOPEN.OUT and writes a line to that file.
 
#include <stdio.h>
#include <stdlib.h>

FILE *stream;

int main( void )
{
   errno_t err;
   // Reassign "stderr" to "freopen.out": 
   err = freopen_s( &stream, "freopen.out", "w", stderr );

   if( err != 0 )
      fprintf( stdout, "error on freopen\n" );
   else
   {
      fprintf( stdout, "successfully reassigned\n" ); fflush( stdout );
      fprintf( stream, "This will go to the file 'freopen.out'\n" );
      fclose( stream );
   }
   system( "type freopen.out" );
}