*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> pthread_create (3)              



NAME    [Toc]    [Back]

       pthread_create - Creates a thread

SYNOPSIS    [Toc]    [Back]

       #include <pthread.h>

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

LIBRARY    [Toc]    [Back]

       DECthreads POSIX 1003.1c Library (libpthread.so)

STANDARDS    [Toc]    [Back]

       Interfaces  documented  on  this reference page conform to
       industry standards as follows:

       IEEE Std 1003.1c-1995, POSIX  System  Application  Program

PARAMETERS    [Toc]    [Back]

       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    [Toc]    [Back]

       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  programs
       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 executable thread  is  created
  with  attributes  specified by the attr argument (or
       with default attributes if NULL is specified).

   Thread Creation    [Toc]    [Back]
       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 presence 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
  scheduling  and  priority  attributes. The caller of
       pthread_create(3) can  synchronize  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  DECthreads writes into the address specified as the
       pthread_create(3) routine's  thread  argument.  DECthreads
       writes  the  new thread's thread identifier before the new
       thread executes.

       By default, the new thread's scheduling policy and  priority
  are  inherited  from the creating thread--that is, by
       default,  the  pthread_create(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

       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

   Thread Termination    [Toc]    [Back]
       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

       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
 exception 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 threadspecific
 data keys that has a non-NULL  value:  DECthreads
       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_ITERATIONS.
  This  destroys  all  thread-specific data
       associated with the terminated thread.  DECthreads awakens
       the  thread (if there is one) that is currently waiting to
       join with the terminated thread. That is, DECthreads 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    [Toc]    [Back]

       If an error condition occurs, no thread  is  created,  the
       contents of thread are undefined, and this routine returns
       an integer value indicating the type  of  error.  Possible
       return  values are as follows: Successful 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  specified  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

ERRORS    [Toc]    [Back]


SEE ALSO    [Toc]    [Back]

       Functions:   pthread_atfork(3),   pthread_attr_destroy(3),
       pthread_attr_init(3),      pthread_attr_setdetachstate(3),
       pthread_attr_setinheritsched(3),    pthread_attr_setschedparam(3),                  pthread_attr_setschedpolicy(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

[ Back ]
 Similar pages
Name OS Title
tis_testcancel Tru64 Creates a cancellation point in the calling thread
pthread_setspecific Tru64 Sets the thread-specific data value associated with the specified key for the current thread
pthread_join Tru64 Causes the calling thread to wait for the termination of the specified thread
pthread_cancel Tru64 Allows a thread to request a thread to terminate execution
pthread_getname_np Tru64 Obtain the object name from the thread object of an existing thread
XmFontListEntryLoad HP-UX A font list function that loads a font or creates a font set and creates an accompanying font list entry
XmFontListEntryLoad IRIX A font list function that loads a font or creates a font set and creates an accompanying font list entry
XmFontListEntryLoad Tru64 A font list function that loads a font or creates a font set and creates an accompanying font list e...
pthread_setname_np Tru64 Changes the object name in the thread object for an existing thread
pthread_equal Tru64 Compares one thread identifier to another thread identifier
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service