PTHREAD_CREATE(3P)                                  POSIX Programmer's Manual                                 PTHREAD_CREATE(3P)



PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may differ (con-
       sult the corresponding Linux manual page for details of Linux behavior), or the  interface  may  not  be  implemented  on
       Linux.

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 num-
              ber 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  applica-
       tions  would  find  such  behavior more natural. Ada, in particular, separates the "creation" of a task from its "activa-
       tion".

       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 facili-
          ties that are currently provided. The start_routine() can synchronize by waiting on a condition variable that is  sig-
          naled 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  cre-
       ated 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  func-
          tion  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  seman-
       tics  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  architec-
          tures 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, Copy-
       right (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.open-
       group.org/unix/online.html .



IEEE/The Open Group                                           2003                                            PTHREAD_CREATE(3P)