CreateFileW 函式（fileapi.h）

發行項
06/27/2024

建立或開啟檔案或 I/O 裝置。最常使用的 I/O 裝置如下：檔案、檔案數據流、目錄、實體磁碟、磁碟區、控制台緩衝區、磁帶機、通訊資源、mailslot 和管道。函式會傳回句柄，根據檔案或裝置以及指定的旗標和屬性，可用來存取各種 I/O 類型的檔案或裝置。

若要以交易作業的形式執行此作業，這會導致可用於交易 I/O 的句柄，請使用 CreateFileTransacted 函式。

語法

HANDLE CreateFileW(
  [in]           LPCWSTR               lpFileName,
  [in]           DWORD                 dwDesiredAccess,
  [in]           DWORD                 dwShareMode,
  [in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  [in]           DWORD                 dwCreationDisposition,
  [in]           DWORD                 dwFlagsAndAttributes,
  [in, optional] HANDLE                hTemplateFile
);

參數

[in] lpFileName

要建立或開啟的檔案或裝置名稱。您可以使用此名稱中的正斜線（/）或反斜杠（\）。

如需特殊裝置名稱的相關信息，請參閱定義 MS-DOS 裝置名稱。

若要建立檔案數據流，請指定檔名、冒號，然後指定數據流的名稱。如需詳細資訊，請參閱檔案資料流。

根據預設，名稱限製為MAX_PATH個字元。若要將此限制延伸至 32,767 寬字元，請在路徑前面加上 “\\？\”。如需詳細資訊，請參閱命名檔案、路徑和命名空間。

提示

從 Windows 10 版本 1607 開始，您可以選擇移除MAX_PATH限制，而不需預先加上 “\\？\”。如需詳細資訊，請參閱命名檔案、路徑和命名空間的一節。

[in] dwDesiredAccess

要求的檔案或裝置存取權，可摘要為讀取、寫入或兩者皆非零）。

最常使用的值是 GENERIC_READ、GENERIC_WRITE或兩者（GENERIC_READ | GENERIC_WRITE）。如需詳細資訊，請參閱一般訪問許可權、檔案安全性和訪問許可權、檔案訪問許可權常數和 ACCESS_MASK。

如果此參數為零，應用程式可以查詢某些元數據，例如檔案、目錄或裝置屬性，而不需要存取該檔案或裝置，即使 GENERIC_READ 存取也遭到拒絕。

您無法要求與已開啟句柄之開啟要求中 dwShareMode 參數所指定的共用模式衝突的存取模式。

如需詳細資訊，請參閱本主題的一節，並建立和開啟檔案。

[in] dwShareMode

檔案或裝置的要求共用模式，可以是讀取、寫入、刪除、所有這些或無（請參閱下表）。存取屬性或擴充屬性的要求不會受到這個旗標的影響。

如果此參數為零且 CreateFile 成功，則檔案或裝置無法共用，而且在關閉檔案或裝置的句柄之前，無法再次開啟。如需詳細資訊，請參閱一節。

您無法要求與現有要求中具有開啟句柄之存取模式衝突的共用模式。 CreateFile 會失敗，而且 getLastError 函式會傳回 ERROR_SHARING_VIOLATION。

若要讓進程在開啟檔案或裝置時共用檔案或裝置，請使用下列一或多個值的相容組合。如需此參數與 dwDesiredAccess 參數之有效組合的詳細資訊，請參閱建立和開啟檔案。

附註不論進程內容為何，每個開啟句柄的共用選項都會維持有效狀態，直到該句柄關閉為止。

價值	意義
0 0x00000000	如果檔案或裝置要求刪除、讀取或寫入存取，則防止後續的開啟作業。
FILE_SHARE_DELETE 0x00000004	啟用檔案或裝置上的後續開啟作業，以要求刪除存取權。否則，如果檔案或裝置要求刪除存取權，則無法開啟檔案或裝置。如果未指定此旗標，但檔案或裝置已開啟以進行刪除存取，則函式會失敗。注意刪除存取權允許刪除和重新命名作業。
FILE_SHARE_READ 0x00000001	啟用檔案或裝置上的後續開啟作業，以要求讀取存取權。否則，如果檔案或裝置要求讀取許可權，則無法開啟檔案或裝置。如果未指定此旗標，但檔案或裝置已開啟以供讀取存取，則函式會失敗。
FILE_SHARE_WRITE 0x00000002	啟用檔案或裝置上的後續開啟作業，以要求寫入存取權。否則，如果檔案或裝置要求寫入存取權，則無法開啟檔案或裝置。如果未指定此旗標，但檔案或裝置已開啟以進行寫入存取，或具有寫入存取權的檔案對應，則函式會失敗。

[in, optional] lpSecurityAttributes

包含兩個不同但相關數據成員之 SECURITY_ATTRIBUTES 結構的指標：選擇性的安全性描述元，以及一個布爾值，決定傳回的句柄是否可以由子進程繼承。

此參數可以是 NULL。

如果此參數 NULL，則應用程式可建立的任何子進程無法繼承 CreateFile 所傳回的句柄，且與傳回句柄相關聯的檔案或裝置會取得預設的安全性描述元。

lpSecurityDescriptor 結構的成員會指定檔案或裝置的 SECURITY_DESCRIPTOR。如果這個成員 NULL，則與傳回句柄相關聯的檔案或裝置會指派預設的安全性描述元。

CreateFile 會忽略開啟現有檔案或裝置時 lpSecurityDescriptor 成員，但會繼續使用 bInheritHandle 成員。

bInheritHandle 結構的成員會指定是否可以繼承傳回的句柄。

如需詳細資訊，請參閱一節。

[in] dwCreationDisposition

針對存在或不存在的檔案或裝置採取動作。

對於檔案以外的裝置，此參數通常會設定為 OPEN_EXISTING。

如需詳細資訊，請參閱一節。

此參數必須是下列其中一個值，無法合併：

價值	意義
CREATE_ALWAYS 2	一律建立新的檔案。如果指定的檔案存在且可寫入，則函式會截斷檔案、函式成功，而最後的錯誤碼會設定為 ERROR_ALREADY_EXISTS （183）。如果指定的檔案不存在且為有效的路徑，則會建立新的檔案、函式成功，並將最後一個錯誤碼設定為零。如需詳細資訊，請參閱本主題的一節。
CREATE_NEW 1	只有在新檔案不存在時，才會建立新的檔案。如果指定的檔案存在，函式會失敗，且最後一個錯誤碼會設定為 ERROR_FILE_EXISTS （80）。如果指定的檔案不存在，而且是可寫入位置的有效路徑，則會建立新的檔案。
OPEN_ALWAYS 4	一律開啟檔案。如果指定的檔案存在，函式會成功，且最後一個錯誤碼會設定為 ERROR_ALREADY_EXISTS （183）。如果指定的檔案不存在，而且是可寫入位置的有效路徑，則函式會建立檔案，並將最後一個錯誤碼設定為零。
OPEN_EXISTING 3	只有在檔案存在時，才開啟檔案或裝置。如果指定的檔案或裝置不存在，函式會失敗，且最後一個錯誤碼會設定為 ERROR_FILE_NOT_FOUND （2）。如需裝置的詳細資訊，請參閱一節。
TRUNCATE_EXISTING 5	開啟檔案並截斷它，使其大小為零位元組，只有當它存在時。如果指定的檔案不存在，函式會失敗，且最後一個錯誤碼會設定為 ERROR_FILE_NOT_FOUND （2）。呼叫進程必須開啟檔案，並將 GENERIC_WRITE 位設定為 dwDesiredAccess 參數的一部分。

[in] dwFlagsAndAttributes

檔案或裝置屬性和旗標，FILE_ATTRIBUTE_NORMAL 是檔案最常見的預設值。

此參數可以包含可用檔案屬性的任何組合（FILE_ATTRIBUTE_*）。所有其他檔案屬性都會覆寫 FILE_ATTRIBUTE_NORMAL。

此參數也可以包含旗標的組合（FILE_FLAG_），以控制檔案或裝置快取行為、存取模式和其他特殊用途旗標。這些會與任何 FILE_ATTRIBUTE_ 值結合。

此參數也可以藉由指定 SECURITY_SQOS_PRESENT 旗標來包含安全性服務品質（SQOS）資訊。其他 SQOS 相關旗標資訊會顯示在屬性和旗標數據表之後的表格中。

注意：CreateFile 開啟現有的檔案時，通常會將檔案旗標與現有檔案的檔案屬性合併，並忽略 dwFlagsAndAttributes中提供的任何檔案屬性。建立和開啟檔案中詳述特殊案例。

下列某些檔案屬性和旗標只能套用至檔案，而且不一定適用於所有其他類型的裝置，CreateFile 可以開啟。如需詳細資訊，請參閱本主題的一節，並建立和開啟檔案。

如需檔案屬性的進階存取，請參閱 SetFileAttributes。如需具有其值和描述之所有檔案屬性的完整清單，請參閱 File Attribute Constants。

屬性	意義
FILE_ATTRIBUTE_ARCHIVE 32 （0x20）	檔案應該封存。應用程式會使用此屬性來標記檔案以進行備份或移除。
FILE_ATTRIBUTE_ENCRYPTED 16384 （0x4000）	檔案或目錄已加密。對於檔案，這表示檔案中的所有數據都會加密。對於目錄，這表示加密是新建立檔案和子目錄的預設值。如需詳細資訊，請參閱檔案加密。如果同時指定 FILE_ATTRIBUTE_SYSTEM，這個旗標就不會有任何作用。家用版、家用版、入門版或ARM版本的Windows不支援此旗標。
FILE_ATTRIBUTE_HIDDEN 2 （0x2）	檔案已隱藏。請勿將其包含在一般目錄清單中。
FILE_ATTRIBUTE_NORMAL 128 （0x80）	檔案沒有設定其他屬性。此屬性只有在單獨使用時才有效。
FILE_ATTRIBUTE_OFFLINE 4096 （0x1000）	檔案的數據無法立即取得。這個屬性表示檔案數據會實際移至離線記憶體。遠端記憶體是階層式記憶體管理軟體，使用這個屬性。應用程式不應該任意變更此屬性。
FILE_ATTRIBUTE_READONLY 1 （0x1）	檔案是唯讀的。應用程式可以讀取檔案，但無法寫入或刪除檔案。
FILE_ATTRIBUTE_SYSTEM 4 （0x4）	檔案是操作系統獨佔或獨佔使用的一部分。
FILE_ATTRIBUTE_TEMPORARY 256 （0x100）	檔案正用於暫存記憶體。如需詳細資訊，請參閱本主題的快取行為一節。

旗	意義
FILE_FLAG_BACKUP_SEMANTICS 0x02000000	檔案正在開啟或建立以進行備份或還原作業。當進程具有 SE_BACKUP_NAME 和 SE_RESTORE_NAME 許可權時，系統可確保呼叫進程會覆寫檔案安全性檢查。如需詳細資訊，請參閱在令牌中變更許可權。您必須設定此旗標，才能取得目錄的句柄。目錄句柄可以傳遞至某些函式，而不是檔案句柄。如需詳細資訊，請參閱一節。
FILE_FLAG_DELETE_ON_CLOSE 0x04000000	檔案會在關閉所有句柄之後立即刪除，其中包括指定的句柄，以及任何其他開啟或重複的句柄。如果檔案有現有的開啟句柄，除非呼叫全都以 FILE_SHARE_DELETE 共用模式開啟，否則呼叫會失敗。除非指定 FILE_SHARE_DELETE 共用模式，否則檔案的後續開啟要求會失敗。
FILE_FLAG_NO_BUFFERING 0x20000000	檔案或裝置正在開啟，且沒有數據讀取和寫入的系統快取。此旗標不會影響硬碟快取或記憶體對應檔案。使用 FILE_FLAG_NO_BUFFERING 旗標成功使用 CreateFile 開啟的檔案有嚴格的需求，如需詳細資訊，請參閱檔案緩衝處理。
FILE_FLAG_OPEN_NO_RECALL 0x00100000	要求檔案數據，但應該會繼續位於遠端記憶體中。它不應該傳輸回本機記憶體。此旗標可供遠端儲存系統使用。
FILE_FLAG_OPEN_REPARSE_POINT 0x00200000	一般重新分析點處理不會發生;CreateFile 會嘗試開啟重新分析點。開啟檔案時，會傳回檔句柄，不論控制重新分析點的篩選是否正常運作。此旗標不能與 CREATE_ALWAYS 旗標搭配使用。如果檔案不是重新分析點，則會忽略此旗標。如需詳細資訊，請參閱一節。
FILE_FLAG_OVERLAPPED 0x40000000	檔案或裝置正在針對異步 I/O 開啟或建立。在此句柄上完成後續的 I/O 作業時，重疊結構中指定的事件將會設定為訊號狀態。如果指定此旗標，則檔案可用於同時讀取和寫入作業。如果未指定此旗標，則即使讀取和寫入函式的呼叫指定了重疊結構，I/O 作業也會串行化。如需使用此旗標建立之檔句柄時考慮的資訊，請參閱本主題的同步和異步 I/O 句柄一節。
FILE_FLAG_POSIX_SEMANTICS 0x01000000	存取會根據 POSIX 規則進行。這包括允許多個具有名稱的檔案，只有在支援該命名的文件系統時才有所不同。使用此選項時請小心，因為針對 MS-DOS 或16位 Windows 所撰寫的應用程式可能無法存取以這個旗標建立的檔案。
FILE_FLAG_RANDOM_ACCESS 0x10000000	存取權是隨機的。系統可以使用此功能作為優化檔案快取的提示。如果文件系統不支援快取的 I/O，且 FILE_FLAG_NO_BUFFERING，這個旗標就沒有作用。如需詳細資訊，請參閱本主題的快取行為一節。
FILE_FLAG_SESSION_AWARE 0x00800000	檔案或裝置正以會話感知開啟。如果未指定此旗標，則會話 0 中執行的處理程式無法開啟個別會話裝置（例如使用 RemoteFX USB 重新導向的裝置）。此旗標對不在會話 0 中的呼叫端沒有任何作用。只有伺服器版本的 Windows 才支援此旗標。 Windows Server 2008 R2 和 Windows Server 2008：Windows Server 2012 之前不支援此旗標。
FILE_FLAG_SEQUENTIAL_SCAN 0x08000000	存取的目的是要從頭到尾循序。系統可以使用此功能作為優化檔案快取的提示。如果使用讀取後置（也就是反向掃描），則不應該使用此旗標。如果文件系統不支援快取的 I/O，且 FILE_FLAG_NO_BUFFERING，這個旗標就沒有作用。如需詳細資訊，請參閱本主題的快取行為一節。
FILE_FLAG_WRITE_THROUGH 0x80000000	寫入作業不會經歷任何中繼快取，它們會直接移至磁碟。如需詳細資訊，請參閱本主題的快取行為一節。

dwFlagsAndAttributes 參數也可以指定 SQOS 資訊。如需詳細資訊，請參閱模擬層級。當呼叫的應用程式將 SECURITY_SQOS_PRESENT 旗標指定為 dwFlagsAndAttributes的一部分時，它也可以包含下列一或多個值。

安全性旗標	意義
SECURITY_ANONYMOUS	模擬匿名模擬層級的用戶端。
SECURITY_CONTEXT_TRACKING	安全性追蹤模式是動態的。如果未指定此旗標，則安全性追蹤模式是靜態的。
SECURITY_DELEGATION	模擬委派模擬層級的用戶端。
SECURITY_EFFECTIVE_ONLY	伺服器只能使用用戶端安全性內容的啟用層面。如果您未指定此旗標，則可以使用用戶端安全性內容的所有層面。這可讓用戶端限制伺服器在模擬用戶端時可以使用的群組和許可權。
SECURITY_IDENTIFICATION	模擬識別模擬層級的用戶端。
SECURITY_IMPERSONATION	模擬模擬層級的用戶端。如果沒有指定其他旗標以及 SECURITY_SQOS_PRESENT 旗標，則這是預設行為。

[in, optional] hTemplateFile

具有 GENERIC_READ 訪問許可權之範本檔案的有效句柄。範本檔案會提供所建立檔案的檔案屬性和擴充屬性。

此參數可以是 NULL。

開啟現有的檔案時，CreateFile 會忽略此參數。

開啟新的加密檔案時，檔案會從其父目錄繼承任意訪問控制清單。如需詳細資訊，請參閱檔案加密。

傳回值

如果函式成功，傳回值就是指定檔案、裝置、命名管道或郵件位置的開啟句柄。

如果函式失敗，傳回值會 INVALID_HANDLE_VALUE。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

言論

CreateFile 最初是專為檔案互動而開發，但此後已擴充並增強，以包含 Windows 開發人員可用的大部分其他類型的 I/O 裝置和機制。本節會嘗試涵蓋開發人員在不同內容和不同 I/O 類型中使用 CreateFile 時可能會遇到的各種問題。只有在特別參考儲存在文件系統上實際檔案中的數據時，文字才會嘗試使用檔案一詞。不過，某些使用檔案可能會更普遍地參考支援類似檔案機制的 I/O 物件。由於先前提及的歷史原因，這種自由使用檔案一詞在常數名稱和參數名稱中特別普遍。

當應用程式使用 createFile傳回的物件句柄完成時，請使用 CloseHandle 函式來關閉句柄。這不僅釋放了系統資源，而且可以更廣泛地影響共用檔案或裝置，並將數據認可至磁碟等專案。本主題中會適當地指出細節。

Windows Server 2003 和 Windows XP：如果嘗試開啟檔案或目錄以在遠端電腦上刪除檔案或目錄，嘗試在遠端電腦上開啟檔案或目錄時，dwDesiredAccess 參數是 DELETE 存取旗標（0x00010000） OR'ed with other access flag，和遠端檔案或目錄尚未使用 FILE_SHARE_DELETE開啟。若要避免在此案例中發生共享違規，請使用 DELETE 訪問許可權開啟遠端檔案或目錄，或呼叫 DeleteFile，而不先開啟檔案或目錄進行刪除。

某些文件系統，例如 NTFS 檔案系統，支援個別檔案和目錄的壓縮或加密。在具有此支援之掛接文件系統的磁碟區上，新的檔案會繼承其目錄的壓縮和加密屬性。

您無法使用 CreateFile 來控制檔案或目錄上的壓縮、解壓縮或解密。如需詳細資訊，請參閱建立和開啟檔案、檔案壓縮和解壓縮，以及檔案加密。

Windows Server 2003 和 Windows XP：基於回溯相容性目的，當您在 lpSecurityAttributes中指定安全性描述元時，CreateFile 不會套用繼承規則。為了支持繼承，稍後查詢此檔案之安全性描述元的函式可能會啟發式判斷並報告繼承是否有效。如需詳細資訊，請參閱自動傳播可繼承的 ACE。

如先前所述，如果 lpSecurityAttributes 參數 NULL，則 CreateFi le 所傳回的句柄無法由應用程式建立的任何子進程繼承。此參數的下列資訊也適用：

如果 bInheritHandle 成員變數未 FALSE，這是任何非零值，則可以繼承句柄。因此，如果您不想要繼承句柄，請務必正確初始化此結構成員，以 FALSE。
檔案或目錄的預設安全性描述元中的訪問控制清單（ACL）會繼承自其父目錄。
目標文件系統必須支援 lpSecurityDescriptor 成員對檔案和目錄的安全性，才能對其產生影響，這可以使用 GetVolumeInformation來決定。

在 Windows 8 和 Windows Server 2012 中，下列技術支援此功能。

科技	支援
伺服器消息塊（SMB） 3.0 通訊協定	是的
SMB 3.0 透明故障轉移（TFO）	請參閱備註
具有向外延展檔案共用的SMB 3.0（SO）	請參閱備註
叢集共用磁碟區檔案系統（CsvFS）	是的
復原檔案系統（ReFS）	是的

請注意，如果已開啟替代數據流的檔案上執行，CreateFile 取代處置將會失敗。

符號連結行為

如果呼叫此函式會建立檔案，則行為不會有任何變更。此外，請考慮下列有關 FILE_FLAG_OPEN_REPARSE_POINT的資訊：

如果指定 FILE_FLAG_OPEN_REPARSE_POINT：
- 如果已開啟現有的檔案，而且它是符號連結，傳回的句柄就是符號連結的句柄。
- 如果指定 TRUNCATE_EXISTING 或 FILE_FLAG_DELETE_ON_CLOSE，受影響的檔案就是符號連結。
如果未指定 FILE_FLAG_OPEN_REPARSE_POINT：
- 如果已開啟現有的檔案，而且它是符號連結，則傳回的句柄是目標的句柄。
- 如果指定 CREATE_ALWAYS、TRUNCATE_EXISTING或 FILE_FLAG_DELETE_ON_CLOSE，受影響的檔案就是目標。

快取行為

CreateFile 會使用 dwFlagsAndAttributes 參數的數個可能值來控制或影響系統快取與句柄相關聯的數據。它們是：

FILE_FLAG_NO_BUFFERING
FILE_FLAG_RANDOM_ACCESS
FILE_FLAG_SEQUENTIAL_SCAN
FILE_FLAG_WRITE_THROUGH
FILE_ATTRIBUTE_TEMPORARY

如果未指定這些旗標，系統就會使用預設的一般用途快取配置。否則，系統快取的行為會如同針對每個旗標所指定。

其中一些旗標不應該合併。例如，結合 FILE_FLAG_RANDOM_ACCESS 與 FILE_FLAG_SEQUENTIAL_SCAN 是自我失敗。

指定 FILE_FLAG_SEQUENTIAL_SCAN 旗標可以提升使用循序存取讀取大型檔案的應用程式效能。對於大部分循序讀取大型檔案的應用程式，效能提升可能更為明顯，但偶爾會略過少量位元組範圍。如果應用程式移動檔案指標進行隨機存取，則最可能不會發生最佳快取效能。不過，仍會保證正確的作業。

旗標 FILE_FLAG_WRITE_THROUGH 和 FILE_FLAG_NO_BUFFERING 是獨立的，而且可以合併。

如果使用 FILE_FLAG_WRITE_THROUGH 但未同時指定 FILE_FLAG_NO_BUFFERING，讓系統快取生效，則數據會寫入系統快取，但不會延遲地排清到磁碟。

如果同時指定 FILE_FLAG_WRITE_THROUGH 和 FILE_FLAG_NO_BUFFERING，讓系統快取沒有作用，則數據會立即排清到磁碟，而不會通過 Windows 系統快取。操作系統也會要求硬碟本機硬體快取的寫入至永續性媒體。

注意並非所有硬碟硬體都支援此寫入功能。

正確使用 FILE_FLAG_NO_BUFFERING 旗標需要特殊的應用程序考慮。如需詳細資訊，請參閱檔案緩衝。

透過 FILE_FLAG_WRITE_THROUGH 的寫入要求也會導致 NTFS 排清任何元數據變更，例如時間戳更新或重新命名作業，因為處理要求。因此，FILE_FLAG_WRITE_THROUGH 旗標通常會與 FILE_FLAG_NO_BUFFERING 旗標搭配使用，以取代每次寫入之後呼叫 FlushFileBuffers 函式，這可能會導致不必要的效能損失。將這些旗標一起使用可避免這些懲罰。如需快取檔案和元數據的一般資訊，請參閱檔案快取。

當 FILE_FLAG_NO_BUFFERING 與 FILE_FLAG_OVERLAPPED結合時，旗標會提供最大的異步效能，因為 I/O 不會依賴記憶體管理員的同步作業。不過，某些 I/O 作業需要更多時間，因為數據不會保留在快取中。此外，檔案元數據可能仍會快取（例如，建立空白檔案時）。若要確保元數據已排清到磁碟，請使用 flushFileBuffers 函式。

指定 FILE_ATTRIBUTE_TEMPORARY 屬性會導致檔案系統避免在有足夠的快取記憶體可用時將數據寫回大量記憶體，因為應用程式會在句柄關閉后刪除暫存盤。在此情況下，系統完全可以避免寫入數據。雖然它不會以與先前提到的旗標相同的方式直接控制數據快取，但 FILE_ATTRIBUTE_TEMPORARY 屬性確實會告知系統在不寫入的情況下，盡可能在系統快取中保存，因此可能會對某些應用程式感到擔憂。

檔案

如果您重新命名或刪除檔案，然後在不久之後加以還原，系統會搜尋快取以取得要還原的檔案資訊。快取的資訊包含其簡短/長名稱組和建立時間。

如果您在擱置刪除的檔案上呼叫 CreateFile，因為先前呼叫 deleteFile，則函式會失敗。操作系統會延遲刪除檔案，直到檔案的所有句柄都關閉為止。 GetLastError 會傳回 ERROR_ACCESS_DENIED。

dwDesiredAccess 參數可以是零，可讓應用程式在沒有存取檔案的情況下查詢檔案屬性，如果應用程式執行時具有足夠的安全性設定。這適用於測試檔案是否存在，而不需開啟檔案以進行讀取和/或寫入存取，或取得檔案或目錄的其他統計數據。請參閱取得和設定檔案資訊和 GetFileInformationByHandle。

如果指定了 CREATE_ALWAYS 和 FILE_ATTRIBUTE_NORMAL，CreateFile 會失敗，並在檔案存在且具有 FILE_ATTRIBUTE_HIDDEN 或 FILE_ATTRIBUTE_SYSTEM 屬性時，將最後一個錯誤設定為 ERROR_ACCESS_DENIED。若要避免錯誤，請指定與現有檔案相同的屬性。

當應用程式跨網路建立檔案時，最好將 GENERIC_READ | GENERIC_WRITE 用於 dwDesiredAccess，而不是單獨使用 GENERIC_WRITE。產生的程式代碼較快，因為重新導向器可以使用快取管理員，並傳送較少具有更多數據的SMB。這種組合也避免了跨網路寫入檔案可能會偶爾傳回 ERROR_ACCESS_DENIED的問題。

如需詳細資訊，請參閱建立和開啟檔案。

同步和異步 I/O 句柄

CreateFile 提供建立同步或異步的檔案或裝置句柄。同步句柄的行為會讓使用該句柄的 I/O 函式呼叫遭到封鎖，直到它們完成為止，而異步檔句柄可讓系統立即從 I/O 函式呼叫傳回，無論它們是否完成 I/O 作業。如先前所述，這個同步與異步行為是由在 dwFlagsAndAttributes 參數內指定 FILE_FLAG_OVERLAPPED 來決定。使用異步 I/O 時，有數個複雜度和潛在陷阱;如需詳細資訊，請參閱同步和異步 I/O。

檔案數據流

在 NTFS 文件系統上，您可以使用 CreateFile 在檔案中建立個別的數據流。如需詳細資訊，請參閱檔案資料流。

實體磁碟和磁碟區

直接存取磁碟或磁碟區會受到限制。

Windows Server 2003 和 Windows XP：直接存取磁碟或磁碟區的方式不受限制。

您可以使用 CreateFile 函式來開啟實體磁碟驅動器或磁碟區，這會傳回直接存取存儲設備（DASD）句柄，可與 DeviceIoControl 函式搭配使用。這可讓您直接存取磁碟或磁碟區，例如磁碟分區數據表之類的磁碟元數據。不過，這種存取也會讓磁碟驅動器或磁碟區暴露出潛在的數據遺失，因為使用此機制對磁碟的寫入不正確，使得其內容無法存取操作系統。為了確保數據完整性，請務必熟悉 deviceIoControl ，以及其他 API 與直接存取句柄的行為不同，而不是文件系統句柄。

必須符合下列需求，才能讓這類呼叫成功：

呼叫端必須具有系統管理許可權。如需詳細資訊，請參閱以特殊許可權執行。
dwCreationDisposition 參數必須具有 OPEN_EXISTING 旗標。
開啟磁碟區或磁碟驅動器時，dwShareMode 參數必須具有 FILE_SHARE_WRITE 旗標。

附註dwDesiredAccess 參數可以是零，可讓應用程式在不存取裝置的情況下查詢裝置屬性。這適用於應用程式判斷磁碟驅動器的大小，以及它所支援的格式，例如，不需要磁碟驅動器中的磁碟驅動器。它也可以用來讀取統計數據，而不需要較高層級的數據讀取/寫入許可權。

開啟實體磁碟驅動器 x：時，lpFileName 字串的格式應該是：“\\.\PhysicalDriveX”。硬碟號碼從零開始。下表顯示實體磁碟驅動器字串的一些範例。

字串	意義
“\\.\PhysicalDrive0”	開啟第一個實體磁碟驅動器。
“\\.\PhysicalDrive2”	開啟第三個實體磁碟驅動器。

若要取得磁碟區的實體磁碟驅動器標識碼，請開啟磁碟區的句柄，並使用 IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTS呼叫 DeviceIoControl 函式。此控制程式代碼會傳回每個磁碟區一或多個範圍的磁碟編號和位移;磁碟區可以跨越多個實體磁碟。

如需開啟實體磁碟驅動器的範例，請參閱呼叫 DeviceIoControl。

開啟磁碟區或卸除式媒體磁碟驅動器時（例如磁碟驅動器或快快閃記憶體指紋磁碟驅動器），lpFileName 字串的格式應該是：“\\.\X：”。請勿使用尾端反斜杠（\），指出磁碟驅動器的根目錄。下表顯示磁碟驅動器字串的一些範例。

字串	意義
“\\.\A：”	開啟磁碟驅動器 A。
“\\.\C：”	開啟 C：磁碟區。
“\\.\C：\”	開啟 C：磁碟區的檔案系統。

您也可以參考磁碟區名稱來開啟磁碟區。如需詳細資訊，請參閱為磁碟區命名。

磁碟區包含一或多個掛接的文件系統。即使 CreateFile中未指定非快取選項，磁碟區句柄也可以以非快取方式開啟。您應該假設所有Microsoft文件系統都會以非快取的方式開啟磁碟區句柄。檔案的非快取 I/O 限制也適用於磁碟區。

即使數據未快取，文件系統也可能不需要緩衝區對齊。不過，如果在開啟磁碟區時指定了非快取選項，則不論磁碟區上的檔系統為何，都會強制執行緩衝區對齊。建議您在所有文件系統上以非快取方式開啟磁碟區句柄，並遵循非快取的 I/O 限制。

注意若要讀取或寫入磁碟區的最後幾個扇區，您必須呼叫 deviceIoControl 並指定 FSCTL_ALLOW_EXTENDED_DASD_IO。這表示檔系統驅動程式不會對分割區讀取或寫入呼叫執行任何 I/O 界限檢查。相反地，界限檢查是由設備驅動器執行。

變更器裝置

IOCTL_CHANGER_* deviceIoControl 接受變更裝置句柄控制碼。若要開啟變更器裝置，請使用下列格式的檔名：“\.\Changerx”，其中 x 是數位，表示要開啟的裝置，從零開始。若要在以 C 或 C++ 撰寫的應用程式中開啟變更器裝置零，請使用下列檔名：「\\.\Changer0」。

磁帶機

您可以使用下列格式的檔名來開啟磁帶機：「\.\TAPEx」。，其中 x 是數位，表示要開啟的磁碟驅動器，從磁帶機零開始。若要在以 C 或 C++ 寫入的應用程式中開啟磁帶機零，請使用下列檔名：「\\\\\.\TAPE0」。。

如需詳細資訊，請參閱備份。

通訊資源

CreateFile 函式可以建立通訊資源的句柄，例如序列埠 COM1。針對通訊資源，dwCreationDisposition 參數必須 OPEN_EXISTING、dwShareMode 參數必須是零（獨佔存取），而且 hTemplateFile 參數必須 NULL。您可以指定讀取、寫入或讀取/寫入存取權，而且可以針對重疊的 I/O 開啟句柄。

若要指定大於 9 的 COM 埠號碼，請使用下列語法：“\.\COM10”。此語法適用於允許指定 COM 埠號碼的所有埠號碼和硬體。

如需通訊的詳細資訊，請參閱 Communications。

主控台

CreateFile 函式可以建立控制台輸入的句柄（CONIN$）。如果進程因為繼承或重複而有開啟的句柄，它也可以建立使用中畫面緩衝區的句柄（CONOUT$）。呼叫進程必須附加至繼承的控制台，或由allocConsole 函式配置的主控台。針對控制台句柄，請設定 CreateFile 參數，如下所示。

參數	價值
lpFileName	使用 CONIN$ 值來指定主控台輸入。使用 CONOUT$ 值來指定主控台輸出。 CONIN$ 會取得主控台輸入緩衝區的句柄，即使 SetStdHandle 函式會重新導向標準輸入句柄。若要取得標準輸入句柄，請使用 GetStdHandle 函式。 CONOUT$ 會取得使用中畫面緩衝區的句柄，即使 SetStdHandle 重新導向標準輸出句柄也一樣。若要取得標準輸出句柄，請使用 GetStdHandle。
dwDesiredAccess	`GENERIC_READ \| GENERIC_WRITE` 是慣用的，但其中一個都可以限制存取。
dwShareMode	開啟 CONIN$時，請指定 FILE_SHARE_READ。開啟 CONOUT$時，請指定 FILE_SHARE_WRITE。如果呼叫行程繼承主控台，或子行程應該能夠存取主控台，此參數必須 `FILE_SHARE_READ \| FILE_SHARE_WRITE`。
lpSecurityAttributes	如果您要繼承主控台，SECURITY_ATTRIBUTES 結構的 bInheritHandle 成員必須 TRUE。
dwCreationDisposition	使用 createFile 開啟控制台時，您應該指定 OPEN_EXISTING。
dwFlagsAndAttributes	忽視。
hTemplateFile	忽視。

下表顯示 dwDesiredAccess 和 lpFileName的各種設定。

lpFileName	dwDesiredAccess	結果
“CON”	GENERIC_READ	開啟主控台以進行輸入。
“CON”	GENERIC_WRITE	開啟主控台以進行輸出。
“CON”	`GENERIC_READ \| GENERIC_WRITE`	導致 createFile 失敗;GetLastError 會傳回 ERROR_FILE_NOT_FOUND。

Mailslots

如果 CreateFile 開啟 mailslot 的用戶端結尾，則如果 mailslot 用戶端嘗試在 mailslot 伺服器使用 createMailSlot 函式建立本機 mailslot 之前嘗試開啟本機 mailslot，則函式會傳回 INVALID_HANDLE_VALUE。

如需詳細資訊，請參閱 Mailslots。

管道

如果 CreateFile 開啟命名管道的用戶端端，函式會使用處於接聽狀態之命名管道的任何實例。開啟進程可以視需要多次複製句柄，但在開啟它之後，另一個用戶端就無法開啟命名管道實例。開啟管道時所指定的存取必須與 createNamedPipe 函式之 dwOpenMode 參數中指定的存取相容。

如果在這項作業之前未在伺服器上成功呼叫 CreateNamedPipe 函式，則管線將不會存在，而且 CreateFile 會失敗，ERROR_FILE_NOT_FOUND。

如果至少有一個使用中管道實例，但伺服器上沒有可用的接聽程式管道，這表示所有管線實例目前都已連線，CreateFile 會失敗，ERROR_PIPE_BUSY。

如需詳細資訊，請參閱 Pipes。

例子

下列主題顯示範例檔案作業：

實體裝置 I/O 示範於下列主題：

使用命名管道的範例位於命名管道用戶端。

使用 mailslot 會顯示寫入 Mailslot。

您可以在建立備份應用程式找到磁帶備份代碼段。

注意

fileapi.h 標頭會將 CreateFile 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

要求

要求	價值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
支援的最低伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平臺	窗戶
標頭	fileapi.h （包括 Windows.h）
連結庫	Kernel32.lib
DLL	Kernel32.dll