Unix/Linux Go Back    


Linux 2.6 - man page for pthread_create (linux section 3posix)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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

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  ref-
       erenced by thread are undefined.

       If  _POSIX_THREAD_CPUTIME  is defined, the new thread shall have a CPU-time clock accessi-
       ble, 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 partic-
       ular, 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 synchro-
	  nization. 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 pro-
       gram: 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 condi-
       tion 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 modi-
       fied 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 orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003				PTHREAD_CREATE(P)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 05:04 PM.