共用方式為

CreateFile3 函式 （fileapi.h）

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

從沙箱封裝的封裝應用程式呼叫時， CreateFile3 會簡化。 您只能開啟 ApplicationData.LocalFolder 或 Package.InstalledLocation 目錄內的檔案或目錄。 您無法開啟具名管道或郵件插槽，也無法建立加密檔案 （FILE_ATTRIBUTE_ENCRYPTED）。

備註

 我們在這裡指的是應用程式的本機資料夾和套件的安裝位置，而不是套件圖表中的其他套件，例如資源套件。 CreateFile3 不支援在套件圖表中開啟其他套件中的檔案。 若要將此作業作為交易作業執行，以產生可用於交易 I/O 的控制碼，請使用 CreateFileTransacted 函式。

語法

HANDLE CreateFile3(
  LPCWSTR                           lpFileName,
  DWORD                             dwDesiredAccess,
  DWORD                             dwShareMode,
  DWORD                             dwCreationDisposition,
  LPCREATEFILE3_EXTENDED_PARAMETERS pCreateExParams
);

參數

lpFileName

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

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

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

小提示

 您可以選擇移除 MAX_PATH 限制，而不加上前置 “\？”。 如需詳細資訊，請參閱 命名檔案、路徑和命名空間 的「最大路徑長度限制」一節。

dwDesiredAccess

要求對檔案或裝置的存取權，可以總結為讀取、寫入、兩者或兩者都不是零。

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

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

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

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

dwShareMode

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

如果此參數為零，且 CreateFile3 成功，則無法共用檔案或裝置，而且無法再次開啟，直到檔案或裝置的控制碼關閉為止。 如需詳細資訊，請參閱備 註 一節。

您無法要求與具有開啟控點的現有要求中指定的存取模式衝突的共用模式。 CreateFile3 會失敗， 而 GetLastError 函式會傳回 ERROR_SHARING_VIOLATION。

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

備註

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

價值觀 Meaning
0
0x00000000		 防止其他進程在要求刪除、讀取或寫入存取權時開啟檔案或裝置。 只有在應用程式具有檔案的寫入許可權時，才會授與檔案或目錄的獨佔存取權。
FILE_SHARE_DELETE
0x00000004		 啟用檔案或裝置上的後續開啟作業，以要求刪除存取權。 否則，如果其他進程要求刪除存取權，則無法開啟檔案或裝置。 如果未指定此旗標，但已開啟檔案或裝置以進行刪除存取，則函式會失敗。

便條： 刪除存取權允許刪除和重新命名作業。
FILE_SHARE_READ
0x00000001		 啟用檔案或裝置上的後續開啟作業，以要求讀取存取權。 否則，其他進程在要求讀取存取權時無法開啟檔案或裝置。 如果未指定此旗標，但已開啟檔案或裝置以取得讀取權，則函式會失敗。 如果正在開啟檔案或目錄，且未指定此旗標，且呼叫端沒有檔案或目錄的寫入存取權，則函式會失敗。
FILE_SHARE_WRITE
0x00000002		 啟用檔案或裝置上的後續開啟作業，以要求寫入存取權。 否則，如果其他進程要求寫入存取權，則無法開啟檔案或裝置。 如果未指定此旗標，但已開啟檔案或裝置以進行寫入存取，或具有具有寫入存取權的檔案對映，則函式會失敗。

dwCreationDisposition

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

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

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

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

價值觀 Meaning
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 參數的一部分。

pCreateExParams

選擇性 CREATEFILE3_EXTENDED_PARAMETERS 結構的指標。

傳回值

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

如果函式失敗，則傳回值為 INVALID_HANDLE_VALUE。 若要取得擴充錯誤資訊，請呼叫 GetLastError。 可能的錯誤包括：

傳回碼 Description
ERROR_PATH_REDIRECTED lpFileName 已由重新分析點和/或符號連結重新導向。

備註

CreateFile3 的行為方式與 CreateFile2 完全相同，但有一個例外;如果 lpFileName 是透過重新分析點或符號連結重新導向，作業可能會失敗。 您可以藉由將 FILE_FLAG_DISALLOW_PATH_REDIRECTS 旗標新增至 dwFileFlags 來禁止重新導向。

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

