[Previous]
[Contents]
[Next]

_beginthread()

start a new thread of execution

Synopsis:

#include <process.h>

int _beginthread(
    register void ( *start_address)(void *),
    void *stack_bottom,
    unsigned stack_size,
    void *arglist );

Description:

The _beginthread() function starts a new thread of execution at the function identified by start_address with a single parameter given by arglist.


Note: The QNX libraries aren't completely thread-safe. Before calling a function in a thread, check its Classification section to make sure it's safe to do so.

The _beginthread() function uses tfork() to begin a new thread of execution; you should call _beginthread() instead of using tfork() directly.

The new thread uses the memory identified by stack_bottom and stack_size for its stack.


Note: The application doesn't need to provide memory for a stack; the stack_bottom may be NULL, in which case the runtime system provides a stack. You must specify a nonzero stack_size for this stack.

The thread ends when it exits from its main function or calls exit(), _exit() or _endthread().

The variable _threadid or function __threadid(), which are defined in <stddef.h>, may be used by the executing thread to obtain its thread ID. It's a pointer to an int.

Under QNX, the number of threads an application can create is limited by the number of processes.

Returns:

The thread ID for the new thread, or -1 if the thread couldn't be started.

Errors:

EAGAIN
There are too many threads.
EINVAL
The argument is invalid, or the stack size is incorrect.
ENOMEM
There isn't enough memory available.

Examples:

#include <stdio.h>
#include <stdlib.h>
#include <stddef.h>
#include <malloc.h>
#include <process.h>

#if defined(__386__)
  #define FAR
  #define STACK_SIZE   8192
#else
  #define FAR      __far
  #define STACK_SIZE   4096
#endif

static volatile int   WaitForThread;

void FAR child( void FAR *parm )
  {
    char * FAR *argv = (char * FAR *) parm;
    int  i;

    printf( "Child thread ID = %x\n", *_threadid );
    for( i = 0; argv[i]; i++ ) {
      printf( "argv[%d] = %s\n", i, argv[i] );
    }
    WaitForThread = 0;
    _endthread();
  }

int main( void )
{
    char      *args[3];
#if defined(__NT__)
    unsigned long   tid;
#else
    char      *stack;
    int        tid;
#endif

    args[0] = "child";
    args[1] = "parm";
    args[2] = NULL;
    WaitForThread = 1;
  #if defined(__386__)
    stack = (char *) malloc( STACK_SIZE );
  #else
    stack = (char *) _nmalloc( STACK_SIZE );
  #endif
    tid = _beginthread( child, stack, STACK_SIZE, args );
    printf( "Thread ID = %x\n", tid );
    while( WaitForThread ) {
      sleep( 0 );
    }
  return (EXIT_SUCCESS);
}

Classification:

WATCOM

Safety:
Interrupt handler No
Signal handler No
Thread Yes

See also:

_endthread()


[Previous]
[Contents]
[Next]