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 extensions,” below.

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

---

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.

---

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 extensions

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

• You can't disable cancellation for a thread.
• You can't set the thread's cancellation type.
• You can't specify what happens when a signal is delivered to the thread.

There are no pthread_attr_set_* functions for these attributes.

As an QNX 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 THR

See also:

pthread_attr_init(), pthread_exit(), pthread_setcancelstate(), pthread_setcanceltype(), sysconf(), ThreadCreate()

Processes and Threads chapter of Getting Started with QNX Neutrino