SetEntriesInAclA function (aclapi.h)

Article
02/09/2023

The SetEntriesInAcl function creates a new access control list (ACL) by merging new access control or audit control information into an existing ACL structure.

Syntax

DWORD SetEntriesInAclA(
  [in]           ULONG              cCountOfExplicitEntries,
  [in, optional] PEXPLICIT_ACCESS_A pListOfExplicitEntries,
  [in, optional] PACL               OldAcl,
  [out]          PACL               *NewAcl
);

Parameters

[in] cCountOfExplicitEntries

The number of EXPLICIT_ACCESS structures in the pListOfExplicitEntries array.

[in, optional] pListOfExplicitEntries

A pointer to an array of EXPLICIT_ACCESS structures that describe the access control information to merge into the existing ACL.

[in, optional] OldAcl

A pointer to the existing ACL. This parameter can be NULL, in which case, the function creates a new ACL based on the EXPLICIT_ACCESS entries.

[out] NewAcl

A pointer to a variable that receives a pointer to the new ACL. If the function succeeds, you must call the LocalFree function to free the returned buffer.

Return value

If the function succeeds, the function returns ERROR_SUCCESS.

If the function fails, it returns a nonzero error code defined in WinError.h.

Remarks

Each entry in the array of EXPLICIT_ACCESS structures specifies access control or audit control information for a specified trustee. A trustee can be a user, group, or other security identifier (SID) value, such as a logon identifier or logon type (for instance, a Windows service or batch job). You can use a name or a SID to identify a trustee.

You can use the SetEntriesInAcl function to modify the list of access control entries (ACEs) in a discretionary access control list (DACL) or a system access control list (SACL). Note that SetEntriesInAcl does not prevent you from mixing access control and audit control information in the same ACL; however, the resulting ACL will contain meaningless entries.

For a DACL, the grfAccessMode member of the EXPLICIT_ACCESS structure specifies whether to allow, deny, or revoke access rights for the trustee. This member can specify one of the following values:

GRANT_ACCESS
SET_ACCESS
DENY_ACCESS
REVOKE_ACCESS

For information about these values, see ACCESS_MODE.

The SetEntriesInAcl function places any new access-denied ACEs at the beginning of the list of ACEs for the new ACL. This function places any new access-allowed ACEs just before any existing access-allowed ACEs.

For a SACL, the grfAccessMode member of the EXPLICIT_ACCESS structure can specify the following values:

REVOKE_ACCESS
SET_AUDIT_FAILURE
SET_AUDIT_SUCCESS

SET_AUDIT_FAILURE and SET_AUDIT_SUCCESS can be combined. For information about these values, see ACCESS_MODE.

The SetEntriesInAcl function places any new system-audit ACEs at the beginning of the list of ACEs for the new ACL.

Examples

For an example that uses this function, see Modifying the ACLs of an Object or Creating a Security Descriptor for a New Object or Taking Object Ownership.

Note

The aclapi.h header defines SetEntriesInAcl as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

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	aclapi.h
Library	Advapi32.lib
DLL	Advapi32.dll

Share via