CreateFile3 支援檔案互動，以及 Windows 開發人員可用的大部分其他類型的 I/O 裝置和機制。 本節嘗試涵蓋開發人員在不同內容和不同 I/O 類型中使用 CreateFile3 時可能遇到的各種問題。 只有在專門引用儲存在檔案系統上實際檔案中的資料 時，文字 才會嘗試使用單字檔案。 不過， 檔案 的某些用途可能會更一般地參考支援類似檔案機制的 I/O 物件。 由於前面提到的歷史原因，這種對 術語檔案 的自由使用在常數名稱和參數名稱中特別普遍。

當應用程式使用 CreateFile3 傳回的物件控制碼完成時，請使用 CloseHandle 函式來關閉控制碼。 這不僅可以釋放系統資源，還可以對共享文件或設備以及將數據提交到磁盤等事情產生更廣泛的影響。 本主題中會酌情說明細節。

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

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

如果 pCreateExParams 參數中傳遞的 CREATEFILE3_EXTENDED_PARAMETERS 結構的 lpSecurityAttributes 成員是 NULL，則 CreateFile3 所傳回的控制碼無法由應用程式可能建立的任何子進程繼承。 有關該會員的以下資訊也適用：

  • 如果 bInheritHandle 成員變數不是 FALSE，這是任何非零值，則可以繼承控制碼。 因此，如果您不打算將控制碼可繼承，則正確初始化 FALSE 此結構成員非常重要。
  • 檔案或目錄預設安全描述子中的存取控制清單 （ACL） 繼承自其母目錄。
  • 目標檔案系統必須支援檔案和目錄的安全性， lpSecurityDescriptor 成員才能對其產生影響，這可以使用 GetVolumeInformation 來判斷。

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

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

如果呼叫此函式會建立檔案，則行為不會變更。 此外FILE_FLAG_OPEN_REPARSE_POINT請考慮下列有關 pCreateExParams 參數中傳遞之 CREATEFILE3_EXTENDED_PARAMETERS 結構之 dwFileFlags 成員旗標的資訊：

  • 如果指定 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 或 DeleteFile2 而擱置刪除的檔案上呼叫 CreateFile3，則函式會失敗。 作業系統會延遲檔案刪除，直到檔案的所有控制碼都關閉為止。 GetLastError 會傳回 ERROR_ACCESS_DENIED。

dwDesiredAccess 參數可以為零，如果應用程式以足夠的安全性設定執行，則允許應用程式查詢檔案屬性，而不需要存取檔案。 這對於測試檔案是否存在而不開啟檔案進行讀取及/或寫入存取權，或取得檔案或目錄的其他統計資料很有用。 請參閱 取得和設定檔案資訊 和 GetFileInformationByHandle。

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

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

檔案串流

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

目錄

應用程式無法使用 CreateFile3 建立目錄，因此只有 OPEN_EXISTING 值對此使用案例的 dwCreationDisposition 有效。 若要建立目錄，應用程式必須呼叫 CreateDirectory、 CreateDirectoryEx 或 CreateDirectory2。

若要使用 CreateFile3 開啟目錄，請將 FILE_FLAG_BACKUP_SEMANTICS 旗標指定為 pCreateExParams 參數中傳遞之 CREATEFILE3_EXTENDED_PARAMETERS 結構之 dwFileFlags 成員的一部分。 當此旗標在沒有 SE_BACKUP_NAME 和 SE_RESTORE_NAME 許可權的情況下使用時，仍會套用適當的安全檢查。

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

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

實體磁碟和磁碟區

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

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

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

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

備註

  dwDesiredAccess 參數可以是零，可讓應用程式查詢裝置屬性，而不需要存取裝置。 例如，這對於應用程式判斷磁碟機的大小及其支援的格式非常有用，而不需要磁碟機中的軟碟。 它也可以用於讀取統計資料，而不需要更高層級的資料讀/寫權限。

開啟實體磁碟驅動器 x： 時， lpFileName 字串應該是下列格式：「\.\PhysicalDriveX」。

硬碟號碼從零開始。 下表顯示實體磁碟機字串的一些範例。

繩子 Meaning
“\.\物理驅動器0” 開啟第一個實體磁碟機。
“\.\物理驅動器2” 開啟第三個實體磁碟機。

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

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

開啟磁碟區或抽取式媒體磁碟機 （例如，磁碟驅動器或快閃記憶體拇指磁碟機） 時， lpFileName 字串應該是下列格式：「\\.\X：“。 請勿使用尾端反斜線 （\），它表示磁碟機的根目錄。

下表顯示磁碟機字串的一些範例：

