GetFileSecurity

	BOOL GetFileSecurity(lpFileName, RequestedInformation, pSecurityDescriptor, nLength, lpnLengthNeeded)
	LPTSTR lpFileName;
	SECURITY_INFORMATION RequestedInformation;
	PSECURITY_DESCRIPTOR pSecurityDescriptor;
	DWORD nLength;
	LPDWORD lpnLengthNeeded;

The GetFileSecurity function obtains specified information about the security of a file or directory. The information obtained is constrained by the caller's access rights and privileges.

The GetFileSecurity function fills the buffer pointed to by pSecurityDescriptor with a copy of the file or directory's security descriptor containing the requested security descriptor fields, based on the caller's access rights and privileges. In order to read the file or directory's security descriptor, the caller must have READ_CONTROL access or be the owner of the file or directory. Additionally, the caller must have SeSecurityPrivilege privilege to read the system ACL.

The GetFileSecurity function may be used as either a wide-character function (where text arguments must use Unicode) or an ANSI function (where text arguments must use characters from the Windows 3.x character set installed).

Parameters

lpFileName

Pointer to a zero-terminated string that names the file or directory whose security this function will obtain.

RequestedInformation

A SECURITY_INFORMATION data structure that specifies the security information being requested.

The SECURITY_INFORMATION data structure has the following form:

typedef ULONG SECURITY_INFORMATION;

pSecurityDescriptor

A pointer to a buffer that the function will fill with a copy of the security descriptor of the object specified by lpFileName. As noted above, the caller must have the right to view the specified aspects of the object's security status. The SECURITY_DESCRIPTOR data structure is returned in self-relative format.

The SECURITY_DESCRIPTOR data structure has the following form:

typedef PVOID PSECURITY_DESCRIPTOR;

nLength

Specifies the size in bytes of the buffer pointed to by pSecurityDescriptor.

lpnLengthNeeded

Pointer to a variable that the function will set to the number of bytes needed to store the complete security descriptor. If the value set is less than or equal to nLength, then the entire security descriptor is returned in the buffer pointed to by pSecurityDescriptor. Otherwise none of the descriptor is returned.

Return Value

The return value is TRUE if the function was successful, or FALSE if an error occurred. Use the GetLastError function to obtain extended error information.

Comments

The function will fail if access is denied or if the buffer pointed to by pSecurityDescriptor is too small to hold the security descriptor.