pthread_create man page on DigitalUNIX

Printed from http://www.polarhome.com/service/man/?qf=pthread_create&af=0&tf=2&of=DigitalUNIX

pthread_create(3)					     pthread_create(3)

NAME
       pthread_create - Creates a thread

SYNOPSIS
       #include <pthread.h>

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

LIBRARY
       DECthreads POSIX 1003.1c Library (libpthread.so)

STANDARDS
       Interfaces  documented on this reference page conform to industry stan‐
       dards as follows:

       IEEE Std 1003.1c-1995, POSIX System Application Program Interface

PARAMETERS
       Location for thread object to be	 created.   Thread  attributes	object
       that  defines  the  characteristics of the thread being created. If you
       specify NULL, default attributes are used.  Function  executed  as  the
       new  thread's  start  routine.	Address value copied and passed to the
       thread's start routine.

DESCRIPTION
       This routine creates a thread.  A thread is a single,  sequential  flow
       of control within a program. It is the active execution of a designated
       routine, including any nested routine invocations.

       Successful execution of this routine includes  the  following  actions:
       DECthreads  creates a thread object to describe and control the thread.
       The thread object includes a thread environment block (TEB)  that  pro‐
       grams  can  use, with care. (See the <sys/types.h> header file on Tru64
       UNIX, or the pthread.h header file on other DECthreads platforms.)  The
       thread  argument	 receives  an  identifier for the new thread.  An exe‐
       cutable thread is created with attributes specified by the  attr	 argu‐
       ment (or with default attributes if NULL is specified).

   Thread Creation
       DECthreads  creates  a  thread  in  the	“ready” state and prepares the
       thread to begin executing its start routine,  the  function  passed  to
       pthread_create(3) as the start_routine argument. Depending on the pres‐
       ence of other threads and their scheduling and priority attributes, the
       new  thread  might start executing immediately. The new thread can also
       preempt its creator, depending on the two threads' respective  schedul‐
       ing  and	 priority attributes. The caller of pthread_create(3) can syn‐
       chronize with the new thread using the pthread_join(3) routine or using
       any mutually agreed upon mutexes or condition variables.

       For  the	 duration  of the new thread's existence, DECthreads maintains
       and manages the thread object and other thread state overhead. A thread
       “exists” until it is both terminated and detached. A thread is detached
       when created if the detachstate attribute of its thread object  is  set
       to  PTHREAD_CREATE_DETACHED.   It  is  also  detached  after any thread
       returns successfully from calling pthread_detach(3) or  pthread_join(3)
       for  the	 thread.  Termination  is  explained  in the next section (see
       Thread Termination).

       DECthreads assigns each new thread  a  thread  identifier,  which  DEC‐
       threads writes into the address specified as the pthread_create(3) rou‐
       tine's thread argument. DECthreads writes the new thread's thread iden‐
       tifier before the new thread executes.

       By  default, the new thread's scheduling policy and priority are inher‐
       ited from the creating thread--that is, by  default,  the  pthread_cre‐
       ate(3)  routine	ignores	 the scheduling policy and priority set in the
       specified thread attributes object. Thus, to create a  thread  that  is
       subject	to  the	 scheduling  policy  and priority set in the specified
       thread attributes object, before calling pthread_create(3) your program
       must use the pthread_attr_setinheritsched(3) routine to set the inherit
       thread	  attributes	 object's     scheduling     attribute	    to
       PTHREAD_EXPLICIT_SCHED.

       On  Tru64  UNIX,	 the  signal state of the new thread is initialized as
       follows: The signal mask is inherited from the  creating	 thread.   The
       set of signals pending for the new thread is empty.

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

   Thread Termination
       A thread terminates when one of the following events occurs: The thread
       returns	from  its start routine.  The thread calls the pthread_exit(3)
       routine.	 The thread is canceled.

       When a thread terminates, DECthreads performs these actions: DECthreads
       writes  a  return  value	 (if  one  is  available)  into the terminated
       thread's thread object, as follows: If the thread  has  been  canceled,
       DECthreads  writes  the value PTHREAD_CANCELED into the thread's thread
       object.	If the thread terminated by returning from its start  routine,
       DECthreads  copies  the	return value from the start routine (if one is
       available) into the  thread's  thread  object.  Alternatively,  if  the
       thread  explicitly  called pthread_exit(3), DECthreads stores the value
       received in the value_ptr  argument  (from  pthread_exit(3))  into  the
       thread's thread object.	Another thread can obtain this return value by
       joining with the terminated thread  (using  pthread_join(3)).   If  the
       thread  terminated by returning from its start routine normally and the
       start routine does not provide a return value, the results obtained  by
       joining with that thread are unpredictable.  If the termination results
       from a cancellation request or a call  to  pthread_exit(3),  DECthreads
       calls,  in  turn, each cleanup handler that this thread declared (using
       pthread_cleanup_push(3))	 and  that   is	  not	yet   removed	(using
       pthread_cleanup_pop(3)).	 (DECthreads  also  transfers  control	to any
       appropriate CATCH, CATCH_ALL, or FINALLY blocks. DECthreads  calls  the
       terminated  thread's  most  recently pushed cleanup handler first.  For
       C++ programmers: At normal exit from a thread, your program  will  call
       the  appropriate destructor functions, just as if an exception had been
       raised.	 To  exit  the	terminated   thread   due   to	 a   call   to
       pthread_exit(3),	 DECthreads  raises  the  pthread_exit_e exception. To
       exit the terminated thread due to cancellation, DECthreads  raises  the
       pthread_cancel_e	 exception. Your program can use the DECthreads excep‐
       tion package to operate on the  generated  exception.  (In  particular,
       note   that   the   practice  of	 using	CATCH  handlers	 in  place  of
       pthread_cleanup_push(3) is not portable.)  For each of  the  terminated
       thread's	 thread-specific  data	keys  that  has a non-NULL value: DEC‐
       threads sets the thread's value for the corresponding key to NULL.   In
       turn, DECthreads calls each thread-specific data destructor function in
       this multithreaded process's list of  destructors.  DECthreads  repeats
       this step until all thread-specific data values in the thread are NULL,
       or for up to a number of iterations equal to  PTHREAD_DESTRUCTOR_ITERA‐
       TIONS.  This destroys all thread-specific data associated with the ter‐
       minated thread.	DECthreads awakens the thread (if there is  one)  that
       is  currently waiting to join with the terminated thread. That is, DEC‐
       threads	awakens	 the  thread  that   is	  waiting   in	 a   call   to
       pthread_join(3).	   If  the  thread  is	already	 detached,  DECthreads
       destroys its thread object. Otherwise, the thread  continues  to	 exist
       until detached or joined with.

RETURN VALUES
       If  an  error  condition	 occurs, no thread is created, the contents of
       thread are undefined, and this routine returns an integer  value	 indi‐
       cating  the  type of error. Possible return values are as follows: Suc‐
       cessful completion.  The system lacks the necessary resources to create
       another	thread,	 or  the  system-imposed  limit on the total number of
       threads under execution by a single user is exceeded.  The value speci‐
       fied  by	 attr  is  invalid.   Insufficient  memory  exists to create a
       thread.	The caller does not have the appropriate permission to	create
       a thread with the specified attributes.

ERRORS
       None

SEE ALSO
       Functions:	   pthread_atfork(3),	      pthread_attr_destroy(3),
       pthread_attr_init(3), pthread_attr_setdetachstate(3), pthread_attr_set‐
       inheritsched(3),	 pthread_attr_setschedparam(3), pthread_attr_setsched‐
       policy(3),	pthread_attr_setstacksize(3),	    pthread_cancel(3),
       pthread_detach(3), pthread_exit(3), pthread_join(3)

       Manuals: Guide to DECthreads and Programmer's Guide

							     pthread_create(3)
[top]

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net