GetLogicalProcessorInformationEx function (sysinfoapi.h)

Retrieves information about the relationships of logical processors and related hardware.

Syntax

BOOL GetLogicalProcessorInformationEx(
  [in]            LOGICAL_PROCESSOR_RELATIONSHIP           RelationshipType,
  [out, optional] PSYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX Buffer,
  [in, out]       PDWORD                                   ReturnedLength
);

Parameters

[in] RelationshipType

The type of relationship to retrieve. This parameter can be one of the following LOGICAL_PROCESSOR_RELATIONSHIP values.

[out, optional] Buffer

A pointer to a buffer that receives a sequence of variable-sized SYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX structures. If the function fails, the contents of this buffer are undefined.

[in, out] ReturnedLength

On input, specifies the length of the buffer pointed to by Buffer, in bytes. If the buffer is large enough to contain all of the data, this function succeeds and ReturnedLength is set to the number of bytes returned. If the buffer is not large enough to contain all of the data, the function fails, GetLastError returns ERROR_INSUFFICIENT_BUFFER, and ReturnedLength is set to the buffer length required to contain all of the data. If the function fails with an error other than ERROR_INSUFFICIENT_BUFFER, the value of ReturnedLength is undefined.

Return value

If the function succeeds, the return value is TRUE and at least one SYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX structure is written to the output buffer.

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

Remarks

If a 32-bit process running under WOW64 calls this function on a system with more than 64 processors, some of the processor affinity masks returned by the function may be incorrect. This is because the high-order DWORD of the 64-bit KAFFINITY structure that represents all 64 processors is "folded" into a 32-bit KAFFINITY structure in the caller's buffer. As a result, the affinity masks for processors 32 through 63 are incorrectly represented as duplicates of the masks for processors 0 through 31. In addition, the affinity masks for processors 32 through 63 are incorrectly represented as duplicates of the masks for processors 0 through 31. In addition, the sum of all per-group ActiveProcessorCount and MaximumProcessorCount values reported in PROCESSOR_GROUP_INFO structures may exclude some active logical processors.

When this function is called with a relationship type of RelationProcessorCore, it returns a PROCESSOR_RELATIONSHIP structure for every active processor core in every processor group in the system. This is by design, because an unaffinitized 32-bit thread can run on any logical processor in a given group, including processors 32 through 63. A 32-bit caller can use the total count of PROCESSOR_RELATIONSHIP structures to determine the actual number of active processor cores on the system. However, the affinity of a 32-bit thread cannot be explicitly set to logical processor 32 through 63 of any processor group.

To compile an application that uses this function, set _WIN32_WINNT >= 0x0601. For more information, see Using the Windows Headers.

Behavior starting with Windows Server 2022 (21H2, build 20348)

The behavior of this and other NUMA functions has been modified to better support systems with nodes containing more that 64 processors. For more information about this change, including information about enabling the old behavior of this API, see NUMA Support.

Requests for RelationNumaNode will return NUMA_NODE_RELATIONSHIP structures that contain only the affinity of the node within it's primary group. The GroupCount value will be 1 and the structure size is fixed.

Requests for RelationNumaNodeEx or RelationAll will return NUMA_NODE_RELATIONSHIP structures that contain an array of affinities for the node over all groups. The GroupCount reports the number of affinities and the size of structure is variable.

Requirements

See also

SYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX