CreateFile2 函式 (fileapi.h)

發行項
03/14/2023

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

從 Windows 市集應用程式呼叫時， CreateFile2 會簡化。您只能開啟 ApplicationData.LocalFolder 或 Package.InstalledLocation 目錄內的檔案或目錄。您無法開啟具名管道或 mailslot，或建立加密的檔案 (FILE_ATTRIBUTE_ENCRYPTED) 。

注意我們在這裡會參考應用程式的本機資料夾和套件的安裝位置，而不是套件圖形中的其他套件，例如資源套件。 CreateFile2 不支援在套件圖形中的其他套件中開啟檔案。例如，假設應用程式相依于 WinJS。應用程式可以呼叫 CreateFile2 ，在其套件中開啟檔案，而不是在 WinJS 套件中開啟。

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

語法

HANDLE CreateFile2(
  [in]           LPCWSTR                           lpFileName,
  [in]           DWORD                             dwDesiredAccess,
  [in]           DWORD                             dwShareMode,
  [in]           DWORD                             dwCreationDisposition,
  [in, optional] LPCREATEFILE2_EXTENDED_PARAMETERS pCreateExParams
);

參數

[in] lpFileName

要建立或開啟之檔案或裝置的名稱。

如需特殊裝置名稱的資訊，請參閱定義 MS-DOS 裝置名稱。

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

提示從 1607 版Windows 10開始，您可以選擇移除MAX_PATH限制，而不需在前面加上「\\？\」。如需詳細資訊，請參閱命名檔案、路徑和命名空間的一節。

[in] dwDesiredAccess

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

最常使用的值是 GENERIC_READ、 GENERIC_WRITE或兩者 (GENERIC_READ | GENERIC_WRITE) 。如需詳細資訊，請參閱一般存取權限、檔案安全性和存取權限、檔案存取權限常數和 ACCESS_MASK。

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

您無法在已開啟控制碼的開啟要求中，要求與 dwShareMode 參數所指定的共用模式衝突的存取模式。

For more information, see the Remarks section of this topic and Creating and Opening Files.

[in] dwShareMode

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

如果此參數為零且 CreateFile2 成功，則無法共用檔案或裝置，而且必須等到檔案或裝置的控制碼關閉後，才能再次開啟。如需詳細資訊，請參閱＜備註＞一節。

您無法要求與現有要求中具有開啟控制碼之存取模式衝突的共用模式。 CreateFile2 會失敗，而且 GetLastError 函式會 傳回ERROR_SHARING_VIOLATION。

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

注意不論進程內容為何，每個開啟控制碼的共用選項都會維持有效狀態，直到該控制碼關閉為止。

值	意義
0 0x00000000	如果其他進程要求刪除、讀取或寫入存取權，則防止其他進程開啟檔案或裝置。只有在應用程式具有檔案的寫入權限時，才會授與檔案或目錄的獨佔存取權。
FILE_SHARE_DELETE 0x00000004	啟用檔案或裝置上的後續開啟作業，以要求刪除存取權。否則，如果進程要求刪除存取權，則無法開啟檔案或裝置。如果未指定此旗標，但檔案或裝置已開啟以供刪除存取，則函式會失敗。注意刪除存取可同時允許刪除和重新命名作業。
FILE_SHARE_READ 0x00000001	在檔案或裝置上啟用後續開啟作業，以要求讀取權限。否則，如果其他進程要求讀取權限，則無法開啟檔案或裝置。如果未指定此旗標，但檔案或裝置已開啟以供讀取存取，則函式會失敗。如果檔案或目錄正在開啟且未指定此旗標，而且呼叫端沒有檔案或目錄的寫入權限，則函式會失敗。
FILE_SHARE_WRITE 0x00000002	在檔案或裝置上啟用後續的開啟作業，以要求寫入權限。否則，如果其他進程要求寫入權限，則無法開啟檔案或裝置。如果未指定此旗標，但已開啟檔案或裝置進行寫入權限，或具有具有寫入權限的檔案對應，則函式會失敗。

[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, optional] pCreateExParams

選擇性 CREATEFILE2_EXTENDED_PARAMETERS 結構的指標。

傳回值

如果函式成功，傳回值會是指定檔案、裝置、具名管道或郵件位置的開啟控制碼。

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

備註

若要編譯使用 CreateFile2 函式的應用程式，請將_WIN32_WINNT巨集定義為 0x0602 或更新版本。如需詳細資訊，請參閱使用 Windows 標頭。

