_beginthread

Header File

process.h

Category

Process Control Routines

Prototype

unsigned long _beginthread(void (_USERENTRY *__start)(void *), unsigned __stksize, void *__arg);

Description

Starts execution of a new thread.

Note:

The start_address must be declared to be _USERENTRY.

The _beginthread function creates and starts a new thread. The thread starts execution at start_address.

The size of its stack in bytes is stack_size; the stack is allocated by the operating system after the stack size is rounded up to the next multiple of 4096. The thread is passed arglist as its only parameter; it can be NULL, but must be present. The thread function should terminate by simply returning; the _endthread. function will be called automatically. The _endthread function will automatically close the handle, and set the return value of the thread to zero.

Either this function or _beginthreadNT must be used instead of the operating system thread-creation API function because _beginthread and _beginthreadNT perform initialization required for correct operation of the runtime library functions.

This function is available only in the multithread libraries.

Return Value

_beginthread returns the handle of the new thread. The return value is a standard Windows handle that can be used in operating system API's such as SuspendThread and ResumeThread.

On error, the function returns -1, and the global variable errno is set to one of the following values:

EAGAIN

Too many threads

EINVAL

Invalid stack size (i.e. less than 16 bytes, or equal to zero)

ENOMEM

Not enough memory

Also see the description of the Win32 API GetLastError, in the MSDN Library.

Example/* Use the -tWM (32-bit multi-threaded target) command-line switch for this example */
#include
#include
#include /* _threadid variable */
#include /* _beginthread, _endthread */
#include /* time, _ctime */
void thread_code(void *threadno)
{
time_t t;
time(&t);
printf("Executing thread number %d, ID = %d, time = %s/n",
(int)threadno, _threadid, ctime(&t));

}

void start_thread(int i)
{
int thread_id;
#if defined(__WIN32__)
if ((thread_id = _beginthread(thread_code,4096,(void *)i)) == (unsigned long)-1)
#else
if ((thread_id = _beginthread(thread_code,4096,(void *)i)) == -1)
#endif
{
printf("Unable to create thread %d, errno = %d/n",i,errno);
return;
}
printf("Created thread %d, ID = %ld/n",i,thread_id);
}
int main(void)
{
int i;
for (i = 1; i < 20; i++)
start_thread(i);
printf("Hit ENTER to exit main thread./n");
getchar();
return 0;
}

CreateThread Function

Creates a thread to execute within the virtual address space of the calling process.

To create a thread that runs in the virtual address space of another process, use the CreateRemoteThread function.HANDLE WINAPI CreateThread(
__in_opt LPSECURITY_ATTRIBUTES lpThreadAttributes,
__in SIZE_T dwStackSize,
__in LPTHREAD_START_ROUTINE lpStartAddress,
__in_opt LPVOID lpParameter,
__in DWORD dwCreationFlags,
__out_opt LPDWORD lpThreadId
); Parameters lpThreadAttributes

A pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpThreadAttributes is NULL, the handle cannot be inherited.

The lpSecurityDescriptor member of the structure specifies a security descriptor for the new thread. If lpThreadAttributes is NULL, the thread gets a default security descriptor. The ACLs in the default security descriptor for a thread come from the primary token of the creator. Windows XP/2000:The ACLs in the default security descriptor for a thread come from the primary or impersonation token of the creator. This behavior changed with Windows XP SP2 and Windows Server 2003. For more information, see Remarks. dwStackSize

The initial size of the stack, in bytes. The system rounds this value to the nearest page. If this parameter is zero, the new thread uses the default size for the executable. For more information, see Thread Stack Size. lpStartAddress

A pointer to the application-defined function to be executed by the thread. This pointer represents the starting address of the thread. For more information on the thread function, see ThreadProc. lpParameter

A pointer to a variable to be passed to the thread. dwCreationFlags

The flags that control the creation of the thread. If the CREATE_SUSPENDED flag is specified, the thread is created in a suspended state, and will not run until the ResumeThread function is called. If this value is zero, the thread runs immediately after creation.

If the STACK_SIZE_PARAM_IS_A_RESERVATION flag is specified, the dwStackSize parameter specifies the initial reserve size of the stack. Otherwise, dwStackSize specifies the commit size. Windows 2000:The STACK_SIZE_PARAM_IS_A_RESERVATION flag is not supported. lpThreadId

A pointer to a variable that receives the thread identifier. If this parameter is NULL, the thread identifier is not returned.

If the function succeeds, the return value is a handle to the new thread.

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