NAME

       pthread_create - thread creation

SYNOPSIS

       #include <pthread.h>

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

DESCRIPTION

       The  pthread_create()  function  shall  create  a new thread, with attributes specified by
       attr, within a process. If attr is NULL, the default attributes  shall  be  used.  If  the
       attributes  specified  by  attr  are  modified later, the thread's attributes shall not be
       affected. Upon successful completion, pthread_create() shall store the ID of  the  created
       thread in the location referenced by thread.

       The  thread  is  created  executing  start_routine  with  arg as its sole argument. If the
       start_routine returns,  the  effect  shall  be  as  if  there  was  an  implicit  call  to
       pthread_exit()  using  the return value of start_routine as the exit status. Note that the
       thread in which main() was originally invoked differs from  this.  When  it  returns  from
       main(),  the  effect  shall be as if there was an implicit call to exit() using the return
       value of main() as the exit status.

       The signal state of the new thread shall be initialized as follows:

        * The signal mask shall be inherited from the creating thread.

        * The set of signals pending for the new thread shall be empty.

       The alternate stack shall not be inherited.

       The floating-point environment shall be inherited from the creating thread.

       If pthread_create() fails, no new thread is created  and  the  contents  of  the  location
       referenced by thread are undefined.

       If  _POSIX_THREAD_CPUTIME  is  defined,  the  new  thread  shall  have  a  CPU-time  clock
       accessible, and the initial value of this clock shall be set to zero.

RETURN VALUE

       If successful, the pthread_create() function shall return zero; otherwise, an error number
       shall be returned to indicate the error.

ERRORS

       The pthread_create() function shall fail if:

       EAGAIN The  system lacked the necessary resources to create another thread, or the system-
              imposed limit on the total number of threads  in  a  process  {PTHREAD_THREADS_MAX}
              would be exceeded.

       EINVAL The value specified by attr is invalid.

       EPERM  The  caller  does  not  have  appropriate permission to set the required scheduling
              parameters or scheduling policy.

       The pthread_create() function shall not return an error code of [EINTR].

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       None.

RATIONALE

       A suggested alternative to pthread_create() would be to define  two  separate  operations:
       create  and  start.  Some  applications  would  find  such  behavior more natural. Ada, in
       particular, separates the "creation" of a task from its "activation".

       Splitting the operation was rejected by the standard developers for many reasons:

        * The number of calls required to start a thread would increase from one to two and  thus
          place  an  additional  burden  on  applications  that  do  not  require  the additional
          synchronization.  The  second  call,  however,  could  be  avoided  by  the  additional
          complication of a start-up state attribute.

        * An  extra  state would be introduced: "created but not started". This would require the
          standard to specify the behavior of the thread operations when the target has  not  yet
          started executing.

        * For  those  applications that require such behavior, it is possible to simulate the two
          separate steps with the facilities that are currently provided. The start_routine() can
          synchronize by waiting on a condition variable that is signaled by the start operation.

       An  Ada  implementor  can  choose  to create the thread at either of two points in the Ada
       program: when the task object is created, or when the task is activated  (generally  at  a
       "begin").  If  the  first  approach  is  adopted,  the  start_routine() needs to wait on a
       condition variable to receive the  order  to  begin  "activation".   The  second  approach
       requires  no  such  condition  variable  or  extra  synchronization. In either approach, a
       separate Ada task control block would need to be created when the task object  is  created
       to hold rendezvous queues, and so on.

       An  extension  of  the  preceding  model  would  be to allow the state of the thread to be
       modified between the create and start. This would allow the thread attributes object to be
       eliminated. This has been rejected because:

        * All state in the thread attributes object has to be able to be set for the thread. This
          would require the definition of functions to modify thread attributes. There  would  be
          no  reduction  in the number of function calls required to set up the thread.  In fact,
          for an application that creates all threads using identical attributes, the  number  of
          function calls required to set up the threads would be dramatically increased. Use of a
          thread attributes object permits the application to make one set of  attribute  setting
          function calls. Otherwise, the set of attribute setting function calls needs to be made
          for each thread creation.

        * Depending on the implementation architecture,  functions  to  set  thread  state  would
          require  kernel  calls,  or  for  other  implementation reasons would not be able to be
          implemented as macros, thereby increasing the cost of thread creation.

        * The ability for applications to segregate threads by class would be lost.

       Another suggested alternative uses a model similar to that for process creation,  such  as
       "thread fork". The fork semantics would provide more flexibility and the "create" function
       can be implemented simply by doing a thread fork followed immediately by  a  call  to  the
       desired "start routine" for the thread. This alternative has these problems:

        * For  many  implementations,  the  entire  stack  of the calling thread would need to be
          duplicated, since in many architectures there is no way to determine the  size  of  the
          calling frame.

        * Efficiency  is  reduced  since  at  least some part of the stack has to be copied, even
          though in most cases the thread never needs the copied context, since it  merely  calls
          the desired start routine.

FUTURE DIRECTIONS

       None.

SEE ALSO

       fork()   ,   pthread_exit()   ,   pthread_join()   ,   the   Base  Definitions  volume  of
       IEEE Std 1003.1-2001, <pthread.h>

COPYRIGHT

       Portions of this text are reprinted and  reproduced  in  electronic  form  from  IEEE  Std
       1003.1,  2003  Edition,  Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard,  the  original  IEEE  and  The  Open Group Standard is the referee document. The
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .