InitializeAcl function (securitybaseapi.h)

Article
10/13/2021

The InitializeAcl function initializes a new ACL structure.

Syntax

BOOL InitializeAcl(
  [out] PACL  pAcl,
  [in]  DWORD nAclLength,
  [in]  DWORD dwAclRevision
);

Parameters

[out] pAcl

A pointer to an ACL structure to be initialized by this function. Allocate memory for pAcl before calling this function.

[in] nAclLength

The length, in bytes, of the buffer pointed to by the pAcl parameter. This value must be large enough to contain the ACL header and all of the access control entries (ACEs) to be stored in the ACL. In addition, this value must be DWORD-aligned. For more information about calculating the size of an ACL, see Remarks.

[in] dwAclRevision

The revision level of the ACL structure being created.

This value can be ACL_REVISION or ACL_REVISION_DS. Use ACL_REVISION_DS if the access control list (ACL) supports object-specific ACEs.

Return value

If the function succeeds, the function returns nonzero.

If the function fails, it returns zero. To get extended error information, call GetLastError.

Remarks

The InitializeAcl function creates an empty ACL structure; the ACL contains no ACEs. Applying an empty ACL to an object denies all access to that object.

The initial size of the ACL depends on the number of ACEs you plan to add to the ACL before you use it. For example, if the ACL is to contain an ACE for a user and group, you would initialize the ACL based on two ACEs. For details about modifying an existing ACL, see Modifying the ACLs of an Object.

To calculate the initial size of an ACL, add the following together, and then align the result to the nearest DWORD:

Size of the ACL structure.
Size of each ACE structure that the ACL is to contain minus the SidStart member (DWORD) of the ACE.
Length of the SID that each ACE is to contain.

Examples

The following example calls the InitializeAcl function. The size of the ACL is based on three allow-access ACEs. As an option, you can use security descriptor definition language (SDDL) to create the ACL. For details, see Creating a DACL.

The example also omits a step for simplification. For more information, see the Taking Object Ownership example. You must call the FreeSid function at the end of the example code due to calling the AllocateAndInitializeSid function.

#include <windows.h>
#include <Winbase.h>
#pragma comment(lib, "duser.lib")

#define NUM_OF_ACES 3

void main()
{
    PACL pAcl = NULL;
    DWORD cbAcl = 0;
    PSID psids[NUM_OF_ACES];

    // Allocate and initialize SIDs.
    // Step omitted - See Taking Object Ownership example.

    // Add the SID for each ACE to psids. 
    cbAcl = sizeof(ACL) + 
        ((sizeof(ACCESS_ALLOWED_ACE)) * NUM_OF_ACES);
    for (int i = 0; i < NUM_OF_ACES; i++)
    {
        cbAcl += GetLengthSid(psids[i]) - sizeof(DWORD);
    }

    // Align cbAcl to a DWORD.
    cbAcl = (cbAcl + (sizeof(DWORD) - 1)) & 0xfffffffc;

    pAcl = (ACL*)LocalAlloc(LPTR, cbAcl);
    if (pAcl)
    {
        if (InitializeAcl(pAcl, cbAcl, ACL_REVISION))
        {

            // Add the ACEs to the ACL.
            // Add the ACL to the object's security descriptor.
        }
        else
        {

            // Handle error.
        }
    }
    {

        // Handle error.
    }

    // Free pAcl when finished.
    // Call FreeSid when finished.
}

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2003 [desktop apps \| UWP apps]
Target Platform	Windows
Header	securitybaseapi.h (include Windows.h)
Library	Advapi32.lib
DLL	Advapi32.dll

Share via