CreateFile2 支援檔案互動，以及 Windows 開發人員可用的大部分其他類型的 I/O 裝置和機制。本節會嘗試涵蓋開發人員在不同內容中使用 CreateFile2 以及不同 I/O 類型時可能會遇到的各種問題。只有在特別參照儲存在檔案系統上實際檔案中的資料時，文字才會嘗試 使用文字檔案 。不過，某些檔案的使用方式可能會更普遍地參考支援類似檔案機制的 I/O 物件。由於先前提及的歷程記錄原因， 這個詞彙檔案 的使用在常數名稱和參數名稱中特別普遍。

當應用程式使用 CreateFile2傳回的物件控制碼完成時，請使用 CloseHandle 函式來關閉控制碼。這不僅釋放系統資源，還可以對共用檔案或裝置及認可資料至磁片等專案產生更廣泛的影響。本主題中會適當地說明細節。

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

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

如果在pCreateExParams參數中傳遞之CREATEFILE2_EXTENDED_PARAMETERS結構的lpSecurityAttributes成員是Null，則應用程式可能建立的任何子進程都無法繼承CreateFile2所傳回的控制碼。下列有關此成員的資訊也適用于：

如果 bInheritHandle 成員變數不是 FALSE，這是任何非零值，則可以繼承控制碼。因此，如果您不想要繼承控制碼，此結構成員必須正確地初始化為 FALSE 。
存取控制清單 (ACL) 檔案或目錄的預設安全性描述項繼承自其父目錄。
目的檔案系統必須支援檔案和目錄的安全性， lpSecurityDescriptor 成員才能對它們產生影響，這可以使用 GetVolumeInformation來決定。

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

技術	支援
伺服器訊息區 (SMB) 3.0 通訊協定	Yes
SMB 3.0 透明容錯移轉 (TFO)	No
具有向外延展檔案共用的 SMB 3.0 (SO)	No
叢集共用磁片區檔案系統 (CsvFS)	Yes
彈性檔案系統 (ReFS)	Yes

符號連結行為

如果呼叫此函式會建立檔案，則行為不會有任何變更。此外，請考慮下列有關在pCreateExParams參數中傳遞之CREATEFILE2_EXTENDED_PARAMETERS結構之 dwFileFlags成員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 ，受影響的檔案就是目標。

檔

如果您重新命名或刪除檔案，然後稍後還原它，系統會在快取中搜尋要還原的檔案資訊。快取的資訊包括其簡短/完整名稱組和建立時間。

如果您在先前呼叫 DeleteFile 時擱置刪除的檔案上呼叫 CreateFile2，函式會失敗。作業系統會延遲檔案刪除，直到關閉檔案的所有控制碼為止。 GetLastError 會 傳回ERROR_ACCESS_DENIED。

dwDesiredAccess參數可以是零，允許應用程式在應用程式執行時使用適當的安全性設定來查詢檔案屬性，而不需要存取檔案。這很適合用來測試檔案是否存在，而不需開啟檔案以進行讀取和/或寫入存取，或取得檔案或目錄的其他統計資料。請參閱取得和設定檔案資訊和 GetFileInformationByHandle。

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

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

檔案資料流程

在 NTFS 檔案系統上，您可以使用 CreateFile2 在檔案內建立個別的資料流程。如需詳細資訊，請參閱檔案資料流程。

若要使用CreateFile2開啟目錄，請將FILE_FLAG_BACKUP_SEMANTICS旗標指定為pCreateExParams參數中傳遞之 CREATEFILE2_EXTENDED_PARAMETERS結構的dwFileFlags成員的一部分。當使用此旗標而不 SE_BACKUP_NAME 和 SE_RESTORE_NAME 許可權時，仍適用適當的安全性檢查。

使用 CreateFile2 在重組 FAT 或 FAT32 檔案系統磁片區期間開啟目錄時，請勿指定 MAXIMUM_ALLOWED 存取權限。如果這樣做，目錄的存取就會遭到拒絕。請改為指定 GENERIC_READ 存取權限。

如需詳細資訊，請參閱關於目錄管理。

實體磁片和磁片區

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

