> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XSystemHandleTrack

> XSystemHandleTrack

# XSystemHandleTrack

Registers a callback to track handle lifetime events in the Gaming Runtime.

## Syntax

```cpp theme={null}
HRESULT XSystemHandleTrack(
  XSystemHandleCallback callback,
  void * context
)
```

### Parameters

*callback*    \_In\_\
Type: [XSystemHandleCallback](/reference/system/xsystem/functions/xsystemhandlecallback)

A user defined callback that will be called on handle creation and destruction. To disable handle
tracking pass in NULL for the callback.

*context*    \_In\_opt\_\
Type: void \*

User define context to be passed to the callback.

### Return value

Type:  [HRESULT](https://learn.microsoft.com/openspecs/windows_protocols/ms-erref/0642cb2f-2075-4469-918c-4441e69c548a)

Returns **S\_OK** if successful; otherwise, returns an error code. For a list of error codes, see
[Error Codes](/reference/errorcodes).

## Remarks

Game developers need to have the ability to troubleshoot bugs involving incorrect handle usage.
Most of the GRTS APIs utilize handles which correspond to the lifetime of internal objects in our
platform implementation. Games often encounter problems caused by developers accidentally
providing invalid (NULL, previously freed, etc.) handles into these APIs leading to title crashes.
Developers may also inadvertently leak handles leading to excessive resource usage. The goal of
the handle tracking API is to empower developers to diagnose and fix these issues.

The API has two components: active and passive. All handles created by GRTS are continuously
tracked for both debug and retail scenarios. Whenever handles are passed into our APIs, the
platform performs validation to ensure that these handles correspond to valid internal objects. If
an invalid handle is detected, the platform logs the error and invokes
[XErrorReport](/reference/system/xerror/functions/xerrorsetoptions) to notify the developer of the problem. The platform does not
make any additional effort to suppress the invalid handle usage and allow the application to crash
as it would have prior to this feature. Finally, any handle leaks at the time of
[XGameRuntimeUninitialize](/reference/system/xgameruntimeinit/functions/xgameruntimeuninitialize) will also be reported via
[XErrorReport](/reference/system/xerror/functions/xerrorsetoptions). At present, the handle tracking system does not enable the
tracking of handles which are external to GRTS.

## Requirements

**Header:** XSystem.h

**Library:** xgameruntime.lib

**Supported platforms:** Windows, XBOX One family consoles and XBOX Series consoles

## See also

[XSystem members](/reference/system/xsystem/xsystem_members)

[XSystemHandleCallback](/reference/system/xsystem/functions/xsystemhandlecallback)


## Related topics

- [XSystemHandleCallback](/reference/system/xsystem/functions/xsystemhandlecallback.md)
- [XSystem](/reference/system/xsystem/xsystem_members.md)
- [PHEAP_TRACK_FREE_ROUTINE callback](/reference/system/xmem/functions/pheap_track_free_routine.md)
- [PHEAP_TRACK_ALLOC_ROUTINE callback](/reference/system/xmem/functions/pheap_track_alloc_routine.md)
- [PHEAP_TRACK_REALLOC_ROUTINE callback](/reference/system/xmem/functions/pheap_track_realloc_routine.md)