Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

GetFileSecurity function

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 GetNamedSecurityInfo function provides functionality similar to GetFileSecurity for files as well as other types of objects.

Syntax


BOOL WINAPI GetFileSecurity(
  _In_       LPCTSTR lpFileName,
  _In_       SECURITY_INFORMATION RequestedInformation,
  _Out_opt_  PSECURITY_DESCRIPTOR pSecurityDescriptor,
  _In_       DWORD nLength,
  _Out_      LPDWORD lpnLengthNeeded
);

Parameters

lpFileName [in]

A pointer to a null-terminated string that specifies the file or directory for which security information is retrieved.

RequestedInformation [in]

A SECURITY_INFORMATION value that identifies the security information being requested.

pSecurityDescriptor [out, optional]

A pointer to a buffer that receives a copy of the security descriptor of the object specified by the lpFileName parameter. The calling process must have permission to view the specified aspects of the object's security status. The SECURITY_DESCRIPTOR structure is returned in self-relative security descriptor format.

nLength [in]

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

lpnLengthNeeded [out]

A pointer to the variable that receives the number of bytes necessary to store the complete security descriptor. If the returned number of bytes is less than or equal to nLength, the entire security descriptor is returned in the output buffer; otherwise, none of the descriptor is returned.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

To read the owner, group, or DACL from the security descriptor for the specified file or directory, the DACL for the file or directory must grant READ_CONTROL access to the caller, or the caller must be the owner of the file or directory.

To read the SACL of a file or directory, the SE_SECURITY_NAME privilege must be enabled for the calling process.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Winbase.h (include Windows.h)

Library

Advapi32.lib

DLL

Advapi32.dll

Unicode and ANSI names

GetFileSecurityW (Unicode) and GetFileSecurityA (ANSI)

See also

Low-level Access Control
Low-level Access Control Functions
GetKernelObjectSecurity
GetNamedSecurityInfo
GetPrivateObjectSecurity
GetUserObjectSecurity
SECURITY_DESCRIPTOR
SECURITY_INFORMATION
SetFileSecurity

 

 

Community Additions

Show:
© 2014 Microsoft