CreateDirectoryExA 函式 (winbase.h)

發行項
06/02/2023

使用指定範本目錄的屬性建立新的目錄。如果基礎檔案系統支援檔案和目錄的安全性，函式會將指定的安全性描述元套用至新的目錄。新目錄會保留指定範本目錄的其他屬性。

若要以交易作業的形式執行此作業，請使用 CreateDirectoryTransacted 函式。

語法

BOOL CreateDirectoryExA(
  [in]           LPCSTR                lpTemplateDirectory,
  [in]           LPCSTR                lpNewDirectory,
  [in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes
);

參數

[in] lpTemplateDirectory

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

提示

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

[in] lpNewDirectory

要建立之目錄的路徑。

提示

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

[in, optional] lpSecurityAttributes

SECURITY_ATTRIBUTES結構的指標。結構的 lpSecurityDescriptor 成員會指定新目錄的安全性描述元。

如果 lpSecurityAttributes 為 Null，目錄會取得預設的安全性描述元。存取控制會在目錄的預設安全性描述元中列出 (ACL) 繼承自其父目錄。

目的檔案系統必須支援檔案和目錄的安全性，這個參數才能生效。當 GetVolumeInformation 傳回 FS_PERSISTENT_ACLS時，就會指出這點。

傳回值

如果函式成功，則傳回非零的值。

如果函式失敗，傳回值會是零 (0) 。若要取得擴充的錯誤資訊，請呼叫 GetLastError。可能的錯誤包括下列各項。

傳回碼	描述
ERROR_ALREADY_EXISTS	指定的目錄已經存在。
ERROR_PATH_NOT_FOUND	一或多個中繼目錄不存在。此函式只會在路徑中建立最終目錄。若要在路徑上建立所有中繼目錄，請使用 SHCreateDirectoryEx 函式。

備註

CreateDirectoryEx函式可讓您建立從其他目錄繼承資料流程資訊的目錄。例如，當您使用 Macintosh 目錄時，此函式很有用，其具有適當識別目錄內容作為屬性所需的資源資料流。

某些檔案系統，例如 NTFS 檔案系統，支援個別檔案和目錄的壓縮或加密。在針對這類檔案系統格式化的磁片區上，新目錄會繼承其父目錄的壓縮和加密屬性。

您可以使用FILE_FLAG_BACKUP_SEMANTICS旗標集呼叫CreateFile函式，以取得目錄的控制碼。如需程式碼範例，請參閱 CreateFile。

若要支援查詢此物件之安全性描述元的繼承函式，可以啟發式判斷並報告該繼承生效。如需詳細資訊，請參閱可繼承 ACE 的自動傳播。

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

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

注意

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

規格需求


最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平台	Windows
標頭	winbase.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll