pthread_create()

Create a thread

Synopsis:

#include <pthread.h>

int pthread_create( pthread_t* thread,
                    const pthread_attr_t* attr,
                    void* (*start_routine)(void* ),
                    void* arg );

Arguments:

thread
NULL, or a pointer to a pthread_t object where the function can store the thread ID of the new thread.
attr
A pointer to a pthread_attr_t structure that specifies the attributes of the new thread. Instead of manipulating the members of this structure directly, use pthread_attr_init() and the pthread_attr_set_* functions. For the exceptions, see "QNX Neutrino extensions," below.

If attr is NULL, the default attributes are used (see pthread_attr_init()).

Note: If you modify the attributes in attr after creating the thread, the thread's attributes aren't affected.
start_routine
The routine where the thread begins, with arg as its only argument. If start_routine() returns, there's an implicit call to pthread_exit(), using the return value of start_routine() as the exit status.

The thread in which main() was invoked behaves differently. When it returns from main(), there's an implicit call to exit(), using the return value of main() as the exit status.

arg
The argument to pass to start_routine.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The pthread_create() function creates a new thread, with the attributes specified in the thread attribute object attr. The created thread inherits the signal mask of the parent thread, and its set of pending signals is empty.

Note:
  • You must call pthread_join() or pthread_detach() for threads created with a detachstate attribute of PTHREAD_CREATE_JOINABLE (the default) before all of the resources associated with the thread can be released at thread termination.
  • If you set the __stacksize member of attr, the thread's actual stack size is rounded up to a multiple of the system page size (which you can get by using the _SC_PAGESIZE constant in a call to sysconf()) if the system allocates the stack (the __stackaddr member of attr is set to NULL). If the stack was previously allocated by the application, its size isn't changed.

QNX Neutrino extensions

If you adhere to the POSIX standard, there are some thread attributes that you can't specify before creating the thread:

There are no pthread_attr_set_* functions for these attributes.

As a QNX Neutrino extension, you can OR the following bits into the __flags member of the pthread_attr_t structure before calling pthread_create():

PTHREAD_CANCEL_ENABLE
Cancellation requests may be acted on according to the cancellation type (the default).
PTHREAD_CANCEL_DISABLE
Cancellation requests are held pending.
PTHREAD_CANCEL_ASYNCHRONOUS
If cancellation is enabled, new or pending cancellation requests may be acted on immediately.
PTHREAD_CANCEL_DEFERRED
If cancellation is enabled, cancellation requests are held pending until a cancellation point (the default).
PTHREAD_MULTISIG_ALLOW
Terminate all the threads in the process (the POSIX default).
PTHREAD_MULTISIG_DISALLOW
Terminate only the thread that received the signal.

After creating the thread, you can change the cancellation properties by calling pthread_setcancelstate() and pthread_setcanceltype().

Returns:

EAGAIN
Insufficient system resources to create thread.
EFAULT
An error occurred trying to access the buffers or the start_routine provided.
EINVAL
Invalid thread attribute object attr.
EOK
Success.

Examples:

Create a thread in a detached state:

#include <stdio.h>
#include <stdlib.h>
#include <pthread.h>

void*  function( void*  arg )
{
   printf( "This is thread %d\n", pthread_self() );
   return( 0 );
}

int main( void )
{
   pthread_attr_t attr;

   pthread_attr_init( &attr );
   pthread_attr_setdetachstate(
      &attr, PTHREAD_CREATE_DETACHED );
   pthread_create( NULL, &attr, &function, NULL );

   /* Allow threads to run for 60 seconds. */
   sleep( 60 );
   return EXIT_SUCCESS;
}

Classification:

POSIX 1003.1

Safety:  
Cancellation point No
Interrupt handler No
Signal handler Yes
Thread Yes