pthread_create

Send feedback |  Rate this page

---

pthread_create()--Create Thread

Syntax: #include <pthread.h> int pthread_create(pthread_t *thread, const pthread_attr_t *attr, void *(*start_routine)(void *), void *arg);   Service Program Name: QP0WPTHR   Default Public Authority: *USE   Threadsafe: Yes   Signal Safe: Yes

The pthread_create() function creates a thread with thespecified attributes and runs the C function start_routine in thethread with the single pointer argument specified. The new thread may, but doesnot always, begin running before pthread_create() returns. Ifpthread_create() completes successfully, the Pthread handle isstored in the contents of the location referred to by thread.

If the start_routine returns normally, it is as if there was animplicit call to pthread_exit() using the return value of start_routine as the status. The function passed as start_routineshould correspond to the following C function prototype:

void *threadStartRoutinName(void *);

If the thread attributes object represented by attr is modifiedlater, the newly created thread is not affected. If attr is NULL, the default thread attributes are used.

With the following declarations and initialization,

pthread_t t;
void *foo(void *);
pthread_attr_t attr;
pthread_attr_init(&pta);

the following two thread creation mechanisms are functionallyequivalent:

rc = pthread_create(&t, NULL, foo, NULL);

rc = pthread_create(&t, &attr, foo, NULL);

The cancellation state of the new thread is PTHREAD_CANCEL_ENABLE. The cancellation type of the new thread isPTHREAD_CANCEL_DEFERRED.

The signal information maintained in the new thread is as follows:

• The signal mask is inherited from the creating thread.
• The set of signals pending for the new thread is empty.

If you attempt to create a thread in a job that is not capable of startingthreads, pthread_create() fails with the EBUSY error. If you attempt to create a thread from a location inwhich thread creation is not allowed, pthread_create() failswith the EBUSY error. See the pthread_getpthreadoption_np() function, option PTHREAD_OPTION_THREAD_CAPABLE_NP, for details about how to determinewhether thread creation is currently allowed in your process.

In the OS/400 implementation, the initial thread is special. Termination ofthe initial thread by pthread_exit() or any other threadtermination mechanism terminates the entire process.

The OS/400 implementation does not set a hard limit on the number of threadsthat can be created. The PTHREAD_THREADS_MAX macro isimplemented as a function call, and returns different values depending on theadministrative setting of the maximum number of threads for the process. Thedefault is NO MAX and has the numeric value of 2147483647 (0x7FFFFFFF).Realistically, the number of threads is limited by the amount of storageavailable to the job.

Currently, thread creation is not allowed after process termination has beenstarted. For example, after a call to exit(), destructors forC++ static objects, functions registered with atexit() orCEE4RAGE() are allowed to run. If these functions attempt tocreate a thread, pthread_create() fails with the EBUSY error. Similar failures occur if other mechanisms are used tocall pthread_create() after process termination hasstarted.

Usage Notes

1. If you attempt to create a thread in a job that is not capable of startingthreads or for some other reason, thread creation is not allowed, and pthread_create() fails with the EBUSY error.
2. For the best performance during thread creation, you should always usepthread_join() or pthread_detach(). Thisallows resources to be reclaimed or reused when the thread terminates.
3. The OS/400 implementation of threads allows the user ID to be changed on aper-thread basis. If, at the time the application creates the first thread, theapplication has not associated a process user identity with the job, the systemuses the identity of the current user to set the process user identity for thejob. The process user identity is used by some operating system support whenoperations that require authorization checks are done against a multithreadedjob from outside that job. The application can set the process user identityusing the Set Job User Identify (QWTSJUID) or QwtSetJuid() Set Job User Identity APIs. See the Security APIs for more details.

Authorities and Locks

None.

Parameters

thread

(Output) Pthread handle to the created thread

attr

(Input) The thread attributes object containing the attributes to beassociated with the newly created thread. If NULL, the defaultthread attributes are used.

start_routine

(Input) The function to be run as the new threads start routine

arg

(Input) An address for the argument for the threads start routine

Return Value

0

pthread_create() was successful.

value

pthread_create() was not successful. value is setto indicate the error condition.

Error Conditions

If pthread_create() was not successful, the error conditionreturned usually indicates one of the following errors. Under some conditions,the value returned could indicate an error other than those listed here.

[EINVAL]

The value specified for the argument is not correct.

[EAGAIN]

The system did not have enough resources to create another thread or the maximum number of threads for this job has been reached.

[EBUSY]

The system cannot allow thread creation in thisprocess at this time.

Related Information

• The <pthread.h> header file. See Header files for Pthread functions.
  
  
• pthread_exit()--Terminate Calling Thread
  
  
• pthread_cancel()--Cancel Thread
  
  
• pthread_detach()--Detach Thread
  
  
• pthread_join()--Wait for and Detach Thread

Example

See Code disclaimer information for information pertaining to code examples.

#define _MULTI_THREADED
#include <pthread.h>
#include <stdio.h>
#include "check.h"

typedef struct {
  int   value;
  char  string[128];
} thread_parm_t;

void *threadfunc(void *parm)
{
  thread_parm_t *p = (thread_parm_t *)parm;
  printf("%s, parm = %d\n", p->string, p->value);
  free(p);
  return NULL;
}

int main(int argc, char **argv)
{
  pthread_t             thread;
  int                   rc=0;
  pthread_attr_t        pta;
  thread_parm_t         *parm=NULL;

  printf("Enter Testcase - %s\n", argv[0]);

  printf("Create a thread attributes object\n");
  rc = pthread_attr_init(&pta);
  checkResults("pthread_attr_init()\n", rc);

  /* Create 2 threads using default attributes in different ways */
  printf("Create thread using the NULL attributes\n");
  /* Set up multiple parameters to pass to the thread */
  parm = malloc(sizeof(thread_parm_t));
  parm->value = 5;
  strcpy(parm->string, "Inside secondary thread");
  rc = pthread_create(&thread, NULL, threadfunc, (void *)parm);
  checkResults("pthread_create(NULL)\n", rc);

  printf("Create thread using the default attributes\n");
  /* Set up multiple parameters to pass to the thread */
  parm = malloc(sizeof(thread_parm_t));
  parm->value = 77;
  strcpy(parm->string, "Inside secondary thread");
  rc = pthread_create(&thread, &pta, threadfunc, (void *)parm);
  checkResults("pthread_create(&pta)\n", rc);

  printf("Destroy thread attributes object\n");
  rc = pthread_attr_destroy(&pta);
  checkResults("pthread_attr_destroy()\n", rc);

  /* sleep() is not a very robust way to wait for the thread */
  sleep(5);

  printf("Main completed\n");
  return 0;
}

Output:

Enter Testcase - QP0WTEST/TPCRT0
Create a thread attributes object
Create thread using the NULL attributes
Create thread using the default attributes
Destroy thread attributes object
Inside secondary thread, parm = 77
Inside secondary thread, parm = 5
Main completed

---

API introduced: V4R3

---

Top | Pthread APIs | APIs bycategory