繩子 Meaning
“\.\A：” 開啟軟碟機 A。
“\.\C：” 開啟 C： 磁碟區。
“\.\C：” 開啟 C： 磁碟區的檔案系統。

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

磁區包含一或多個已掛接的檔案系統。 磁片區控制碼可以根據特定檔案系統的判斷開啟為非快取，即使未在 CreateFile3 中指定非快取選項也一樣。 您應該假設所有 Microsoft 檔案系統都會將磁碟區控制碼開啟為非快取。 檔案未快取 I/O 的限制也適用於磁區。

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

備註

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

更換裝置

DeviceIoControl 的 IOCTL_CHANGER_* 控制碼會接受變更器裝置的控制碼。 若要開啟 Changer 裝置，請使用下列形式的檔案名稱：「\.\Changerx」，其中 x 是一個數字，表示要開啟的裝置，從零開始。 若要在以 C 或 C++ 撰寫的應用程式中開啟變換器裝置零，請使用下列檔名： “\\.\Changer0”。

磁帶機

您可以使用下列格式的檔名來開啟磁帶機：「\.\TAPEx」，其中 x 是指出要開啟的磁碟機的數字，從磁帶機零開始。 若要在以 C 或 C++ 撰寫的應用程式中開啟磁帶機零，請使用下列檔名： “\\.\TAPE0”。

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

通訊資源

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

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

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

Consoles

CreateFile3 函式可以建立主控台輸入的控制碼 （CONIN$） 。 如果進程因為繼承或複製而具有開啟的控制碼，它也可以建立作用中螢幕緩衝區的控制碼 （CONOUT$） 。 呼叫進程必須附加至繼承的主控台或 AllocConsole 函式所配置的主控台。

針對主控台控制碼，請設定 CreateFile3 參數，如下所示：

參數 價值觀
lp檔案名稱 使用 CONIN$ 值來指定主控台輸入。

使用 CONOUT$ 值來指定主控台輸出。

CONIN$ 會取得主控台輸入緩衝區的控制碼，即使 SetStdHandle 函式會重新導向標準輸入控制碼也一樣。 若要取得標準輸入控制碼，請使用 GetStdHandle 函式。

CONOUT$ 會取得作用中螢幕緩衝區的控制碼，即使 SetStdHandle 重新導向標準輸出控制碼也一樣。 若要取得標準輸出控制碼，請使用 GetStdHandle。
dwDesiredAccess GENERIC_READ \| GENERIC_WRITE 是首選，但任何一個都可以限制訪問。
dwShare模式 開啟 CONIN$ 時，請指定 FILE_SHARE_READ。 開啟 CONOUT$ 時，請指定 FILE_SHARE_WRITE。

如果呼叫處理程序繼承主控台，或子處理程序應該能夠存取主控台，則此參數必須是 FILE_SHARE_READ \| FILE_SHARE_WRITE。
dwCreation處置 使用 CreateFile3 開啟主控台時，您應該指定OPEN_EXISTING。

設定 pCreateExParams 參數中傳遞的 CREATEFILE3_EXTENDED_PARAMETERS 結構成員，如下所示：

Members 價值觀
lpSecurity屬性 如果您想要繼承主控台，SECURITY_ATTRIBUTES結構的 bInheritHandle 成員必須是 TRUE。
dwFile屬性
dwFile旗標
dwSecurityQosFlags
hTemplateFile		 被忽略了。

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

lp檔案名稱 dwDesiredAccess Result
“缺點” GENERIC_READ 開啟主控台以供輸入。
“缺點” GENERIC_WRITE 開啟主控台以進行輸出。
“缺點” GENERIC_READ \| GENERIC_WRITE 導致 CreateFile3 失敗; GetLastError 會傳回 ERROR_FILE_NOT_FOUND。

郵件槽

如果 CreateFile3 開啟郵件插槽的用戶端端，則函式會傳回 INVALID_HANDLE_VALUE 如果郵件插槽用戶端嘗試在郵件插槽伺服器使用 CreateMailSlot 函式建立本機郵件插槽之前開啟它。

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

管道

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

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

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

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

需求

Requirement 價值觀
最低支援的用戶端 Windows 11 24H2 [桌面應用程式 |UWP 應用程式]
支援的最低伺服器 Windows Server 2025 [傳統型應用程式 |UWP 應用程式]
Header fileapi.h （包括 Windows.h）
Library 內核 32.lib
DLL檔案 Kernel32.dll

另請參閱

建立目錄2

刪除檔案2

移除目錄2

  • Last updated on