SetLastError

SetLastError is a Windows API function that sets the calling thread's last-error code, a thread-local DWORD. The last-error code is used in conjunction with GetLastError to convey detailed error information from Windows API calls to the caller. Applications typically rely on the return value of a function to determine success or failure and then query the last error only when a failure is indicated.

The function signature is VOID SetLastError(DWORD dwErrCode). The value is stored in thread-local storage and is intended to be consumed by GetLastError immediately after a function reports failure. In normal application code, SetLastError is not often called directly; it is more commonly used by system and library code or during error mapping between layers.

Usage guidelines emphasize that when a Windows API fails, it usually returns a failure indicator (such as FALSE, 0, or INVALID_HANDLE_VALUE) and sets the thread's last-error code. You should call GetLastError right after the failure to obtain the error code. Do not call other functions in between, as subsequent calls may modify the last error. If a function succeeds, its last-error value should not be relied upon; it may be stale or unrelated. To clear a previous error state, you can call SetLastError(0), though not all code relies on a zero value.

Scope and caveats include that the last-error value is per-thread and is not preserved across process boundaries or certain asynchronous boundaries. It is not meaningful across threads, as a new thread starts with its own last-error value. The error code is a Windows error value (DWORD), with common examples such as ERROR_FILE_NOT_FOUND or ERROR_ACCESS_DENIED.

See also: GetLastError; Windows error codes.