UID

title

description

helpviewer_keywords

old-location

tech.root

ms.assetid

ms.date

ms.keywords

req.header

req.include-header

req.target-type

req.target-min-winverclnt

req.target-min-winversvr

req.kmdf-ver

req.umdf-ver

req.ddi-compliance

req.unicode-ansi

req.idl

req.max-support

req.namespace

req.assembly

req.type-library

req.lib

req.dll

req.irql

targetos

req.typenames

req.redist

ms.custom

f1_keywords

dev_langs

topic_type

api_type

api_location

api_name

NF:aclapi.SetNamedSecurityInfoA

SetNamedSecurityInfoA function (aclapi.h)

Sets specified security information in the security descriptor of a specified object. (ANSI)

SetNamedSecurityInfoA

aclapi/SetNamedSecurityInfoA

security\setnamedsecurityinfo.htm

security

70fbba50-2576-4857-a955-119fb12bf7b6

12/05/2018

SetNamedSecurityInfo, SetNamedSecurityInfo function [Security], SetNamedSecurityInfoA, SetNamedSecurityInfoW, _win32_setnamedsecurityinfo, aclapi/SetNamedSecurityInfo, aclapi/SetNamedSecurityInfoA, aclapi/SetNamedSecurityInfoW, security.setnamedsecurityinfo

aclapi.h

Windows

Windows XP [desktop apps \| UWP apps]

Windows Server 2003 [desktop apps \| UWP apps]

SetNamedSecurityInfoW (Unicode) and SetNamedSecurityInfoA (ANSI)

Advapi32.lib

Advapi32.dll

Windows

19H1

SetNamedSecurityInfoA

aclapi/SetNamedSecurityInfoA

c++

APIRef

kbSyntax

DllExport

Advapi32.dll

API-MS-Win-Security-Provider-l1-1-0.dll

advapi32legacy.dll

API-MS-Win-DownLevel-AdvApi32-l3-1-0.dll

ntmarta.dll

API-MS-Win-Security-Provider-Ansi-L1-1-0.dll

SetNamedSecurityInfo

SetNamedSecurityInfoA

SetNamedSecurityInfoW

SetNamedSecurityInfoA function

-description

The SetNamedSecurityInfo function sets specified security information in the security descriptor of a specified object. The caller identifies the object by name.

-parameters

-param pObjectName [in]

A pointer to a null-terminated string that specifies the name of the object for which to set security information. This can be the name of a local or remote file or directory on an NTFS file system, network share, registry key, semaphore, event, mutex, file mapping, or waitable timer.

For descriptions of the string formats for the different object types, see SE_OBJECT_TYPE.

-param ObjectType [in]

A value of the SE_OBJECT_TYPE enumeration that indicates the type of object named by the pObjectName parameter.

-param SecurityInfo [in]

A set of bit flags that indicate the type of security information to set. This parameter can be a combination of the SECURITY_INFORMATION bit flags.

-param psidOwner [in, optional]

A pointer to a SID structure that identifies the owner of the object. If the caller does not have the SeRestorePrivilege constant (see Privilege Constants), this SID must be contained in the caller's token, and must have the SE_GROUP_OWNER permission enabled. The SecurityInfo parameter must include the OWNER_SECURITY_INFORMATION flag. To set the owner, the caller must have WRITE_OWNER access to the object or have the SE_TAKE_OWNERSHIP_NAME privilege enabled. If you are not setting the owner SID, this parameter can be NULL.

-param psidGroup [in, optional]

A pointer to a SID that identifies the primary group of the object. The SecurityInfo parameter must include the GROUP_SECURITY_INFORMATION flag. If you are not setting the primary group SID, this parameter can be NULL.

-param pDacl [in, optional]

A pointer to the new DACL for the object. The SecurityInfo parameter must include the DACL_SECURITY_INFORMATION flag. The caller must have WRITE_DAC access to the object or be the owner of the object. If you are not setting the DACL, this parameter can be NULL.

-param pSacl [in, optional]

A pointer to the new SACL for the object. The SecurityInfo parameter must include any of the following flags: SACL_SECURITY_INFORMATION, LABEL_SECURITY_INFORMATION, ATTRIBUTE_SECURITY_INFORMATION, SCOPE_SECURITY_INFORMATION, or BACKUP_SECURITY_INFORMATION.

If setting SACL_SECURITY_INFORMATION or SCOPE_SECURITY_INFORMATION, the caller must have the SE_SECURITY_NAME privilege enabled. If you are not setting the SACL, this parameter can be NULL.

-returns

If the function succeeds, the function returns ERROR_SUCCESS.

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

-remarks

If you are setting the discretionary access control list (DACL) or any elements in the system access control list (SACL) of an object, the system automatically propagates any inheritable access control entries (ACEs) to existing child objects, according to the rules of inheritance.

You can use the SetNamedSecurityInfo function with the following types of objects:

Local or remote files or directories on an NTFS
Local or remote printers
Local or remote Windows services
Network shares
Registry keys
Semaphores, events, mutexes, and waitable timers
File-mapping objects
Directory service objects

The SetNamedSecurityInfo function does not reorder access-allowed or access-denied ACEs based on the preferred order. When propagating inheritable ACEs to existing child objects, SetNamedSecurityInfo puts inherited ACEs in order after all of the noninherited ACEs in the DACLs of the child objects.

This function transfers information in plaintext. The information transferred by this function is signed unless signing has been turned off for the system, but no encryption is performed.

When you update access rights of a folder indicated by an UNC path, for example \Test\TestFolder, the original inherited ACE is removed and the full volume path is not included.

Examples

For an example that uses this function, see Modifying the ACLs of an Object or Taking Object Ownership.

Note

The aclapi.h header defines SetNamedSecurityInfo as an alias which 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 not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.