CreateThread Function (Windows API)

Syntax

HANDLE CreateThread(
                    LPSECURITY_ATTRIBUTES lpThreadAttributes,
                    SIZE_T dwStackSize,
                    LPTHREAD_START_ROUTINE lpStartAddress,
                    LPVOID lpParameter,
                    DWORD dwCreationFlags,
                    LPDWORD lpThreadId
                );

Parameters

Parameter	Description
`lpThreadAttributes`	A pointer to a `SECURITY_ATTRIBUTES` structure that specifies the security attributes of the new thread. If this parameter is NULL, the thread gets a default security descriptor. The default security descriptor for threads grants all access rights to the first unrestricted user that opened the system. If `lpThreadAttributes` is NULL, the handle cannot be inherited by the child process. If the first element of the `lpSecurityDescriptor` member of the structure is a valid handle to a security descriptor, then the security descriptor is used as the security descriptor for the new thread. If the first element of `lpSecurityDescriptor` is NULL, the function uses the security descriptor of the creating process as the security descriptor of the new thread.
`dwStackSize`	The initial size, in bytes, of the stack for the new thread. If this parameter is 0, the function uses the default size for the stack of the calling process. The default stack size is 1 megabyte. For more information, see Stack Sizes.
`lpStartAddress`	A pointer to the application-defined function of type `LPTHREAD_START_ROUTINE` that the thread is to execute. This pointer cannot be NULL. `DWORD WINAPI ThreadProc( LPVOID lpParam );`
`lpParameter`	A pointer to a variable to be passed to the thread function.
`dwCreationFlags`	The flags that control the thread's creation. This parameter can be one of the following values: 0: The thread runs immediately after creation. `CREATE_SUSPENDED` (0x00000004): The thread is created in a suspended state. Use the `ResumeThread` function to initiate its execution. `STACK_SIZE_PARAM_IS_A_RESERVATION` (0x00010000): If `dwStackSize` is not 0, this flag indicates that it is a reservation, not a commit. This flag is recommended for 32-bit systems.
`lpThreadId`	A pointer to a 32-bit value that receives the thread identifier of the new thread. If this parameter is NULL, the thread identifier is not returned.

Return Value

If the function succeeds, the return value is a handle to the new thread. Each thread has a unique handle that can be used with various functions.

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

Remarks

A thread in a process shares the same address space as the process. A thread object is created and runs within the context of the process.

The thread function (specified by lpStartAddress) should be of type LPTHREAD_START_ROUTINE. This function receives a single parameter, lpParameter, and should return a 32-bit value. This return value is the exit code of the thread. The calling thread can use the GetExitCodeThread function to retrieve this value.

The handle returned by CreateThread can be used to specify the thread in any function that requires a thread handle, such as the synchronization functions. The handle is created with full access rights to the new thread.

To close a thread handle, call CloseHandle. It is not necessary to close the handle when a thread terminates.

If you are creating a thread for a process that is being debugged, the debugger can use the DEBUG_ONLY_THIS_PROCESS flag to specify that the thread should only be created when the process is being debugged.

Requirements

Component	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	`threadpoolapis.h` (include `windows.h`)
Library	`User32.lib`
DLL	`User32.dll`

MSDN Documentation