您可以使用 CreateFile2 函式來開啟實體磁片磁碟機或磁片區，這會傳回可搭配 DeviceIoControl 函式使用的直接存取存放裝置 (DASD) 控制碼。這可讓您直接存取磁片或磁片區，例如磁片中繼資料，例如磁碟分割資料表。不過，這種類型的存取也會將磁片磁碟機或磁片區公開給潛在的資料遺失，因為使用此機制對磁片的寫入不正確，可能會讓作業系統無法存取其內容。為了確保資料完整性，請務必熟悉 DeviceIoControl ，以及其他 API 的運作方式與直接存取控制碼不同，而不是檔案系統控制碼。

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

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

注意dwDesiredAccess參數可以是零，可讓應用程式在不存取裝置的情況下查詢裝置屬性。這適用于應用程式，以判斷磁片磁碟機的大小及其支援的格式，而不需要磁片磁碟機中的磁片磁碟機，例如。它也可以用於讀取統計資料，而不需要較高層級的資料讀取/寫入權限。

開啟實體磁片磁碟機 x：時， lpFileName 字串的格式應該是：「\\.\PhysicalDriveX」。硬碟編號從零開始。下表顯示實體磁片磁碟機字串的一些範例。

String	意義
「\\.\PhysicalDrive0」	開啟第一個實體磁片磁碟機。
「\\.\PhysicalDrive2」	開啟第三個實體磁片磁碟機。

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

如需開啟實體磁片磁碟機的範例，請參閱呼叫 DeviceIoControl。

例如，開啟磁片區或卸載式媒體磁片磁碟機 (時，磁片磁碟機或快閃記憶體指紋磁片磁碟機 ) ，lpFileName 字串的格式應該是：「\.\X：」。請勿使用尾端反斜線 (\) ，這表示磁片磁碟機的根目錄。下表顯示磁片磁碟機字串的一些範例。

String	意義
「\\.\A：」	開啟磁片磁碟機 A。
「\\.\C：」	開啟 C：磁片區。
「\\.\C：\」	開啟 C：磁片區的檔案系統。

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

磁片區包含一或多個掛接的檔案系統。即使 CreateFile2中未指定非快取選項，磁片區控制碼也可以開啟為非快取特定檔案系統。您應該假設所有 Microsoft 檔案系統都會以非快取方式開啟磁片區控制碼。檔案的非快取 I/O 限制也適用于磁片區。

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

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

變更器裝置

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

磁帶機

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

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

通訊資源

CreateFile2函式可以建立通訊資源的控制碼，例如序列埠 COM1。對於通訊資源，dwCreationDisposition參數必須OPEN_EXISTING，dwShareMode參數必須是零 (獨佔存取) ，而hTemplateFile參數必須是Null。可以指定讀取、寫入或讀取/寫入存取權，而且可以針對重迭的 I/O 開啟控制碼。

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

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

機

CreateFile2函式可以建立主控台輸入的控制碼， (CONIN$) 。如果進程因為繼承或重複而有開啟的控制碼，也可以建立使用中螢幕緩衝區的控制碼， (CONOUT$) 。呼叫進程必須附加至繼承的主控台或 AllocConsole 函式所配置的主控台。針對主控台控制碼，請設定 CreateFile2 參數，如下所示。

參數	值
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` 。
dwCreationDisposition	使用CreateFile2開啟主控台時，您應該指定OPEN_EXISTING。

設定在pCreateExParams參數中傳遞之CREATEFILE2_EXTENDED_PARAMETERS結構的成員，如下所示。

成員	值
lpSecurityAttributes	如果您想要繼承主控台，SECURITY_ATTRIBUTES結構的bInheritHandle成員必須是TRUE。
dwFileAttributes dwFileFlags dwSecurityQosFlags hTemplateFile	忽略。

成員

值

lpSecurityAttributes

如果您想要繼承主控台，SECURITY_ATTRIBUTES結構的bInheritHandle成員必須是TRUE。

dwFileAttributes

dwFileFlags

dwSecurityQosFlags

hTemplateFile

忽略。

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

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

Mailslots

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

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

管道

如果 CreateFile2 開啟具名管道的用戶端端，函式會使用處于接聽狀態之具名管道的任何實例。開啟進程可以視需要多次複製控制碼，但在開啟之後，無法由另一個用戶端開啟具名管道實例。開啟管道時所指定的存取權必須與CreateNamedPipe函式之 dwOpenMode參數中指定的存取相容。

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

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

如需詳細資訊，請參閱管道。

規格需求


最低支援的用戶端	Windows 8 [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2012 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	fileapi.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll