pthread_create(3T)             DG/UX R4.11MU05            pthread_create(3T)


NAME
       pthreadcreate - create a thread

SYNOPSIS
       #include <pthread.h>

       int pthreadcreate(pthreadt *thread,
                          pthreadattrt *attr,
                          void * (*startroutine)(void *arg),
                          void *arg);

   where:
       thread         A pointer to the location in which to store the new
                      thread ID
       attr           A pointer to a thread attributes object, or NULL
       startroutine  A pointer to the routine at which the new thread will
                      start executing
       arg            A pointer to an argument to be passed to startroutine

DESCRIPTION
       The pthreadcreate() function creates a new thread, with attributes
       specified by attr.  The newly created thread starts executing
       startroutine, with arg as its sole argument.

       If attr is NULL, the default attributes are used.  Otherwise, attr
       points to the threads attributes object containing the creation
       attributes that will be used to override the default attributes.
       Passing a NULL as attr is equivalent to passing a pointer to a newly
       initialized attributes object.  Refer to pthreadattrinit(3T) and
       related attributes-setting routines for descriptions of the default
       values.  Briefly, the default attributes specify that the new thread
       will have a stack size of 4096 bytes (DG/UX), will not be detached,
       and will inherit its scheduling attributes from the creating
       (calling) thread.

       Upon successful completion, pthreadcreate() stores the ID of the
       created thread in the location pointed to by thread.

       If startroutine returns, the effect is as if there were an implicit
       call to pthreadexit() using the return value of startroutine as the
       exit status.  Note the initial thread differs from this, when it
       returns from main() the effect shall be as if there were an implicit
       call to exit() using the return value of main() as the exit status.
       A call to exit() causes the entire process to be terminated.

       If pthreadcreate() fails, no new thread is created, and the contents
       of the location pointed to by thread are undefined.

DIAGNOSTICS
   Return Value
       If successful, pthreadcreate() returns 0, and sets the value pointed
       to by thread to the new thread's id.  Otherwise it returns -1 and
       sets errno to indicate the error.

   Errors
       For each of the following conditions, pthreadcreate() returns -1 and
       sets errno to the corresponding value:

       [EINVAL]  An invalid attributes object has been specified.  This
                 occurs when DG/UX has detected that the attributes object
                 pointed to by attr has not been initialized by a previous
                 call to pthreadattrinit() or has been corrupted.

       [EINVAL]  An invalid combination of values has been specified in the
                 attributes object pointed to by attr.

       [EPERM]   The caller does not have permission to create a thread with
                 the attributes object pointed to by attr.

       [EAGAIN]  The system- or user-imposed limit on the number of threads
                 or thread groups would be exceeded by this call.

       [ENOMEM]  Insufficient memory exists to create the thread, even
                 though the caller is allowed to create another thread.

       [ESRCH]   The caller is attempting to create the thread in a thread
                 group that does not exist or has been marked for
                 destruction.

SEE ALSO
       fork(2), pthreadattrinit(3T), pthreadattrsetstacksize(3T),
       pthreadattrsetdetachstate(3T), pthreadattrsetinheritsched(3T),
       pthreaddetach(3T), pthreadexit(3T), pthreadjoin(3T),
       pthreadself(3T), pthreadequal(3T), dgpthreadattrsetgroup(3T),
       dgpthreadgroupcreate(3T).  threads(5),

NOTES
       Unlike a newly created process that also returns from fork(2), a
       newly created thread does not return from pthreadcreate().  Instead
       the new thread starts executing at its startroutine.  Similarly,
       there are no parent/child relationships among threads in the same
       process.  All threads are siblings of one another.

       After the call to pthreadcreate() completes, the attributes pointed
       to by attr are no longer associated with the newly created thread.
       Conceptually, they are simply copied to the new thread.

       The location pointed to by thread is not filled in until after
       returning from the call to pthreadcreate().  A common mistake is to
       use the new thread id as the arg to the same pthreadcreate() call.

       DG/UX attempts to reuse threads and their corresponding thread ids.
       An application should not assume that all thread ids assigned to
       threads in the same process will be unique for the life of the
       process.  As soon as a thread has exited and has been detached, its
       resources and id are made available for reuse.  Hence an application
       needs to be especially careful about not using a thread id after that
       thread has exited and been cleaned up.


Licensed material--property of copyright holder(s)