RtlCreateAcl 函式（ntifs.h）

發行項
02/07/2025

RtlCreateAcl 例程會建立並初始化訪問控制清單（ACL）。

語法

NTSYSAPI NTSTATUS RtlCreateAcl(
  [out] PACL  Acl,
  [in]  ULONG AclLength,
        ULONG AclRevision
);

參數

[out] Acl

呼叫端配置的緩衝區指標，以接收初始化的 ACL 結構。此緩衝區必須至少 sizeof（ACL），

[in] AclLength

Acl 參數所指向之緩衝區的長度，以位元組為單位。這個值必須夠大，才能包含 ACL 標頭，以及要儲存在 ACL 中的所有存取控制專案（ACE）。如需計算 ACL 大小的相關信息，請參閱下列一節。

AclRevision

要新增之 ACE 的 ACL 修訂層級。 Windows 版本需求如下：

價值	意義
ACL_REVISION	所有 Windows 版本的修訂層級都有效。
ACL_REVISION_DS	*：如果 Acl Acl* 中的 ACL 包含物件特定的 ACE，則必須 ACL_REVISION_DS**AceRevision。

傳回值

RtlCreateAcl 可以傳回下列其中一個狀態值：

傳回碼	描述
STATUS_SUCCESS	ACL 已成功建立並初始化。
STATUS_BUFFER_TOO_SMALL	新的 ACL 不適用於位於 Acl的緩衝區。需要較大的 ACL 緩衝區。
STATUS_INVALID_PARAMETER	指定的修訂不是目前的，或 AclLength 的值太大。

言論

RtlCreateAcl 所初始化的 ACL 不包含存取控制專案（ACE）。這個 ACL 是空的，而不是不存在的 ACL。如果空的 ACL 套用至物件，ACL 會隱含拒絕該物件的所有存取權。若要將 ACL 新增 ACL，請使用 RtlAddAccessAllowedAce。

若要計算 ACL 的大小，請將 sizeof（ACL）新增至要儲存在 ACL 中之所有 ACE 的大小。若要計算 ACE 的大小，請將 ACE 結構的大小，例如 sizeof（ACCESS_ALLOWED_ACE），新增至與 ACE 相關聯的 SID 長度，然後減去 SidStart 成員的大小（這是 ACE 結構和 SID 的一部分）。使用 RtlLengthSid 函式來取得指定 SID 的長度。

下列範例示範如何計算允許存取的 ACE 大小：

sizeof (ACCESS_ALLOWED_ACE) - sizeof (ACCESS_ALLOWED_ACE.SidStart) 
        + GetLengthSid (pAceSid);

若要計算 ACL 的大小，請使用下列演算法，在 sizeof（ACE）運算式中取代適當的 ACE 結構：

cbAcl = sizeof (ACL);
for (i = 0 ; i < nAceCount ; i++) {
    // subtract ACE.SidStart from the size
    cbAce = sizeof (ACE) - sizeof (DWORD);
    // add this ACE's SID length
    cbAce += GetLengthSid (pAceSid[i]);
    // add the length of each ACE to the total ACL length
    cbAcl += cbAce;
}

如需安全性和訪問控制的詳細資訊，請參閱適用於驅動程式開發人員的 Windows 安全性模型，以及 Windows SDK 中這些主題的檔。