VMS Help  —  POSIX Threads, PTHREAD routines
    Routines that comprise the multithreading pthread interface are
    based on the IEEE POSIX 1003.1-1996 standard. The global errno
    variable is not used by these routines. To indicate errors,
    the PTHREAD routines return integer values indicating the type
    of error. Routine names ending with the _np suffix denote that
    the routine is not portable; that is, the routine might not be
    available in implementations of POSIX 1003.1-1996 other than
    the Threads Library. See the Guide to the POSIX Threads Library
    documentation for more information.

1  –  pthread_attr_destroy

    Destroys a thread attributes object.

1.1  –  C Binding

    #include <pthread.h>

    int
    pthread_attr_destroy (
                pthread_attr_t   *attr);

1.2  –  Arguments

 attr

    Thread attributes object to be destroyed.

1.3  –  Description

    This routine destroys a thread attributes object. Call this
    routine when a thread attributes object will no longer be
    referenced.

    Threads that were created using this thread attributes object are
    not affected by the destruction of the thread attributes object.

    The results of calling this routine are unpredictable if
    the value specified by the attr argument refers to a thread
    attributes object that does not exist.

1.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by attr is not a valid thread
                attributes object.

1.5  –  Associated Routines

       pthread_attr_init()
       pthread_create()

2  –  pthread_attr_getdetachstate

    Obtains the detachstate attribute of the specified thread
    attributes object.

2.1  –  C Binding

    #include <pthread.h>

    int
    pthread_attr_getdetachstate (
                const pthread_attr_t   *attr,
                int   *detachstate);

2.2  –  Arguments

 attr

    Thread attributes object whose detachstate attribute is obtained.

 detachstate

    Receives the value of the detachstate attribute.

2.3  –  Description

    This routine obtains the detachstate attribute of a thread
    attributes object. This attribute specifies whether threads
    created using the specified thread attributes object are created
    in a detached state.

    On successful completion, this routine returns a zero and the
    detachstate attribute is set in detachstate. A value of PTHREAD_
    CREATE_JOINABLE indicates the thread is not detached, and a value
    of PTHREAD_CREATE_DETACHED indicates the thread is detached.

    See the pthread_attr_setdetachstate() description for information
    about the detachstate attribute.

2.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by attr does not refer to an
                existing thread attributes object.

2.5  –  Associated Routines

       pthread_attr_init()
       pthread_attr_setdetachstate()

3  –  pthread_attr_getguardsize

    Obtains the guardsize attribute of the specified thread
    attributes object.

3.1  –  C Binding

    #include <pthread.h>

    int
    pthread_attr_getguardsize (
                const pthread_attr_t   *attr,
                size_t   *guardsize);

3.2  –  Arguments

 attr

    Address of the thread attributes object whose guardsize attribute
    is obtained.

 guardsize

    Receives the value of the guardsize attribute of the thread
    attributes object specified by attr.

3.3  –  Description

    This routine obtains the value of the guardsize attribute of
    the thread attributes object specified in the attr argument and
    stores it in the location specified by the guardsize argument.
    The specified attributes object must already be initialized at
    the time this routine is called.

    When creating a thread, use a thread attributes object to specify
    nondefault values for thread attributes. The guardsize attribute
    of a thread attributes object specifies the minimum size (in
    bytes) of the guard area for the stack of a new thread.

    A guard area can help a multithreaded program detect the overflow
    of a thread's stack. A guard area is a region of no-access memory
    that the Threads Library allocates at the overflow end of the
    thread's stack. When any thread attempts to access a memory
    location within this region, a memory addressing violation
    occurs.

    Note that the value of the guardsize attribute of a particular
    thread attributes object does not necessarily correspond to the
    actual size of the guard area of any existing thread in your
    multithreaded program.

3.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by attr does not refer to an
                existing thread attributes object.

3.5  –  Associated Routines

       pthread_attr_init()
       pthread_attr_setguardsize()
       pthread_attr_setstacksize()
       pthread_create()

4  –  pthread_attr_getinheritsched

    Obtains the inherit scheduling attribute of the specified thread
    attributes object.

4.1  –  C Binding

    #include <pthread.h>

    int
    pthread_attr_getinheritsched (
                const pthread_attr_t   *attr,
                int   *inheritsched);

4.2  –  Arguments

 attr

    Thread attributes object whose inherit scheduling attribute is
    obtained.

 inheritsched

    Receives the value of the inherit scheduling attribute. Refer to
    the description of the pthread_attr_setinheritsched() function
    for valid values.

4.3  –  Description

    This routine obtains the value of the inherit scheduling
    attribute from the specified thread attributes object. The
    inherit scheduling attribute specifies whether threads created
    using the attributes object inherit the scheduling attributes of
    the creating thread, or use the scheduling attributes stored in
    the attributes object that is passed to pthread_create().

4.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by attr is not a valid thread
                attributes object.

4.5  –  Associated Routines

       pthread_attr_init()
       pthread_attr_setinheritsched()
       pthread_create()

5  –  pthread_attr_getname_np

    Obtains the object name attribute from a thread attributes
    object.

5.1  –  C Binding

    #include <pthread.h>

    int
    pthread_attr_getname_np (
             const pthread_attr_t   *attr,
             char   *name,
             size_t   len,
             void   **mbz);

5.2  –  Arguments

 attr

    Address of the thread attributes object whose object name
    attribute is to be obtained.

 name

    Location to store the obtained object name.

 len

    Length in bytes of buffer at the location specified by name.

 mbz

    Reserved for future use. The value must be zero (0).

5.3  –  Description

    This routine copies the object name attribute from the thread
    attributes object specified by the attr argument to the buffer
    at the location specified by the name argument. Before calling
    this routine, your program must allocate the buffer indicated by
    name. A new thread created using the thread attributes object is
    initialized with the object name that was set in that attributes
    object.

    The object name is a C language string and provides an identifier
    that is meaningful to a person debugging a multithreaded
    application. The maximum number of characters in the object name
    is 31.

    If the specified thread attributes object has not been previously
    set with an object name, this routine copies a C language null
    string into the buffer at location name.

    This routine contrasts with pthread_getname_np(), which obtains
    the object name from the thread object for an existing thread.

5.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by attr is not a valid thread
                attributes object.

5.5  –  Associated Routines

       pthread_getname_np()
       pthread_attr_setname_np()
       pthread_setname_np()

6  –  pthread_attr_getschedparam

    Obtains the scheduling parameters for an attribute of the
    specified thread attributes object.

6.1  –  C Binding

    #include <pthread.h>

    int
    pthread_attr_getschedparam (
                const pthread_attr_t   *attr,
                struct sched_param   *param);

6.2  –  Arguments

 attr

    Thread attributes object of the scheduling policy attribute whose
    parameters are obtained.

 param

    Receives the values of scheduling parameters for the scheduling
    policy attribute of the attributes object specified by the
    attr argument. Refer to the description of the pthread_attr_
    setschedparam() routine for valid parameters and their values.

6.3  –  Description

    This routine obtains the scheduling parameters associated
    with the scheduling policy attribute of the specified thread
    attributes object.

6.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by attr is not a valid thread
                attributes object.

6.5  –  Associated Routines

       pthread_attr_init()
       pthread_attr_setschedparam()
       pthread_create()

7  –  pthread_attr_getschedpolicy

    Obtains the scheduling policy attribute of the specified thread
    attributes object.

7.1  –  C Binding

    #include <pthread.h>

    int
    pthread_attr_getschedpolicy (
                const pthread_attr_t   *attr,
                int   *policy);

7.2  –  Arguments

 attr

    Thread attributes object whose scheduling policy attribute is
    obtained.

 policy

    Receives the value of the scheduling policy attribute. Refer to
    the description of the pthread_attr_setschedpolicy() routine for
    valid values.

7.3  –  Description

    This routine obtains the value of the scheduling policy attribute
    of the specified thread attributes object. The scheduling policy
    attribute defines the scheduling policy for threads created using
    the attributes object.

7.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by attr is not a valid thread
                attributes object.

7.5  –  Associated Routines

       pthread_attr_init()
       pthread_attr_setschedpolicy()
       pthread_create()

8  –  pthread_attr_getscope

    Obtains the contention scope attribute of the specified thread
    attributes object.

8.1  –  C Binding

    #include <pthread.h>

    int
    pthread_attr_getscope (
                const pthread_attr_t   *attr,
                int   *scope);

8.2  –  Arguments

 attr

    Address of the thread attributes object whose contention scope
    attribute is obtained.

 scope

    Receives the value of the contention scope attribute of the
    thread attributes object specified by attr.

8.3  –  Description

    This routine obtains the value of the contention scope attribute
    of the thread attributes object specified in the attr argument
    and stores it in the location specified by the scope argument.
    The specified attributes object must already be initialized at
    the time this routine is called.

    The contention scope attribute specifies the set of threads
    with which a thread must compete for processing resources. The
    contention scope attribute specifies whether the new thread
    competes for processing resources only with other threads in its
    own process, called process contention scope, or with all threads
    on the system, called system contention scope.

    The Threads Library selects at most one thread to execute on
    each processor at any point in time. The Threads Library resolves
    the contention based on each thread's scheduling attributes (for
    example, priority) and scheduling policy (for example, round-
    robin).

    A thread created using a thread attributes object whose
    contention scope attribute is set to PTHREAD_SCOPE_PROCESS
    contends for processing resources with other threads within its
    own process that also were created with PTHREAD_SCOPE_PROCESS.
    It is unspecified how such threads are scheduled relative to
    threads in other processes or threads in the same process that
    were created with PTHREAD_SCOPE_SYSTEM contention scope.

    A thread created using a thread attributes object whose
    contention scope attribute is set to PTHREAD_SCOPE_SYSTEM
    contends for processing resources with other threads in any
    process that also were created with PTHREAD_SCOPE_SYSTEM.

    Note that the value of the contention scope attribute of a
    particular thread attributes object does not necessarily
    correspond to the actual scheduling contention scope of any
    existing thread in your multithreaded program.

8.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by attr is not a valid thread
                attributes object.
    [ENOSYS]    This routine is not supported by the implementation.

8.5  –  Associated Routines

       pthread_attr_init()
       pthread_attr_setscope()

9  –  pthread_attr_getstackaddr

    Obtains the stack address attribute of the specified thread
    attributes object.

9.1  –  C Binding

    #include <pthread.h>

    int
    pthread_attr_getstackaddr (
                const pthread_attr_t   *attr,
                void   **stackaddr);

9.2  –  Arguments

 attr

    Address of the thread attributes object whose stack address
    attribute is obtained.

 stackaddr

    Receives the value of the stack address attribute of the thread
    attributes object specified by attr.

9.3  –  Description

    This routine obtains the value of the stack address attribute of
    the thread attributes object specified in the attr argument and
    stores it in the location specified by the stackaddr argument.
    The specified attributes object must already be initialized when
    this routine is called.

    The stack address attribute of a thread attributes object points
    to the origin of the stack for a new thread.

    Note that the value of the stack address attribute of a
    particular thread attributes object does not necessarily
    correspond to the actual stack origin of any existing thread
    in your multithreaded program.

9.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by attr is not a valid thread
                attributes object.

9.5  –  Associated Routines

       pthread_attr_getguardsize()
       pthread_attr_getstacksize()
       pthread_attr_init()
       pthread_attr_setguardsize()
       pthread_attr_setstackaddr()
       pthread_attr_setstacksize()
       pthread_create()

10  –  pthread_attr_getstackaddr_np

    Obtains the stack address attribute of the specified thread
    attributes object.

10.1  –  C Binding

    #include <pthread.h>

    int
    pthread_attr_getstackaddr (
                const pthread_attr_t   *attr,
                void   **stackaddr,
                size_t   *size);

10.2  –  Arguments

 attr

    Address of the thread attributes object whose stack address
    attribute is obtained.

 stackaddr

    Receives the address of the stack region of the thread attributes
    object specified by attr.

 size

    The size of the stack region in bytes.

10.3  –  Description

    This routine obtains the value of the stack address attribute of
    the thread attributes object specified in the attr argument and
    stores it in the location specified by the stackaddr argument.
    The specified attributes object must already be initialized when
    this routine is called.

    The stack address attribute of a thread attributes object points
    to the origin of the stack for a new thread.

    Unlike pthread_attr_getstackaddr(), this routine is a much more
    reliable portable interface. With the POSIX standard pthread_
    attr_getstackaddr(), a stack is specified using a single,
    undefined, address. An implementation of the standard can only
    assume that the specified value represents the value to which the
    thread's stack pointer should be set when beginning execution.
    However, this requires the application to know how the machine
    uses the stack. For example, a stack may "grow" either up (to
    higher addresses) or down (to lower addresses), and may be
    decreased (or increased) either before or after storing a new
    value.

    The Threads Library provides an alternative interface with
    pthread_attr_getstackaddr_np(). Instead of returning a stack
    address, it returns the base (lowest) address and the size.

10.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by attr is not a valid thread
                attributes object.

10.5  –  Associated Routines

       pthread_attr_setstackaddr_np()

11  –  pthread_attr_getstacksize

    Obtains the stacksize attribute of the specified thread
    attributes object.

11.1  –  C Binding

    #include <pthread.h>

    int
    pthread_attr_getstacksize (
             const pthread_attr_t   *attr,
             size_t   *stacksize);

11.2  –  Arguments

 attr

    Thread attributes object whose stacksize attribute is obtained.

 stacksize

    Receives the value for the stacksize attribute of the thread
    attributes object specified by the attr argument.

11.3  –  Description

    This routine obtains the stacksize attribute of the thread
    attributes object specified in the attr argument.

11.4  –  Return Values

    On successful completion, this routine returns a zero (0) and
    the stacksize value in bytes in the location specified in the
    stacksize argument.

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by attr is not a valid stack
                attributes object.

11.5  –  Associated Routines

       pthread_attr_init()
       pthread_attr_setstacksize()
       pthread_create()

12  –  pthread_attr_init

    Initializes a thread attributes object.

12.1  –  C Binding

    #include <pthread.h>

    int
    pthread_attr_init (
             pthread_attr_t   *attr);

12.2  –  Arguments

 attr

    Address of a thread attributes object to be initialized.

12.3  –  Description

    This routine initializes the thread attributes object specified
    by the attr argument with a set of default attribute values. A
    thread attributes object is used to specify the attributes of
    one or more threads when they are created. The attributes object
    created by this routine is used only in calls to the pthread_
    create() routine.

    The following routines change individual attributes of an
    initialized thread attributes object:

       pthread_attr_setdetachstate()
       pthread_attr_setguardsize()
       pthread_attr_setinheritsched()
       pthread_attr_setschedparam()
       pthread_attr_setschedpolicy()
       pthread_attr_setscope()
       pthread_attr_setstackaddr()
       pthread_attr_setstacksize()

    The attributes of the thread attributes object are initialized to
    default values. The default value of each attribute is discussed
    in the reference description for each routine previously listed.

    When a thread attributes object is used to create a thread,
    the object's attribute values determine the characteristics
    of the new thread. Thus, attributes objects act as additional
    arguments to thread creation. Changing the attributes of a
    thread attributes object does not affect any threads that were
    previously created using that attributes object.

    You can use the same thread attributes object in successive calls
    to pthread_create(), from any thread. (However, you cannot use
    the same value of the stack address attribute to create multiple
    threads that might run concurrently; threads cannot share a
    stack.) If more than one thread might change the attributes in
    a shared attributes object, your program must use a mutex to
    protect the integrity of the attributes object's contents.

    When you set the scheduling policy or scheduling parameters,
    or both, in a thread attributes object, you must disable
    scheduling inheritance if you want the scheduling attributes
    you set to be used at thread creation. To disable scheduling
    inheritance, before creating the new thread use the pthread_attr_
    setinheritsched() routine to specify the value PTHREAD_EXPLICIT_
    SCHED for the inherit argument.

12.4  –  Return Values

    If an error condition occurs, the thread attributes object cannot
    be used, and this routine returns an integer value indicating the
    type of error. Possible return values are as follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by attr is not a valid thread
                attributes object.
    [ENOMEM]    Insufficient memory to initialize the thread
                attributes object.

12.5  –  Associated Routines

       pthread_attr_destroy()
       pthread_attr_setdetachstate()
       pthread_attr_setguardsize()
       pthread_attr_setinheritsched()
       pthread_attr_setschedparam()
       pthread_attr_setschedpolicy()
       pthread_attr_setscope()
       pthread_attr_setstackaddr()
       pthread_attr_setstacksize()
       pthread_create()

13  –  pthread_attr_setdetachstate

    Changes the detachstate attribute in the specified thread
    attributes object.

13.1  –  C Binding

    #include <pthread.h>

    int
    pthread_attr_setdetachstate (
                pthread_attr_t   *attr,
                int   detachstate);

13.2  –  Arguments

 attr

    Thread attributes object to be modified.

 detachstate

    New value for the detachstate attribute. Valid values are as
    follows:

    PTHREAD_CREATE_       This is the default value. Threads are
    JOINABLE              created in "undetached" state.
    PTHREAD_CREATE_       The created thread is detached immediately,
    DETACHED              before it begins running.

13.3  –  Description

    This routine changes the detachstate attribute in the thread
    attributes object specified by the attr argument. The detachstate
    attribute specifies whether the thread created using the
    specified thread attributes object is created in a detached state
    or not. A value of PTHREAD_CREATE_JOINABLE indicates the thread
    is not detached, and a value of PTHREAD_CREATE_DETACHED indicates
    the thread is detached. PTHREAD_CREATE_JOINABLE is the default
    value.

    Your program cannot use the thread handle (the value of type
    pthread_t returned by the pthread_create() routine) of a detached
    thread because the thread might terminate asynchronously, and a
    detached thread ID is not valid after termination. In particular,
    it is an error to attempt to detach or join with a detached
    thread.

    When a thread that has not been detached completes execution,
    the Threads Library retains the state of that thread to allow
    another thread to join with it. If the thread is detached
    before it completes execution, the Threads Library is free to
    immediately reclaim the thread's storage and resources. Failing
    to detach threads that have completed execution can result in
    wasting resources, so threads should be detached as soon as
    the program is done with them. If there is no need to use the
    thread's handle after creation, such as to join with it, create
    the thread initially detached.

13.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by the attr argument is not a
                valid threads attribute object or the detachstate
                argument is invalid.

13.5  –  Associated Routines

       pthread_attr_init()
       pthread_attr_getdetachstate()
       pthread_create()
       pthread_join()

14  –  pthread_attr_setguardsize

    Changes the guardsize attribute of the specified thread
    attributes object.

14.1  –  C Binding

    #include <pthread.h>

    int
    pthread_attr_setguardsize (
             pthread_attr_t   *attr,
             size_t   guardsize);

14.2  –  Arguments

 attr

    Address of the thread attributes object whose guardsize attribute
    is to be modified.

 guardsize

    New value for the guardsize attribute of the thread attributes
    object specified by attr.

14.3  –  Description

    This routine uses the value specified in the guardsize argument
    to set the guardsize attribute of the thread attributes object
    specified in the attr argument.

    When creating a thread, use a thread attributes object to specify
    nondefault values for thread attributes. The guardsize attribute
    of a thread attributes object specifies the minimum size (in
    bytes) of the guard area for the stack of a new thread.

    A guard area, with its associated overflow warning area, can
    help a multithreaded program detect overflow of a thread's
    stack. A guard area is a region of no-access memory that the
    Threads Library allocates at the overflow end of the thread's
    stack, following the thread's overflow warning area. If the
    thread attempts to write in the overflow warning area, a stack
    overflow exception occurs. Your program can catch this exception
    and continue processing as long as the thread does not attempt
    to write in the guard area. When any thread attempts to access
    a memory location within the guard area, a memory addressing
    violation occurs without the possibility of recovery.

    A new thread can be created with a default guardsize attribute
    value. This value is platform dependent, but will always be
    at least one "hardware protection unit" (that is, at least one
    page). For more information, see this guide's platform-specific
    appendixes.

    After this routine is called, due to platform-specific factors
    the Threads Library might reserve a larger guard area for the
    new thread than was specified in the guardsize argument. See this
    guide's platform-specific appendixes for more information.

    The Threads Library allows your program to specify the size of a
    thread stack's guard area for two reasons:

    o  When a thread allocates large data structures on its stack, a
       guard area with a size greater than the default size might be
       required to detect stack overflow.

    o  Overflow protection of a thread's stack can potentially waste
       system resources, such as for an application that creates a
       large number of threads that will never overflow their stacks.
       Your multithreaded program can conserve system resources
       by "turning off" a thread's stack guard area-that is, by
       specifying a guardsize attribute of zero.

    If a thread is created using a thread attributes object whose
    stackaddr attribute is set (using the pthread_attr_setstackaddr()
    routine), this routine ignores the object's guardsize attribute
    and provides no thread stack overflow warning or guard area for
    the new thread.

14.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The argument attr is not a valid thread attributes
                object, or the argument guardsize contains an invalid
                value.

14.5  –  Associated Routines

       pthread_attr_init()
       pthread_attr_getguardsize()
       pthread_attr_setstacksize()
       pthread_create()

15  –  pthread_attr_setinheritsched

    Changes the inherit scheduling attribute of the specified thread
    attributes object.

15.1  –  C Binding

    #include <pthread.h>

    int
    pthread_attr_setinheritsched (
             pthread_attr_t   *attr,
             int   inheritsched);

15.2  –  Arguments

 attr

    Thread attributes object whose inherit scheduling attribute is to
    be modified.

 inheritsched

    New value for the inherit scheduling attribute. Valid values are
    as follows:

       PTHREAD_INHERIT_      The created thread inherits the
       SCHED                 scheduling policy and associated
                             scheduling attributes of the thread
                             calling pthread_create(). Any scheduling
                             attributes in the attributes object
                             specified by the pthread_create() attr
                             argument are ignored during thread
                             creation. This is the default value.
       PTHREAD_EXPLICIT_     The scheduling policy and associated
       SCHED                 scheduling attributes of the created
                             thread are set to the corresponding
                             values from the attribute object
                             specified by the pthread_create()  attr
                             argument.

15.3  –  Description

    This routine changes the inherit scheduling attribute of the
    thread attributes object specified by the attr argument. The
    inherit scheduling attribute specifies whether a thread created
    using the specified attributes object inherits the scheduling
    attributes of the creating thread, or uses the scheduling
    attributes stored in the attributes object specified by the
    pthread_create() attr argument.

    The first thread in an application has a scheduling policy of
    SCHED_OTHER. See the pthread_attr_setschedparam() and pthread_
    attr_setschedpolicy() routines for more information on valid
    priority values and valid scheduling policy values.

    Inheriting scheduling attributes (instead of using the scheduling
    attributes stored in the attributes object) is useful when a
    thread is creating several helper threads-that is, threads
    that are intended to work closely with the creating thread to
    cooperatively solve the same problem. For example, inherited
    scheduling attributes ensure that helper threads created in
    a sort routine execute with the same priority as the calling
    thread.

15.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by the attr argument is not a
                valid thread attributes object, or the inheritsched
                argument contains an invalid value.
    [ENOTSUP]   An attempt was made to set the attribute to an
                unsupported value.

15.5  –  Associated Routines

       pthread_attr_init()
       pthread_attr_getinheritsched()
       pthread_attr_setschedpolicy()
       pthread_attr_setschedparam()
       pthread_attr_setscope()
       pthread_create()

16  –  pthread_attr_setname_np

    Changes the object name attribute in a thread attributes object.

16.1  –  C Binding

    #include <pthread.h>

    int
    pthread_attr_setname_np (
             pthread_attr_t   *attr,
             const char   *name,
             void   *mbz);

16.2  –  Arguments

 attr

    Address of the thread attributes object whose object name
    attribute is to be changed.

 name

    Object name value to copy into the thread attributes object's
    object name attribute.

 mbz

    Reserved for future use. The value must be zero (0).

16.3  –  Description

    This routine changes the object name attribute in the thread
    attributes object specified by the attr argument to the value
    specified by the name argument. A new thread created using the
    thread attributes object is initialized with the object name that
    was set in that attributes object.

    The object name is a C language string and provides an identifier
    that is meaningful to a person debugging a multithreaded
    application. The maximum number of characters in the object name
    is 31.

    This routine contrasts with pthread_setname_np(), which changes
    the object name in the thread object for an existing thread.

16.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by attr is not a valid thread
                attributes object, or the length in characters of
                name exceeds 31.
    [ENOMEM]    Insufficient memory exists to create a copy of the
                object name string.

16.5  –  Associated Routines

       pthread_attr_getname_np()
       pthread_getname_np()
       pthread_setname_np()

17  –  pthread_attr_setschedparam

    Changes the values of the parameters associated with a scheduling
    policy of the specified thread attributes object.

17.1  –  C Binding

    #include <pthread.h>

    int
    pthread_attr_setschedparam (
             pthread_attr_t   *attr,
             const struct sched_param   *param);

17.2  –  Arguments

 attr

    Thread attributes object for the scheduling policy attribute
    whose parameters are to be set.

 param

    A structure containing new values for scheduling parameters
    associated with the scheduling policy attribute of the specified
    thread attributes object.

                                   NOTE

       The Threads Library provides only the sched_priority
       scheduling parameter. See below for information about this
       scheduling parameter.

17.3  –  Description

    This routine sets the scheduling parameters associated with
    the scheduling policy attribute of the thread attributes object
    specified by the attr argument.
    Scheduling Priority
    Use the sched_priority field of a sched_param structure to set
    a thread's execution priority. The effect of the scheduling
    priority you assign depends on the scheduling policy specified
    for the attributes object specified by the attr argument.

    By default, a created thread inherits the priority of the thread
    calling pthread_create(). To specify a priority using this
    routine, scheduling inheritance must be disabled at the time the
    thread is created. Before calling pthread_create(), call pthread_
    attr_setinheritsched() and specify the value PTHREAD_EXPLICIT_
    SCHED for the inherit argument.

    An application specifies priority only to express the urgency
    of executing the thread relative to other threads. Do not use
    priority to control mutual exclusion when you are accessing
    shared data. With a sufficient number of processors present, all
    ready threads, regardless of priority, execute simultaneously.
    Even on a uniprocessor, a lower priority thread could either
    execute before or be interleaved with a higher priority thread,
    for example due to page fault behavior. See <REFERENCE>(intro_
    threads_chap) and <REFERENCE>(threads_concepts_chap) for more
    information.

    Valid values of the sched_priority scheduling parameter depend on
    the chosen scheduling policy. Use the POSIX routines sched_get_
    priority_min() or sched_get_priority_max()  to determine the low
    and high limits of each policy.

    Additionally, the Threads Library provides nonportable priority
    range constants, as follows:

    Policy          Low            High

    SCHED_FIFO      PRI_FIFO_MIN   PRI_FIFO_MAX
    SCHED_RR        PRI_RR_MIN     PRI_RR_MAX
    SCHED_OTHER     PRI_OTHER_MIN  PRI_OTHER_MAX
    SCHED_FG_NP     PRI_FG_MIN_NP  PRI_FG_MAX_NP
    SCHED_BG_NP     PRI_BG_MIN_NP  PRI_BG_MAX_NP

    The default priority varies by platform. On Tru64 UNIX, the
    default is 19 (that is, the POSIX priority of a normal timeshare
    process). On other platforms, the default priority is the
    midpoint between PRI_FG_MIN_NP and PRI_FG_MAX_NP.

17.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by attr is not a valid thread
                attributes object, or the value specified by param is
                invalid.
    [ENOTSUP]   An attempt was made to set the attribute to an
                unsupported value.

17.5  –  Associated Routines

       pthread_attr_init()
       pthread_attr_getschedparam()
       pthread_attr_setinheritsched()
       pthread_attr_setschedpolicy()
       pthread_create()
       sched_yield()

18  –  pthread_attr_setschedpolicy

    Changes the scheduling policy attribute of the specified thread
    attributes object.

18.1  –  C Binding

    #include <pthread.h>

    int
    pthread_attr_setschedpolicy (
             pthread_attr_t   *attr,
             int   policy);

18.2  –  Arguments

 attr

    Thread attributes object to be modified.

 policy

    New value for the scheduling policy attribute. Valid values are
    as follows:

       SCHED_BG_NP
       SCHED_FG_NP (also known as SCHED_OTHER)
       SCHED_FIFO
       SCHED_RR

    SCHED_OTHER is the default value.

18.3  –  Description

    This routine sets the scheduling policy of a thread that is
    created using the attributes object specified by the attr
    argument. The default value of the scheduling attribute is SCHED_
    OTHER.

    By default, a created thread inherits the policy of the thread
    calling pthread_create(). To specify a policy using this routine,
    scheduling inheritance must be disabled at the time the thread
    is created. Before calling pthread_create(), call pthread_attr_
    setinheritsched() and specify the value PTHREAD_EXPLICIT_SCHED
    for the inherit argument.

    Preemption is caused by both scheduling and policy. Never attempt
    to use scheduling as a mechanism for synchronization.

18.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by attr is not a valid thread
                attributes object, or the value specified by policy
                is invalid.

18.5  –  Associated Routines

       pthread_attr_init()
       pthread_attr_getschedpolicy()
       pthread_attr_setinheritsched()
       pthread_attr_setschedparam()
       pthread_create()

19  –  pthread_attr_setscope

    Sets the contention scope attribute of the specified thread
    attributes object.

19.1  –  C Binding

    #include <pthread.h>

    int
    pthread_attr_setscope (
                pthread_attr_t   *attr,
                int   scope);

19.2  –  Arguments

 attr

    Address of the thread attributes object whose contention scope
    attribute is to be modified.

 scope

    New value for the contention scope attribute of the thread
    attributes object specified by attr.

19.3  –  Description

    This routine uses the value specified in the scope argument
    to set the contention scope attribute of the thread attributes
    object specified in the attr argument.

    When creating a thread, use a thread attributes object to specify
    nondefault values for thread attributes. The contention scope
    attribute specifies the set of threads with which a thread must
    compete for processing resources. The contention scope attribute
    specifies whether the new thread competes for processing
    resources only with other threads in its own process, called
    process contention scope, or with all threads on the system,
    called system contention scope.

    The Threads Library selects at most one thread to execute on
    each processor at any point in time. The Threads Library resolves
    the contention based on each thread's scheduling attributes (for
    example, priority) and scheduling policy (for example, round-
    robin).

    A thread created using a thread attributes object whose
    contention scope attribute is set to PTHREAD_SCOPE_PROCESS
    contends for processing resources with other threads within its
    own process that also were created with PTHREAD_SCOPE_PROCESS. It
    is unspecified how such threads are scheduled relative to either
    threads in other processes or threads in the same process that
    were created with PTHREAD_SCOPE_SYSTEM contention scope.

    A thread created using a thread attributes object whose
    contention scope attribute is set to PTHREAD_SCOPE_SYSTEM
    contends for processing resources with other threads in any
    process that also were created with PTHREAD_SCOPE_SYSTEM.

    Note that the value of the contention scope attribute of a
    particular thread attributes object does not necessarily
    correspond to the actual scheduling contention scope of any
    existing thread in your multithreaded program.

19.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by attr is not a valid thread
                attributes value, or the value specified by scope is
                not valid.
    [ENOTSUP]   An attempt was made to set the attribute to an
                unsupported value.

19.5  –  Associated Routines

       pthread_attr_destroy()
       pthread_attr_init()
       pthread_attr_getscope()
       pthread_attr_setinheritsched()
       pthread_create()

20  –  pthread_attr_setstackaddr

    Changes the stack address attribute of the specified thread
    attributes object.

20.1  –  C Binding

    #include <pthread.h>

    int
    pthread_attr_setstackaddr (
             pthread_attr_t   *attr,
             void   *stackaddr);

20.2  –  Arguments

 attr

    Address of the thread attributes object whose stack address
    attribute is to be modified.

 stackaddr

    New value for the stack address attribute of the thread
    attributes object specified by attr.

20.3  –  Description

    This routine uses the value specified in the stackaddr argument
    to set the stack address attribute of the thread attributes
    object specified in the attr argument.

    When creating a thread, use a thread attributes object to specify
    nondefault values for thread attributes. The stack address
    attribute of a thread attributes object points to the origin
    of the stack for a new thread.

    The default value for the stack address attribute of an
    initialized thread attributes object is NULL.

                                   NOTE

       Correct use of this routine depends upon details of the
       target platform's stack architecture. Thus, this routine
       cannot be used in a portable manner.

       The size of the stack must be at least PTHREAD_STACK_MIN
       bytes (see the pthread.h header file). However, because the
       Threads Library must use a portion of this stack memory to
       begin thread execution and to maintain thread state, your
       program's "user thread code" cannot rely on using all of the
       stack memory allocated.

    For your program to calculate a value for the stackaddr
    attribute, note that:

    o  Your program must allocate the memory that will be used for
       the new thread's stack.

    o  On Tru64 UNIX, to create a new thread using a thread
       attributes object, the stackaddr attribute must be an address
       that points to the high-memory end of the memory region
       allocated for the stack. This address must point to the
       highest even-boundary quadword in the allocated memory region.

    Also note that:

    o  If you use the pthread_attr_setstackaddr() routine to set a
       thread attributes object's stack address attribute and use
       that attributes object to create a new thread, the Threads
       Library ignores the attributes object's guardsize attribute
       and provides no thread stack guard area or overflow warning
       area for the new thread.

    o  If you use the same thread attributes object to create more
       than one thread and each created thread uses a nondefault
       stack address, you must use the pthread_attr_setstackaddr()
       routine to set a unique stack address attribute value for each
       new thread created using that attributes object.

20.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by attr is not a valid thread
                attributes object.

20.5  –  Associated Routines

       pthread_attr_getguardsize()
       pthread_attr_getstackaddr()
       pthread_attr_getstacksize()
       pthread_attr_init()
       pthread_attr_setguardsize()
       pthread_attr_setstacksize()
       pthread_create()

21  –  pthread_attr_setstackaddr_np

    Changes the stack address and size of the specified thread
    attributes object.

21.1  –  C Binding

    #include <pthread.h>

    int
    pthread_attr_setstackaddr_np (
             pthread_attr_t   *attr,
             void   *stackaddr,
             size_t   size);

21.2  –  Arguments

 attr

    Address of the thread attributes object whose stack address
    attribute is to be modified.

 stackaddr

    New value for the address of the stack region of the thread
    attributes object specified by attr.

 size

    The size of the stack region in bytes.

21.3  –  Description

    This routine uses the values specified in the stackaddr and size
    arguments to set the base stack address and size of the thread
    attributes object specified in the attr argument.

    When creating a thread, use a thread attributes object to specify
    nondefault values for thread attributes. The default value for
    the stack address attribute of an initialized thread attributes
    object is NULL.

    Unlike pthread_attr_setstackaddr(), this routine is a much more
    reliable portable interface. With the POSIX standard pthread_
    attr_setstackaddr(), a stack is specified using a single,
    undefined, address. An implementation of the standard can only
    assume that the specified value represents the value to which the
    thread's stack pointer should be set when beginning execution.
    However, this requires the application to know how the machine
    uses the stack. For example, a stack may "grow" either up (to
    higher addresses) or down (to lower addresses), and may be
    decreased (or increased) either before or after storing a new
    value.

    The Threads Library provides an alternative interface with
    pthread_attr_setstackaddr_np(). Instead of specifying a stack
    address, you specify the base (lowest) address and the size.

21.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by attr is not a valid thread
                attributes object.

21.5  –  Associated Routines

       pthread_attr_getstackaddr_np()

22  –  pthread_attr_setstacksize

    Changes the stacksize attribute in the specified thread
    attributes object.

22.1  –  C Binding

    #include <pthread.h>

    int
    pthread_attr_setstacksize (
             pthread_attr_t   *attr,
             size_t   stacksize);

22.2  –  Arguments

 attr

    Threads attributes object to be modified.

 stacksize

    New value for the stacksize attribute of the thread attributes
    object specified by the attr argument. The stacksize argument
    must be greater than or equal to PTHREAD_STACK_MIN. PTHREAD_
    STACK_MIN specifies the minimum size (in bytes) of the stack
    needed for a thread.

22.3  –  Description

    This routine sets the stacksize attribute in the thread
    attributes object specified by the attr argument. Use this
    routine to adjust the size of the writable area of the stack
    for a new thread.

    The size of a thread's stack is fixed at the time of thread
    creation. On OpenVMS systems, only the initial thread can
    dynamically extend its stack. On Tru64 UNIX systems, very large
    stacks can be created, but only a few pages are committed.

    Many compilers do not check for stack overflow. Ensure that the
    new thread's stack is sufficient for the resources required by
    routines that are called from the thread.

22.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by attr is not a valid thread
                attributes object, or the value specified by
                stacksize either is less than PTHREAD_STACK_MIN or
                exceeds a Threads Library-imposed limit.

22.5  –  Associated Routines

       pthread_attr_init()
       pthread_attr_getstacksize()
       pthread_create()

23  –  pthread_cancel

    Allows a thread to request a thread to terminate execution.

23.1  –  C Binding

    #include <pthread.h>

    int
    pthread_cancel (
             pthread_t   thread);

23.2  –  Arguments

 thread

    Thread that will receive a cancelation request.

23.3  –  Description

    This routine sends a cancelation request to the specified target
    thread. A cancelation request is a mechanism by which a calling
    thread requests the target thread to terminate as quickly as
    possible. Issuing a cancelation request does not guarantee that
    the target thread will receive or handle the request.

    When the cancelation request is acted on, all active cleanup
    handler routines for the target thread are called. When the last
    cleanup handler returns, the thread-specific data destructor
    routines are called for each thread-specific data key with a
    destructor and for which the target thread has a non-NULL value.
    Finally, the target thread is terminated.

    Note that cancelation of the target thread runs asynchronously
    with respect to the calling thread's returning from pthread_
    cancel(). The target thread's cancelability state and type
    determine when or if the cancelation takes place, as follows:

    1. The target thread can delay cancelation during critical
       operations by setting its cancelability state to PTHREAD_
       CANCEL_DISABLE.

    2. Because of communication delays, the calling thread can only
       rely on the fact that a cancelation request will eventually
       become pending in the target thread (provided that the target
       thread does not terminate beforehand).

    3. The calling thread has no guarantee that a pending cancelation
       request will be delivered because delivery is controlled by
       the target thread.

    When a cancelation request is delivered to a thread, termination
    processing is similar to that for pthread_exit(). For more
    information about thread termination, see the Thread Termination
    section of pthread_create().

    This routine is preferred in implementing an Ada abort statement
    and any other language- or software-defined construct for
    requesting thread cancelation.

    The results of this routine are unpredictable if the value
    specified in thread refers to a thread that does not currently
    exist.

23.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The specified thread is invalid.
    [ESRCH]     The thread argument does not specify an existing
                thread.

23.5  –  Associated Routines

       pthread_cleanup_pop()
       pthread_cleanup_push()
       pthread_create()
       pthread_exit()
       pthread_join()
       pthread_setcancelstate()
       pthread_setcanceltype()
       pthread_testcancel()

24  –  pthread_cleanup_pop

    (Macro) Removes the cleanup handler routine from the calling
    thread's cleanup handler stack and optionally executes it.

24.1  –  C Binding

    #include <pthread.h>

    void
    pthread_cleanup_pop(
             int   execute);

24.2  –  Arguments

 execute

    Integer that specifies whether the cleanup handler routine
    specified in the matching call to pthread_cleanup_push() is
    executed. A nonzero value causes the cleanup handler routine
    to be executed.

24.3  –  Description

    This routine removes the cleanup handler routine established by
    the matching call to pthread_cleanup_push() from the calling
    thread's cleanup handler stack, then executes it if the value
    specified in this routine's execute argument is nonzero.

    A cleanup handler routine can be used to clean up from a block
    of code whether exited by normal completion, cancelation, or the
    raising (or reraising) of an exception. The routine is popped
    from the calling thread's cleanup handler stack and is called
    with the arg argument (see the description for pthread_cleanup_
    push()) when any of the following actions occur:

    o  The thread calls pthread_cleanup_pop() and specifies a nonzero
       value for the execute argument.

    o  The thread calls pthread_exit().

    o  The thread is canceled.

    o  An exception is raised and is caught when the Threads Library
       unwinds the calling thread's stack to the lexical scope of the
       pthread_cleanup_push() and pthread_cleanup_pop()  pair.

    This routine and pthread_cleanup_push() are implemented as
    macros and must appear as statements and in pairs within the
    same lexical scope. You can think of the pthread_cleanup_push()
    macro as expanding to a string whose first character is a left
    brace ({) and pthread_cleanup_pop() as expanding to a string
    containing the corresponding right brace (}). This routine and
    pthread_cleanup_push() are implemented as exceptions, and may not
    work in a C++ environment. (See <REFERENCE>(exceptions_chap) for
    more information.)

24.4  –  Return Values

    None

24.5  –  Associated Routines

       pthread_cancel()
       pthread_cleanup_push()
       pthread_create()
       pthread_exit()

25  –  pthread_cleanup_push

    (Macro) Establishes a cleanup handler routine to be executed when
    the thread exits or is canceled.

25.1  –  C Binding

    #include <phtread.h>

    void
    pthread_cleanup_push(
             void   (*routine)(void *),
             void   *arg);

25.2  –  Arguments

 routine

    Routine executed as the cleanup handler.

 arg

    Argument passed to the cleanup handler routine.

25.3  –  Description

    This routine pushes the specified routine onto the calling
    thread's cleanup handler stack. The cleanup handler routine is
    popped from the stack and called with the arg argument when any
    of the following actions occur:

    o  The thread calls pthread_cleanup_pop() and specifies a nonzero
       value for the execute argument.

    o  The thread calls pthread_exit().

    o  The thread is canceled.

    o  An exception is raised and is caught when the Threads Library
       unwinds the calling thread's stack to the lexical scope of the
       pthread_cleanup_push() and pthread_cleanup_pop()  pair.

    This routine and pthread_cleanup_pop() are implemented as macros
    and must appear as statements and in pairs within the same
    lexical scope. You can think of the pthread_cleanup_push() macro
    as expanding to a string whose first character is a left brace
    ({) and pthread_cleanup_pop() as expanding to a string containing
    the corresponding right brace (}). This routine and pthread_
    cleanup_pop() are implemented as exceptions, and may not work
    in a C++ environment. (See <REFERENCE>(exceptions_chap) for more
    information.)

25.4  –  Return Values

    None

25.5  –  Associated Routines

       pthread_cancel()
       pthread_cleanup_pop()
       pthread_create()
       pthread_exit()
       pthread_testcancel()

26  –  pthread_cond_broadcast

    Wakes all threads that are waiting on the specified condition
    variable.

26.1  –  C Binding

    #include <pthread.h>

    int
    pthread_cond_broadcast (
             pthread_cond_t   *cond);

26.2  –  Arguments

 cond

    Condition variable upon which the threads (to be awakened) are
    waiting.

26.3  –  Description

    This routine unblocks all threads waiting on the specified
    condition variable cond. Calling this routine implies that data
    guarded by the associated mutex has changed, so that it might be
    possible for one or more waiting threads to proceed. The threads
    that are unblocked shall contend for the mutex according to their
    respective scheduling policies (if applicable).

    If only one of the threads waiting on a condition variable may be
    able to proceed, but one of those threads can proceed, then use
    pthread_cond_signal() instead.

    Whether the associated mutex is locked or unlocked, you can still
    call this routine. However, if predictable scheduling behavior is
    required, that mutex should then be locked by the thread calling
    the pthread_cond_broadcast() routine.

    If no threads are waiting on the specified condition variable,
    this routine takes no action. The broadcast does not propagate to
    the next condition variable wait.

26.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by cond is not a valid condition
                variable.

26.5  –  Associated Routines

       pthread_cond_destroy()
       pthread_cond_init()
       pthread_cond_signal()
       pthread_cond_timedwait()
       pthread_cond_wait()

27  –  pthread_cond_destroy

    Destroys a condition variable.

27.1  –  C Binding

    #include <pthread.h>

    int
    pthread_cond_destroy (
             pthread_cond_t   *cond);

27.2  –  Arguments

 cond

    Condition variable to be destroyed.

27.3  –  Description

    This routine destroys the condition variable specified by cond.
    This effectively uninitializes the condition variable. Call this
    routine when a condition variable will no longer be referenced.
    Destroying a condition variable allows the Threads Library to
    reclaim internal memory associated with the condition variable.

    It is safe to destroy an initialized condition variable upon
    which no threads are currently blocked. Attempting to destroy a
    condition variable upon which other threads are blocked results
    in unpredictable behavior.

    The results of this routine are unpredictable if the condition
    variable specified in cond either does not exist or is not
    initialized.

27.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by cond is not a valid condition
                variable.
    [EBUSY]     The object being referenced by cond is being
                referenced by another thread that is currently
                executing
                pthread_cond_wait()  or pthread_cond_timedwait() on
                the condition variable specified in cond.

27.5  –  Associated Routines

       pthread_cond_broadcast()
       pthread_cond_init()
       pthread_cond_signal()
       pthread_cond_timedwait()
       pthread_cond_wait()

28  –  pthread_cond_getname_np

    Obtains the object name from a condition variable object.

28.1  –  C Binding

    #include <pthread.h>

    int
    pthread_cond_getname_np (
             pthread_cond_t   *cond,
             char   *name,
             size_t   len);

28.2  –  Arguments

 cond

    Address of the condition variable object whose object name is to
    be obtained.

 name

    Location to store the obtained object name.

 len

    Length in bytes of buffer at the location specified by name.

28.3  –  Description

    This routine copies the object name from the condition variable
    object specified by the cond argument to the buffer at the
    location specified by the name argument. Before calling this
    routine, your program must allocate the buffer indicated by name.

    The object name is a C language string and provides an identifier
    that is meaningful to a person debugging a multithreaded
    application. The maximum number of characters in the object name
    is 31.

    If the specified condition variable object has not been
    previously set with an object name, this routine copies a C
    language null string into the buffer at location name.

28.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by cond is not a valid condition
                variable.

28.5  –  Associated Routines

       pthread_cond_setname_np()

29  –  pthread_cond_init

    Initializes a condition variable.

29.1  –  C Binding

    #include <pthread.h>

    int
    pthread_cond_init (
             pthread_cond_t   *cond,
             const pthread_condattr_t   *attr);

29.2  –  Arguments

 cond

    Condition variable to be initialized.

 attr

    Condition variable attributes object that defines the
    characteristics of the condition variable to be initialized.

29.3  –  Description

    This routine initializes the condition variable cond with
    attributes specified in the attr argument. If attr is NULL, the
    default condition variable attributes are used.

    A condition variable is a synchronization object used in
    conjunction with a mutex. A mutex controls access to data that
    is shared among threads; a condition variable allows threads to
    wait for that data to enter a defined state.

    Condition variables are not owned by a particular thread. Any
    associated storage is not automatically deallocated when the
    creating thread terminates.

    Use the macro PTHREAD_COND_INITIALIZER to initialize statically
    allocated condition variables to the default condition variable
    attributes. To invoke this macro, enter:

       pthread_cond_t condition = PTHREAD_COND_INITIALIZER

    When statically initialized, a condition variable should not also
    be initialized using pthread_cond_init(). Also, a statically
    initialized condition variable need not be destroyed using
    pthread_cond_destroy().

    Under certain circumstances it might be impossible to wait upon
    a statically initialized condition variable when the process
    virtual address space (or some other memory limit) is nearly
    exhausted. In such a case pthread_cond_wait() or pthread_cond_
    timedwait() can return [ENOMEM]. To avoid this possibility,
    initialize critical condition variables using pthread_cond_
    init().

29.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EAGAIN]    The system lacks the necessary resources to
                initialize another condition variable, or

                The system-imposed limit on the total number of
                condition variables under execution by a single user
                is exceeded.
    [EBUSY]     The implementation has detected an attempt to
                reinitialize the object referenced by cond, a
                previously initialized, but not yet destroyed
                condition variable.
    [EINVAL]    The value specified by attr is not a valid attributes
                object.
    [ENOMEM]    Insufficient memory exists to initialize the
                condition variable.

29.5  –  Associated Routines

       pthread_cond_broadcast()
       pthread_cond_destroy()
       pthread_cond_signal()
       pthread_cond_timedwait()
       pthread_cond_wait()

30  –  pthread_cond_setname_np

    Changes the object name for a condition variable object.

30.1  –  C Binding

    #include <pthread.h>

    int
    pthread_cond_setname_np (
             pthread_cond_t   *cond,
             const char   *name,
             void   *mbz);

30.2  –  Arguments

 cond

    Address of the condition variable object whose object name is to
    be changed.

 name

    Object name value to copy into the condition variable object.

 mbz

    Reserved for future use. The value must be zero (0).

30.3  –  Description

    This routine changes the object name in the condition variable
    object specified by the cond argument to the value specified
    by the name argument. To set a new condition variable object's
    object name, call this routine immediately after initializing the
    condition variable object.

    The object name is a C language string and provides an identifier
    that is meaningful to a person debugging a multithreaded
    application. The maximum number of characters in the object name
    is 31.

30.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by cond is not a valid condition
                variable object, or the length in characters of name
                exceeds 31.
    [ENOMEM]    Insufficient memory exists to create a copy of the
                object name string.

30.5  –  Associated Routines

       pthread_cond_getname_np()

31  –  pthread_cond_signal

    Wakes at least one thread that is waiting on the specified
    condition variable.

31.1  –  C Binding

    #include <pthread.h>

    int
    pthread_cond_signal (
             pthread_cond_t   *cond);

31.2  –  Arguments

 cond

    Condition variable to be signaled.

31.3  –  Description

    This routine unblocks at least one thread waiting on the
    specified condition variable cond. Calling this routine implies
    that data guarded by the associated mutex has changed, thus it
    might be possible for one of the waiting threads to proceed. In
    general, only one thread will be released.

    If no threads are waiting on the specified condition variable,
    this routine takes no action. The signal does not propagate to
    the next condition variable wait.

    This routine should be called when any thread waiting on the
    specified condition variable might find its predicate true,
    but only one thread should proceed. If more than one thread can
    proceed, or if any of the threads would not be able to proceed,
    then you must use pthread_cond_broadcast().

    The scheduling policy determines which thread is awakened. For
    policies SCHED_FIFO and SCHED_RR, a blocked thread is chosen
    in priority order, using first-in/first-out (FIFO) within
    priorities.

    If the calling thread holds the lock to the target condition
    variable's associated mutex while setting the variable's wait
    predicate, that thread can call pthread_cond_signal() to signal
    the variable even after releasing the lock on that mutex.
    However, for more predictable scheduling behavior, call pthread_
    cond_signal() before releasing the target condition variable's
    associated mutex.

31.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by cond is not a valid condition
                variable.

31.5  –  Associated Routines

       pthread_cond_broadcast()
       pthread_cond_destroy()
       pthread_cond_init()
       pthread_cond_timedwait()
       pthread_cond_wait()

32  –  pthread_cond_signal_int_np

    Wakes one thread that is waiting on the specified condition
    variable (called from interrupt level only).

32.1  –  C Binding

    #include <pthread.h>

    int
    pthread_cond_signal_int_np(
             pthread_cond_t   *cond);

32.2  –  Arguments

 cond

    Condition variable to be signaled.

32.3  –  Description

    This routine wakes one thread waiting on the specified condition
    variable. It can only be called from a software interrupt handler
    routine (such as from a Tru64 UNIX signal handler or OpenVMS
    AST). Calling this routine implies that it might be possible for
    a single waiting thread to proceed.

    The scheduling policies of the waiting threads determine which
    thread is awakened. For policies SCHED_FIFO and SCHED_RR, a
    blocked thread is chosen in priority order, using first-in/first-
    out (FIFO) within priorities.

    This routine does not cause a thread blocked on a condition
    variable to resume execution immediately. A thread resumes
    execution at some time after the interrupt handler routine
    returns. If no threads are waiting on the condition variable
    at the time of the call to pthread_cond_signal_int_np(), the next
    future waiting thread will be automatically released (that is,
    it will not actually wait). This routine establishes a "pending"
    wake if necessary.

    You can call this routine regardless of whether the associated
    mutex is either locked or unlocked. (Never lock a mutex from an
    interrupt handler routine.)

                                   NOTE

       This routine allows you to signal a condition variable from
       a software interrupt handler. Do not call this routine from
       noninterrupt code. To signal a condition variable from the
       normal noninterrupt level, use pthread_cond_signal().

32.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by cond is not a valid condition
                variable.

32.5  –  Associated Routines

       pthread_cond_broadcast()
       pthread_cond_signal()
       pthread_cond_sig_preempt_int_np()
       pthread_cond_timedwait()
       pthread_cond_wait()

33  –  pthread_cond_sig_preempt_int_np

    Wakes one thread that is waiting on the specified condition
    variable (called from interrupt level only).

33.1  –  C Binding

     void
    pthread_cond_sig_preempt_int_np (
             pthread_cond_t   *cond);

33.2  –  Arguments

 cond

    Condition variable signaled.

33.3  –  Description

    This routine wakes one thread waiting on a condition variable.
    It can only be called from a software interrupt handler routine.
    Calling this routine implies that it might be possible for a
    single waiting thread to proceed. Call this routine when any
    thread waiting on the specified condition variable might find its
    predicate true.

    The scheduling policies of the waiting threads determine which
    thread is awakened. For policies SCHED_FIFO and SCHED_RR, a
    blocked thread is chosen in priority order, using first-in/first-
    out (FIFO) within priorities.

    You can call this routine when the associated mutex is either
    locked or unlocked. (Never try to lock a mutex from an interrupt
    handler.)

    This routine allows you to signal a thread from a software
    interrupt handler. Do not call this routine from noninterrupt
    code. If you want to signal a thread from the normal noninterrupt
    level, use pthread_cond_signal.

                                   NOTE

       If a waiting thread has a preemptive scheduling policy and
       a higher priority than the thread which was running when
       the interrupt occurred, then the waiting thread will preempt
       the interrupt routine and begin to run immediately. This
       is unlike pthread_cond_signal_int_np() which causes the
       condition variable to be signaled at a safe point after
       the interrupt has completed. pthread_cond_sig_preempt_int_
       np() avoids the possible latency which pthread_cond_signal_
       int_np() may introduce; however, a side effect of this is
       that during the call to pthread_cond_sig_preempt_int_np()
       other threads may run if a preemption occurs. Thus, once an
       interrupt routine calls pthread_cond_sig_preempt_int_np()
       it can no longer rely on any assumptions of exclusivity
       or atomicity which are typically provided by interrupt
       routines. Furthermore, once the call to pthread_cond_sig_
       preempt_int_np() is made, in addition to other threads
       running, subsequent interrupts may be delivered at any time
       as well (that is, they will not be blocked until the current
       interrupt completes). For this reason, it is recommended
       that pthread_cond_sig_preempt_int_np() be called as the last
       statement in the interrupt routine.

33.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by cond is not a valid condition
                variable.

33.5  –  Associated Routines

       pthread_cond_broadcast()
       pthread_cond_signal()
       pthread_cond_signal_int_np()
       pthread_cond_timedwait()
       pthread_cond_wait()

34  –  pthread_cond_timedwait

    Causes a thread to wait for the specified condition variable
    to be signaled or broadcast, such that it will awake after a
    specified period of time.

34.1  –  C Binding

    #include <pthread.h>
    int
    pthread_cond_timedwait (
             pthread_cond_t   *cond,
             pthread_mutex_t   *mutex,
             const struct timespec   *abstime);

34.2  –  Arguments

 cond

    Condition variable that the calling thread waits on.

 mutex

    Mutex associated with the condition variable specified in cond.

 abstime

    Absolute time at which the wait expires, if the condition has not
    been signaled or broadcast. See the pthread_get_expiration_np()
    routine, which is used to obtain a value for this argument.

    The abstime argument is specified in Universal Coordinated Time
    (UTC). In the UTC-based model, time is represented as seconds
    since the Epoch. The Epoch is defined as the time 0 hours, 0
    minutes, 0 seconds, January 1st, 1970 UTC.

34.3  –  Description

    This routine causes a thread to wait until one of the following
    occurs:

    o  The specified condition variable is signaled or broadcast.

    o  The current system clock time is greater than or equal to the
       time specified by the abstime argument.

    This routine is identical to pthread_cond_wait(), except that
    this routine can return before a condition variable is signaled
    or broadcast, specifically, when the specified time expires. For
    more information, see the pthread_cond_wait() description.

    This routine atomically releases the mutex and causes the calling
    thread to wait on the condition. When the thread regains control
    after calling pthread_cond_timedwait(), the mutex is locked and
    the thread is the owner. This is true regardless of why the wait
    ended. If general cancelability is enabled, the thread reacquires
    the mutex (blocking for it if necessary) before the cleanup
    handlers are run (or before the exception is raised).

    If the current time equals or exceeds the expiration time, this
    routine returns immediately, releasing and reacquiring the mutex.
    It might cause the calling thread to yield (see the sched_yield()
    description). Your code should check the return status whenever
    this routine returns and take the appropriate action. Otherwise,
    waiting on the condition variable can become a nonblocking loop.

    Call this routine after you have locked the mutex specified
    in mutex. The results of this routine are unpredictable if
    this routine is called without first locking the mutex. The
    only routines that are supported for use with asynchronous
    cancelability enabled are those that disable asynchronous
    cancelability.

34.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by cond, mutex, or abstime is
                invalid, or

                Different mutexes are supplied for concurrent
                pthread_cond_timedwait()  operations or
                pthread_cond_wait()  operations on the same condition
                variable, or

                The mutex was not owned by the calling thread at the
                time of the call.
    [ETIMEDOUT] The time specified by abstime expired.
    [ENOMEM]    The Threads Library cannot acquire memory needed
                to block using a statically initialized condition
                variable.

34.5  –  Associated Routines

       pthread_cond_broadcast()
       pthread_cond_destroy()
       pthread_cond_init()
       pthread_cond_signal()
       pthread_cond_wait()
       pthread_get_expiration_np()

35  –  pthread_cond_wait

    Causes a thread to wait for the specified condition variable to
    be signaled or broadcast.

35.1  –  C Binding

    #include <pthread.h>

    int
    pthread_cond_wait (
             pthread_cond_t   *cond,
             pthread_mutex_t   *mutex);

35.2  –  Arguments

 cond

    Condition variable that the calling thread waits on.

 mutex

    Mutex associated with the condition variable specified in cond.

35.3  –  Description

    This routine causes a thread to wait for the specified condition
    variable to be signaled or broadcast. Each condition corresponds
    to one or more Boolean relations, called a predicate, based on
    shared data. The calling thread waits for the data to reach a
    particular state for the predicate to become true. However, the
    return from this routine does not imply anything about the value
    of the predicate and it should be reevaluated upon return.

    Call this routine after you have locked the mutex specified in
    mutex. The results of this routine are unpredictable if this
    routine is called without first locking the mutex.

    This routine atomically releases the mutex and causes the calling
    thread to wait on the condition. When the thread regains control
    after calling pthread_cond_wait(), the mutex is locked and the
    thread is the owner. This is true regardless of why the wait
    ended. If general cancelability is enabled, the thread reacquires
    the mutex (blocking for it if necessary) before the cleanup
    handlers are run (or before the exception is raised).

    A thread that changes the state of storage protected by the
    mutex in such a way that a predicate associated with a condition
    variable might now be true, must call either pthread_cond_
    signal() or pthread_cond_broadcast()  for that condition
    variable. If neither call is made, any thread waiting on the
    condition variable continues to wait.

    This routine might (with low probability) return when the
    condition variable has not been signaled or broadcast. When
    this occurs, the mutex is reacquired before the routine returns.
    To handle this type of situation, enclose each call to this
    routine in a loop that checks the predicate. The loop provides
    documentation of your intent and protects against these spurious
    wakeups, while also allowing correct behavior even if another
    thread consumes the desired state before the awakened thread
    runs.

    It is illegal for threads to wait on the same condition variable
    by specifying different mutexes.

    The only routines that are supported for use with asynchronous
    cancelability enabled are those that disable asynchronous
    cancelability.

35.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by cond or mutex is invalid, or

                Different mutexes are supplied for concurrent
                pthread_cond_wait()  or pthread_cond_timedwait()
                operations on the same condition variable, or

                The mutex was not owned by the calling thread at the
                time of the call.
    [ENOMEM]    The Threads Library cannot acquire memory needed
                to block using a statically initialized condition
                variable.

35.5  –  Associated Routines

       pthread_cond_broadcast()
       pthread_cond_destroy()
       pthread_cond_init()
       pthread_cond_signal()
       pthread_cond_timedwait()

36  –  pthread_condattr_destroy

    Destroys a condition variable attributes object.

36.1  –  C Binding

    #include <pthread.h>

    int
    pthread_condattr_destroy (
             pthread_condattr_t   *attr);

36.2  –  Arguments

 attr

    Condition variable attributes object to be destroyed.

36.3  –  Description

    This routine destroys the specified condition variable attributes
    object. Call this routine when a condition variable attributes
    object will no longer be referenced.

    Condition variables that were created using this attributes
    object are not affected by the destruction of the condition
    variable attributes object.

    The results of calling this routine are unpredictable if the
    value specified by the attr argument refers to a condition
    variable attributes object that does not exist.

36.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The attributes object specified by attr is invalid.

36.5  –  Associated Routines

       pthread_condattr_init()

37  –  pthread_condattr_init

    Initializes a condition variable attributes object.

37.1  –  C Binding

    #include <pthread.h>

    int
    pthread_condattr_init (
             pthread_condattr_t   *attr);

37.2  –  Arguments

 attr

    Address of the condition variable attributes object to be
    initialized.

37.3  –  Description

    This routine initializes the condition variable attributes object
    specified by the attr argument with a set of default attribute
    values.

    When an attributes object is used to create a condition
    variable, the values of the individual attributes determine the
    characteristics of the new condition variable. Attributes objects
    act as additional arguments to condition variable creation.
    Changing individual attributes in an attributes object does not
    affect any condition variables that were previously created using
    that attributes object.

    You can use the same condition variable attributes object in
    successive calls to pthread_condattr_init(), from any thread.
    If multiple threads can change attributes in a shared attributes
    object, your program must use a mutex to protect the integrity of
    that attributes object.

    Results are undefined if this routine is called and the attr
    argument specifies a condition variable attributes object that is
    already initialized.

    Currently, on OpenVMS systems, no attributes affecting condition
    variables are defined; you cannot change any attributes in the
    condition variable attributes object. On Tru64 UNIX systems, the
    PSHARED attribute is defined.

    The pthread_condattr_init() and pthread_condattr_destroy()
    routines are provided for future expandability of the pthread
    interface and to conform with the POSIX.1 standard. These
    routines serve no useful function, because there are no pthread_
    condattr_set*() type routines available at this time.

37.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by attr is not a valid condition
                variable attributes object.
    [ENOMEM]    Insufficient memory exists to initialize the
                condition variable attributes object.

37.5  –  Associated Routines

       pthread_condattr_destroy()
       pthread_cond_init()

38  –  pthread_create

    Creates a thread.

38.1  –  C Binding

    #include <pthread.h>

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

38.2  –  Arguments

 thread

    Location for thread object to be created.

 attr

    Thread attributes object that defines the characteristics of the
    thread being created. If you specify NULL, default attributes are
    used.

 start_routine

    Function executed as the new thread's start routine.

 arg

    Address value copied and passed to the thread's start routine.

38.3  –  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:

    o  The Threads Library 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 platforms.)

    o  The thread argument receives an identifier for the new thread.

    o  An executable thread is created with attributes specified
       by the attr argument (or with default attributes if NULL is
       specified).

    Thread Creation
    The Threads Library creates a thread in the ready state and
    prepares the thread to begin executing its start routine,
    the function passed to pthread_create() 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() can
    synchronize with the new thread using the pthread_join() routine
    or using any mutually agreed upon mutexes, condition variables or
    read-write locks.

    For the duration of the new thread's existence, the Threads
    Library 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() or pthread_join()  for the thread.
    Termination is explained in the next section (see Thread
    Termination).

    The Threads Library assigns each new thread a thread identifier,
    which is written into the address specified as the pthread_
    create() routine's thread argument. The new thread's thread
    identifier is written 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() 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(), your program must use the pthread_attr_
    setinheritsched() 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:

    1. The signal mask is inherited from the creating thread.

    2. The set of signals pending for the new thread is empty.

    If pthread_create() 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:

    o  The thread returns from its start routine.

    o  The thread calls the pthread_exit() routine.

    o  The thread is canceled.

    When a thread terminates, the following actions are performed:

    1. A return value (if one is available) is written into the
       terminated thread's thread object, as follows:

       o  If the thread has been canceled, the value PTHREAD_CANCELED
          is written into the thread's thread object.

       o  If the thread terminated by returning from its start
          routine, the return value is copied from the start routine
          (if one is available) into the thread's thread object.
          Alternatively, if the thread explicitly called pthread_
          exit(), the value received in the value_ptr argument (from
          pthread_exit()) is stored in the thread's thread object.

       Another thread can obtain this return value by joining with
       the terminated thread (using pthread_join()).

                                      NOTE

          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.

    2. If the termination results from a cancelation request or a
       call to pthread_exit(), the Threads Library calls, in turn,
       each cleanup handler that this thread declared (using pthread_
       cleanup_push()) and that is not yet removed (using pthread_
       cleanup_pop()). (The Threads Library also transfers control to
       any appropriate CATCH, CATCH_ALL, or FINALLY blocks .)

       The Threads Library 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.

    3. To exit the terminated thread due to a call to pthread_exit(),
       the Threads Library raises the pthread_exit_e exception. To
       exit the terminated thread due to cancelation, the Threads
       Library raises the pthread_cancel_e exception.

       Your program can use the exception package to operate on the
       generated exception. (In particular, note that the practice of
       using CATCH handlers in place of pthread_cleanup_push() is not
       portable.)

    4. For each of the terminated thread's thread-specific data keys
       that has a non-NULL value:

       o  The thread's value for the corresponding key is set to
          NULL.

       o  Call each thread-specific data destructor function in this
          multithreaded process' list of destructors.

       Repeat 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.

    5. Awaken the thread (if there is one) that is currently waiting
       to join with the terminated thread. That is, awaken the thread
       that is waiting in a call to pthread_join().

    6. If the thread is already detached, destroy its thread object.
       Otherwise, the thread continues to exist until detached or
       joined with.

38.4  –  Return Values

    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:

    Return      Description

    0           Successful completion.
    [EAGAIN]    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.
    [EINVAL]    The value specified by attr is not a valid attributes
                block.
    [ENOMEM]    Insufficient memory exists to create a thread.
    [EPERM]     The caller does not have the appropriate permission
                to create a thread with the specified attributes.

38.5  –  Associated Routines

       pthread_atfork()
       pthread_attr_destroy()
       pthread_attr_init()
       pthread_attr_setdetachstate()
       pthread_attr_setinheritsched()
       pthread_attr_setschedparam()
       pthread_attr_setschedpolicy()
       pthread_attr_setstacksize()
       pthread_cancel()
       pthread_detach()
       pthread_exit()
       pthread_join()

39  –  pthread_delay_np

    Delays a thread's execution.

39.1  –  C Binding

    #include <pthread.h>

    int
    pthread_delay_np (
             const struct timespec   *interval);

39.2  –  Arguments

 interval

    Number of seconds and nanoseconds to delay execution. The value
    specified for each must be greater than or equal to zero.

39.3  –  Description

    This routine causes a thread to delay execution for a specific
    interval of time. This interval ends at the current time plus the
    specified interval. The routine will not return before the end
    of the interval is reached, but may return an arbitrary amount of
    time after the end of the interval is reached. This can be due to
    system load, thread priorities, and system timer granularity.

    Specifying an interval of zero (0) seconds and zero (0)
    nanoseconds is allowed and can be used to force the thread either
    to give up the processor or to deliver a pending cancelation
    request.

    The timespec structure contains the following two fields:

    o  tv_sec is an integral number of seconds.

    o  tv_nsec is an integral number of nanoseconds.

39.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by interval is invalid.

40  –  pthread_detach

    Marks a thread object for deletion.

40.1  –  C Binding

    #include <pthread.h>

    int
    pthread_detach (
             pthread_t   thread);

40.2  –  Arguments

 thread

    Thread object being marked for deletion.

40.3  –  Description

    This routine marks the specified thread object to indicate that
    storage for the corresponding thread can be reclaimed when
    the thread terminates. This includes storage for the thread
    argument's return value, as well as the thread object. If thread
    has not terminated when this routine is called, this routine does
    not cause it to terminate.

    When a thread object is no longer referenced, call this routine.

    The results of this routine are unpredictable if the value of
    thread refers to a thread object that does not exist.

    You can create a thread already detached by setting its thread
    object's detachstate attribute.

    The pthread_join() routine also detaches the target thread after
    pthread_join() returns successfully.

40.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by thread does not refer to a
                joinable thread.
    [ESRCH]     The value specified by thread cannot be found.

40.5  –  Associated Routines

       pthread_cancel()
       pthread_create()
       pthread_exit()
       pthread_join()

41  –  pthread_equal

    Compares one thread identifier to another thread identifier.

41.1  –  C Binding

    #include <pthread.h>

    int
    pthread_equal (
             pthread_t   t1,
             pthread_t   t2);

41.2  –  Arguments

 t1

    The first thread identifier to be compared.

 t2

    The second thread identifier to be compared.

41.3  –  Description

    This routine compares one thread identifier to another thread
    identifier.

    If either t1 or t2 are not valid thread identifiers, this
    routine's behavior is undefined.

41.4  –  Return Values

    Possible return values are as follows:

    Return      Description

    0           Values of t1 and t2 do not designate the same object.
    Non-zero    Values of t1 and t2 designate the same object.

42  –  pthread_exc_get_status_np

    (Macro) Obtains a system-defined error status from a status
    exception object.

42.1  –  C Binding

    #include <pthread_exception.h>

    int
    pthread_exc_get_status_np (
             EXCEPTION    *exception,
             unsigned long    *code);

42.2  –  Arguments

 exception

    Threads Library status exception object whose status code is
    obtained.

 code

    Receives the system-specific status code associated with the
    specified status exception object.

42.3  –  Description

    This routine obtains and returns the system-specific status
    value from the status exception object specified in the exception
    argument. This value must have already been associated with the
    exception object using the pthread_exc_set_status_np() routine.

    In a program that uses Threads Library status exceptions, use
    this routine within a CATCH or CATCH_ALL code block to obtain the
    status code value associated with a caught exception. Note that
    any exception objects set to the same status value are considered
    equivalent by the Threads Library.

42.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. If the routine's exception
    object argument is a status exception, it sets the code argument
    and returns zero (0). Possible return values are as follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The exception argument is not a valid status
                exception object.

42.5  –  Associated Routines

       pthread_exc_set_status_np()

43  –  pthread_exc_matches_np

    (Macro) Determines whether two Threads Library exception objects
    are identical.

43.1  –  C Binding

    #include <pthread_exception.h>

    int
    pthread_exc_matches_np (
             EXCEPTION    *exception1,
             EXCEPTION    *exception2);

43.2  –  Arguments

 exception1

    Threads Library exception object.

 exception2

    Threads Library exception object.

43.3  –  Description

    This routine compares two exception objects, taking into
    consideration whether each is an address exception or status
    exception.

    This routine returns either the C language value TRUE or the
    C language value FALSE, indicating whether the two exception
    objects specified in the arguments exception1 and exception2 are
    identical.

43.4  –  Return Values

    The C language value TRUE if the exception objects are identical,
    or the C language value FALSE if not.

43.5  –  Associated Routines

       pthread_exc_get_status_np()
       pthread_exc_report_np()
       pthread_exc_set_status_np()

44  –  pthread_exc_report_np

    Produces a message that reports what a specified Threads Library
    status exception object represents.

44.1  –  C Binding

    #include <pthread_exception.h>

    void
    pthread_exc_report_np (
             EXCEPTION    *exception);

44.2  –  Arguments

 exception

    Threads Library exception object that has been set with a status
    value.

44.3  –  Description

    This routine produces a text message on the stderr device
    (Tru64 UNIX systems) or SYS$ERROR device (OpenVMS systems) that
    describes the exception whose exception object is specified in
    the exception argument.

    In a program that uses status exceptions, use this routine within
    a CATCH or CATCH_ALL code block to produce the message associated
    with a caught exception. Note that any exception objects set to
    the same status value are considered equivalent by the Threads
    Library.

44.4  –  Return Values

    None

44.5  –  Associated Routines

       pthread_exc_get_status_np()
       pthread_exc_set_status_np()

45  –  pthread_exc_set_status_np

    (Macro) Imports a system-defined error status into a Threads
    Library address exception object.

45.1  –  C Binding

    #include <pthread_exception.h>

    void
    pthread_exc_set_status_np (
             EXCEPTION    *exception,
             unsigned long   code);

45.2  –  Arguments

 exception

    Threads Library address exception object into which the specified
    status code is imported.

 code

    System-specific status code to be imported.

45.3  –  Description

    This routine associates a system-specific status value with the
    specified address exception object. This transforms the address
    exception object into a status exception object.

    The exception argument must already have been initialized with
    the exception package's EXCEPTION_INIT macro.

    Use this routine to associate any system-specific status value
    with the specified address exception object. Note that any
    exception objects set to the same status value are considered
    equivalent by the Threads Library.

45.4  –  Return Values

    None

45.5  –  Associated Routines

       pthread_exc_get_status_np()

46  –  pthread_exit

    Terminates the calling thread.

46.1  –  C Binding

    #include <pthread.h>

    void
    pthread_exit (
             void   *value_ptr);

46.2  –  Arguments

 value_ptr

    Value copied and returned to the caller of pthread_join(). Note
    that void * is used as a universal datatype, not as a pointer.
    The Threads Library treats the value_ptr as a value and stores it
    to be returned by pthread_join().

46.3  –  Description

    This routine terminates the calling thread and makes a status
    value (value_ptr) available to any thread that calls pthread_
    join() and specifies the terminating thread.

    Any cleanup handlers that have been pushed and not yet popped
    from the stack are popped in the reverse order that they were
    pushed and then executed. After all cleanup handlers have been
    executed, appropriate destructor functions are called in an
    unspecified order if the thread has any thread-specific data.
    Thread termination does not release any application-visible
    process resources, including, but not limited to mutexes and
    file descriptors, nor does it perform any process-level cleanup
    actions, including, but not limited to calling any atexit()
    routine that may exist.

    The Threads Library issues an implicit call to pthread_exit()
    when a thread returns from the start routine that was used to
    create it. The Threads Library writes the function's return value
    as the return value in the thread's thread object. The process
    exits when the last running thread calls pthread_exit().

    After a thread has terminated, the result of access to local
    (that is, explicitly or implicitly declared auto) variables
    of the thread is undefined. So, do not use references to local
    variables of the existing thread for the value_ptr argument of
    the pthread_exit() routine.

46.4  –  Return Values

    None

46.5  –  Associated Routines

       pthread_cancel()
       pthread_create()
       pthread_detach()
       pthread_join()

47  –  pthread_get_expiration_np

    Obtains a value representing a desired expiration time.

47.1  –  C Binding

    #include <pthread.h>

    int
    pthread_get_expiration_np (
                const struct timespec   *delta,
                struct timespec   *abstime);

47.2  –  Arguments

 delta

    Number of seconds and nanoseconds to add to the current system
    time. (The result is the time in the future.) This result will be
    placed in abstime.

 abstime

    Value representing the absolute expiration time. The absolute
    expiration time is obtained by adding delta to the current system
    time. The resulting abstime is in Universal Coordinated Time
    (UTC).

47.3  –  Description

    This routine adds a specified interval to the current absolute
    system time and returns a new absolute time. This new absolute
    time may then be used as the expiration time in a call to
    pthread_cond_timedwait().

    The timespec structure contains the following two fields:

    o  tv_sec is an integral number of seconds.

    o  tv_nsec is an integral number of nanoseconds.

47.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by delta is invalid.

47.5  –  Associated Routines

       pthread_cond_timedwait()

48  –  pthread_getconcurrency

    Obtains the value of the concurrency level global variable for
    this process.

48.1  –  C Binding

    #include <pthread.h>

    int
    pthread_getconcurrency (
                void);

48.2  –  Description

    This routine obtains and returns the value of the "concurrency
    level" global setting for the calling thread's process. Because
    the Threads Library automatically manages the concurrency of all
    threads in a multithreaded process, it ignores this concurrency
    level value.

    The concurrency level value has no effect on the behavior of a
    multithreaded program that uses the Threads Library. This routine
    is provided for Single UNIX Specification, Version 2, source code
    compatibility and has no other effect when called.

    The initial concurrency level is zero (0), indicating that the
    Threads Library controls the concurrency level.

    The concurrency level can be set using the pthread_
    setconcurrency() routine.

48.3  –  Return Values

    This routine always returns the value of this process'
    concurrency level global variable. If this process has never
    called the pthread_setconcurrency() routine, this routine returns
    zero (0).

48.4  –  Associated Routines

       pthread_setconcurrency()

49  –  pthread_getname_np

    Obtains the object name from the thread object for an existing
    thread.

49.1  –  C Binding

    #include <pthread.h>

    int
    pthread_getname_np (
             pthread_thread_t   thread,
             char   *name,
             size_t   len);

49.2  –  Arguments

 thread

    Thread object whose object name is to be obtained.

 name

    Location to store the obtained object name.

 len

    Length in bytes of buffer at the location specified by name.

49.3  –  Description

    This routine copies the object name from the thread object
    specified by the thread argument to the buffer at the location
    specified by the name argument. Before calling this routine, your
    program must allocate the buffer indicated by name.

    The object name is a C language string and provides an identifier
    that is meaningful to a person debugging a multithreaded
    application. The maximum number of characters in the object name
    is 31.

    If the specified thread object has not been previously set with
    an object name, this routine copies a C language null string into
    the buffer at location name.

49.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [ESRCH]     The thread specified by thread does not exist.

49.5  –  Associated Routines

       pthread_setname_np()

50  –  pthread_getschedparam

    Obtains the current scheduling policy and scheduling parameters
    of a thread.

50.1  –  C Binding

    #include <pthread.h>

    int
    pthread_getschedparam (
             pthread_t   thread,
             int   *policy,
             struct sched_param   *param);

50.2  –  Arguments

 thread

    Thread whose scheduling policy and parameters are obtained.

 policy

    Receives the value of the scheduling policy for the thread
    specified in thread. Refer to the description of the pthread_
    setschedparam() routine for valid policies and their meanings.

 param

    Receives the value of the scheduling parameters for the thread
    specified in thread. Refer to the description of the pthread_
    setschedparam() routine for valid values.

50.3  –  Description

    This routine obtains both the current scheduling policy and
    associated scheduling parameters of the thread specified by the
    thread argument.

    The priority value returned in the param structure is the value
    specified either in the attr argument passed to pthread_create()
    or by the most recent call to pthread_setschedparam() that
    affects the target thread.

    This routine differs from pthread_attr_getschedpolicy() and
    pthread_attr_getschedparam(), in that those routines get the
    scheduling policy and parameter attributes that are used to
    establish the priority and scheduling policy of a new thread
    when it is created. This routine, however, obtains the scheduling
    policy and parameters of an existing thread.

50.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [ESRCH]     The value specified by thread does not refer to an
                existing thread.

50.5  –  Associated Routines

       pthread_attr_getschedparam()
       pthread_attr_getschedpolicy()
       pthread_create()
       pthread_self()
       pthread_setschedparam()

51  –  pthread_getsequence_np

    Obtains the unique identifier for the specified thread.

51.1  –  C Binding

    #include <pthread.h>

    unsigned long
    pthread_getsequence_np (
             pthread_t   thread);

51.2  –  Arguments

 thread

    Thread whose sequence number is to be obtained.

51.3  –  Description

    This routine obtains and returns the thread sequence number
    for the thread identified by the thread object specified in the
    thread argument.

    The thread sequence number provides a unique identifier for each
    existing thread. A thread's thread sequence number is never
    reused while the thread exists, but can be reused after the
    thread terminates. The debugger interfaces use this sequence
    number to identify each thread in commands and in display output.

    The result of calling this routine is undefined if the thread
    argument does not specify a valid thread object.

51.4  –  Return Values

    No errors are returned. This routine returns the thread sequence
    number for the thread identified by the thread object specified
    in the thread argument. The result of calling this routine is
    undefined if the thread argument does not specify a valid thread.

51.5  –  Associated Routines

       pthread_create()
       pthread_self()

52  –  pthread_getspecific

    Obtains the thread-specific data associated with the specified
    key.

52.1  –  C Binding

    #include <pthread.h>

    void
    *pthread_getspecific (
                pthread_key_t   key);

52.2  –  Arguments

 key

    The context key identifies the thread-specific data to be
    obtained.

52.3  –  Description

    This routine obtains the thread-specific data associated with the
    specified key for the current thread. Obtain this key by calling
    the pthread_key_create() routine. This routine returns the value
    currently bound to the specified key on behalf of the calling
    thread.

    This routine may be called from a thread-specific data destructor
    function.

52.4  –  Return Values

    No errors are returned. This routine returns the thread-specific
    data value associated with the specified key argument. If no
    thread-specific data value is associated with key, or if key is
    not defined, then this routine returns a NULL value.

52.5  –  Associated Routines

       pthread_key_create()
       pthread_setspecific()

53  –  pthread_join

                   PTHREAD_JOIN32(),  PTHREAD_JOIN64()

       The pthread_join32() and pthread_join64() forms are only
       valid in 64-bit pointer environments for OpenVMS Alpha.
       Ensure that your compiler provides 64-bit support before you
       use pthread_join64().

    Causes the calling thread to wait for the termination of a
    specified thread.

53.1  –  C Binding

    #include <pthread.h>

    int
    pthread_join (
             pthread_t   thread,
             void   **value_ptr);

53.2  –  Arguments

 thread

    Thread whose termination is awaited by the calling routine.

 value_ptr

    Return value of the terminating thread (when that thread either
    calls pthread_exit() or returns from its start routine).

53.3  –  Description

    This routine suspends execution of the calling thread until the
    specified target thread thread terminates.

    On return from a successful pthread_join() call with a non-
    NULL value_ptr argument, the value passed to pthread_exit()
    is returned in the location referenced by value_ptr, and the
    terminating thread is detached.

    If more than one thread attempts to join with the same thread,
    the results are unpredictable.

    A call to pthread_join() returns after the target thread
    terminates. The pthread_join() routine is a deferred cancelation
    point; the target thread will not be detached if the thread
    blocked in pthread_join() is canceled.

    If a thread calls this routine and specifies its own pthread_t, a
    deadlock can result.

    The pthread_join() (or pthread_detach())  routine should
    eventually be called for every thread that is created with the
    detachstate attribute of its thread object set to PTHREAD_CREATE_
    JOINABLE, so that storage associated with the thread can be
    reclaimed.

                                   NOTE

       For OpenVMS Alpha systems:
       The pthread_join() routine is defined to pthread_join64()
       if you compile using /pointer_size=long. If you do not
       specify /pointer_size, or if you specify /pointer_
       size=short, then pthread_join() is defined to be pthread_
       join32(). You can call pthread_join32() or pthread_join64()
       instead of pthread_join(). The pthread_join32() form
       returns a 32-bit void * value in the address to which
       value_ptr points. The pthread_join64() form returns a 64-
       bit void * value. You can call either, or you can call
       pthread_join(). Note that if you call pthread_join32() and
       the thread with which you join returns a 64-bit value, the
       high 32 bits of which are not 0 (zero), the Threads Library
       discards those high bits with no warning.

53.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by thread does not refer to a
                joinable thread.
    [ESRCH]     The value specified by thread does not refer to an
                existing thread ID.
    [EDEADLK]   A deadlock was detected, or thread specifies the
                calling thread.

53.5  –  Associated Routines

       pthread_cancel()
       pthread_create()
       pthread_detach()
       pthread_exit()

54  –  pthread_key_create

    Generates a unique thread-specific data key.

54.1  –  C Binding

    #include <pthread.h>

    int
    pthread_key_create (
             pthread_key_t   *key,
             void   (*destructor)(void *));

54.2  –  Arguments

 key

    Location where the new thread-specific data key will be stored.

 destructor

    Procedure called to destroy a thread-specific data value
    associated with the created key when the thread terminates.
    Note that the argument to the destructor for the user-specified
    routine is the non-NULL value associated with a key.

54.3  –  Description

    This routine generates a unique, thread-specific data key that
    is visible to all threads in the process. The variable key
    provided by this routine is an opaque object used to locate
    thread-specific data. Although the same key value can be used
    by different threads, the values bound to the key by pthread_
    setspecific() are maintained on a per-thread basis and persist
    for the life of the calling thread. The initial value of the key
    in all threads is NULL.

    The Threads Library imposes a maximum number of thread-specific
    data keys, equal to the symbolic constant PTHREAD_KEYS_MAX.

    Thread-specific data allows client software to associate "static"
    information with the current thread. For example, where a routine
    declares a variable static in a single-threaded program, a
    multithreaded version of the program might create a thread-
    specific data key to store the same variable.

    This routine generates and returns a new key value. The key
    reserves a cell within each thread. Each call to this routine
    creates a new cell that is unique within an application
    invocation. Keys must be generated from initialization code that
    is guaranteed to be called only once within each process. (See
    the pthread_once() description for more information.)

    When a thread terminates, its thread-specific data is
    automatically destroyed; however, the key remains unless
    destroyed by a call to pthread_key_delete(). An optional
    destructor function can be associated with each key. At thread
    exit, if a key has a non-NULL destructor pointer, and the thread
    has a non-NULL value associated with that key, the destructor
    function is called with the current associated value as its sole
    argument. The order in which thread-specific data destructors are
    called at thread termination is undefined.

    Before each destructor is called, the thread's value for the
    corresponding key is set to NULL. After the destructors have been
    called for all non-NULL values with associated destructors, if
    there are still some non-NULL values with associated destructors,
    then this sequence of actions is repeated. If there are still
    non-NULL values for any key with a destructor after four
    repetitions of this sequence, the thread is terminated. At this
    point, any key values that represent allocated heap will be lost.
    Note that this occurs only when a destructor performs some action
    that creates a new value for some key. Your program's destructor
    code should attempt to avoid this sort of circularity.

54.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EAGAIN]    The system lacked the necessary resources to create
                another thread-specific data key, or the limit on the
                total number of keys per process (PTHREAD_KEYS_MAX)
                has been exceeded.
    [ENOMEM]    Insufficient memory exists to create the key.

54.5  –  Associated Routines

       pthread_getspecific()
       pthread_key_delete()
       pthread_once()
       pthread_setspecific()

55  –  pthread_key_delete

    Deletes a thread-specific data key.

55.1  –  C Binding

    #include <pthread.h>

    int
    pthread_key_delete (
             pthread_key_t   key);

55.2  –  Arguments

 key

    Context key to be deleted.

55.3  –  Description

    This routine deletes the thread-specific data key specified by
    the key argument, which must have been previously returned by
    pthread_key_create().

    The thread-specific data values associated with key need not be
    NULL at the time this routine is called. The application must
    free any application storage or perform any cleanup actions for
    data structures related to the deleted key or associated thread-
    specific data in any threads. This cleanup can be done either
    before or after this routine is called.

    Attempting to use the key after calling this routine results in
    unpredictable behavior.

    No destructor functions are invoked by this routine. Any
    destructor functions that may have been associated with key shall
    no longer be called upon thread exit. pthread_key_delete() can be
    called from within destructor functions.

55.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The key value is not a valid key.

55.5  –  Associated Routines

       pthread_exit()
       pthread_getspecific()
       pthread_key_create()

56  –  pthread_key_getname_np

    Obtains the object name from a thread-specific data key object.

56.1  –  C Binding

    #include <pthread.h>

    int
    pthread_key_getname_np (
             pthread_key_t   *key,
             char   *name,
             size_t   len);

56.2  –  Arguments

 key

    Address of the thread-specific data key object whose object name
    is to be obtained.

 name

    Location to store the obtained object name.

 len

    Length in bytes of buffer at the location specified by name.

56.3  –  Description

    This routine copies the object name from the thread-specific
    data key object specified by the key argument to the buffer at
    the location specified by the name argument. Before calling this
    routine, your program must allocate the buffer indicated by name.

    The object name is a C language string and provides an identifier
    that is meaningful to a person debugging a multithreaded
    application. The maximum number of characters in the object name
    is 31.

    If the specified thread-specific data key object has not been
    previously set with an object name, this routine copies a C
    language null string into the buffer at location name.

56.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by key is not a valid key.

56.5  –  Associated Routines

       pthread_key_setname_np()

57  –  pthread_key_setname_np

    Changes the object name in a thread-specific data key object.

57.1  –  C Binding

    #include <pthread.h>

    int
    pthread_key_setname_np (
             pthread_key_t   *cond,
             const char   *name,
             void   *mbz);

57.2  –  Arguments

 key

    Address of the thread-specific data key object whose object name
    is to be changed.

 name

    Object name value to copy into the key object.

 mbz

    Reserved for future use. The value must be zero (0).

57.3  –  Description

    This routine changes the object name in the thread-specific
    data key object specified by the key argument to the value
    specified by the name argument. To set a new thread-specific data
    key object's object name, call this routine immediately after
    initializing the key object.

    The object name is a C language string and provides an identifier
    that is meaningful to a person debugging a multithreaded
    application. The maximum number of characters in the object name
    is 31.

57.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by key is not a valid key, or the
                length in characters of name exceeds 31.
    [ENOMEM]    Insufficient memory exists to create a copy of the
                object name string.

57.5  –  Associated Routines

       pthread_key_getname_np()

58  –  pthread_lock_global_np

    Locks the Threads Library global mutex.

58.1  –  C Binding

    #include <pthread.h>

    int
    pthread_lock_global_np (void);

58.2  –  Arguments

    None

58.3  –  Description

    This routine locks the Threads Library global mutex. If the
    global mutex is currently held by another thread when a thread
    calls this routine, the calling thread waits for the global mutex
    to become available and then locks it.

    The thread that has locked the global mutex becomes its current
    owner and remains the owner until the same thread has unlocked
    it. This routine returns with the global mutex in the locked
    state and with the current thread as the global mutex's current
    owner.

    Use the global mutex when calling a library package that is
    not designed to run in a multithreaded environment. Unless the
    documentation for a library function specifically states that it
    is thread-safe, assume that it is not compatible; in other words,
    assume it is nonreentrant.

    The global mutex is one lock. Any code that calls any function
    that is not known to be reentrant should use the same lock.
    This prevents problems resulting from dependencies among threads
    that call library functions and those functions' calling other
    functions, and so on.

    The global mutex is a recursive mutex. A thread that has locked
    the global mutex can relock it without deadlocking. The locking
    thread must call pthread_unlock_global_np() as many times as it
    called this routine, to allow another thread to lock the global
    mutex.

58.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.

58.5  –  Associated Routines

       pthread_unlock_global_np()

59  –  pthread_mutex_destroy

    Destroys a mutex.

59.1  –  C Binding

    #include <pthread.h>

    int
    pthread_mutex_destroy (
             pthread_mutex_t   *mutex);

59.2  –  Arguments

 mutex

    The mutex to be destroyed.

59.3  –  Description

    This routine destroys the specified mutex by uninitializing it,
    and should be called when a mutex object is no longer referenced.
    After this routine is called, the Threads Library may reclaim
    internal storage used by the specified mutex.

    It is safe to destroy an initialized mutex that is unlocked.
    However, it is illegal to destroy a locked mutex.

    The results of this routine are unpredictable if the mutex object
    specified in the mutex argument does not currently exist, or is
    not initialized.

59.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EBUSY]     An attempt was made to destroy the object referenced
                by mutex while it is locked.
    [EINVAL]    The value specified by mutex is not a valid mutex.

59.5  –  Associated Routines

       pthread_mutex_init()
       pthread_mutex_lock()
       pthread_mutex_trylock()
       pthread_mutex_unlock()

60  –  pthread_mutex_getname_np

    Obtains the object name from a mutex object.

60.1  –  C Binding

    #include <pthread.h>

    int
    pthread_mutex_getname_np (
             pthread_mutex_t   *mutex,
             char   *name,
             size_t   len);

60.2  –  Arguments

 mutex

    Address of the mutex object whose object name is to be obtained.

 name

    Location to store the obtained object name.

 len

    Length in bytes of buffer at the location specified by name.

60.3  –  Description

    This routine copies the object name from the mutex object
    specified by the mutex argument to the buffer at the location
    specified by the name argument. Before calling this routine, your
    program must allocate the buffer indicated by name.

    The object name is a C language string and provides an identifier
    that is meaningful to a person debugging a multithreaded
    application. The maximum number of characters in the object name
    is 31.

    If the specified condition variable object has not been
    previously set with an object name, this routine copies a C
    language null string into the buffer at location name.

60.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by mutex is not a valid mutex.

60.5  –  Associated Routines

       pthread_mutex_setname_np()

61  –  pthread_mutex_init

    Initializes a mutex.

61.1  –  C Binding

    #include <pthread.h>

    int
    pthread_mutex_init (
             pthread_mutex_t   *mutex,
             const pthread_mutexattr_t   *attr);

61.2  –  Arguments

 mutex

    Mutex to be initialized.

 attr

    Mutex attributes object that defines the characteristics of the
    mutex to be initialized.

61.3  –  Description

    This routine initializes a mutex with the attributes specified
    by the mutex attributes object specified in the attr argument. A
    mutex is a synchronization object that allows multiple threads to
    serialize their access to shared data.

    The mutex is initialized and set to the unlocked state. If attr
    is set to NULL, the default mutex attributes are used. The
    pthread_mutexattr_settype() routine can be used to specify the
    type of mutex that is created (normal, recursive, or errorcheck).

    Use the PTHREAD_MUTEX_INITIALIZER macro to statically initialize
    a mutex without calling this routine. Statically initialized
    mutexes need not be destroyed using pthread_mutex_destroy(). Use
    this macro as follows:

       pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER

    Only normal mutexes can be statically initialized.

    A mutex is a resource of the process, not part of any particular
    thread. A mutex is neither destroyed nor unlocked automatically
    when any thread exits. If a mutex is allocated on a stack, static
    initializers cannot be used on the mutex.

61.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error, the mutex is not initialized,
    and the contents of mutex are undefined. Possible return values
    are as follows:

    Return      Description

    0           Successful completion.
    [EAGAIN]    The system lacks the necessary resources to
                initialize the mutex.
    [EBUSY]     The implementation has detected an attempt to
                reinitialize the mutex (a previously initialized,
                but not yet destroyed mutex).
    [EINVAL]    The value specified by mutex is not a valid mutex.
    [ENOMEM]    Insufficient memory exists to initialize the mutex.
    [EPERM]     The caller does not have privileges to perform this
                operation.

61.5  –  Associated Routines

       pthread_mutexattr_init()
       pthread_mutexattr_gettype()
       pthread_mutexattr_settype()
       pthread_mutex_lock()
       pthread_mutex_trylock()
       pthread_mutex_unlock()

62  –  pthread_mutex_lock

    Locks an unlocked mutex.

62.1  –  C Binding

    #include <pthread.h>

    int
    pthread_mutex_lock (
             pthread_mutex_t   *mutex);

62.2  –  Arguments

 mutex

    Mutex to be locked.

62.3  –  Description

    This routine locks a mutex with behavior that depends upon the
    type of mutex, as follows:

    o  If a normal or default mutex is specified, a deadlock can
       result if the current owner of the mutex calls this routine in
       an attempt to lock the mutex a second time. (The deadlock is
       not detected or reported.)

    o  If a recursive mutex is specified, the current owner of the
       mutex can relock the same mutex without blocking. The lock
       count is incremented for each recursive lock within the
       thread.

    o  If an errorcheck mutex is specified and the current owner
       tries to lock the mutex a second time, this routine reports
       the [EDEADLK] error. If the mutex is locked by another thread,
       the calling thread waits for the mutex to become available.

    Use the pthread_mutexattr_settype() routine to set the type of
    the mutex to normal, default, recursive, or errorcheck.

    The thread that has locked a mutex becomes its current owner and
    remains its owner until the same thread has unlocked it. This
    routine returns with the mutex in the locked state and with the
    calling thread as the mutex's current owner.

    A recursive or errorcheck mutex records the identity of the
    thread that locks it, allowing debuggers to display this
    information. In most cases, normal and default mutexes do not
    record the owning thread's identity.

62.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EDEADLK]   A deadlock condition is detected.
    [EINVAL]    The value specified by mutex is not a valid mutex.

62.5  –  Associated Routines

       pthread_mutexattr_settype()
       pthread_mutex_destroy()
       pthread_mutex_init()
       pthread_mutex_trylock()
       pthread_mutex_unlock()

63  –  pthread_mutex_setname_np

    Changes the object name in a mutex object.

63.1  –  C Binding

    #include <pthread.h>

    int
    pthread_mutex_setname_np (
             pthread_mutex_t   *mutex,
             const char   *name,
             void   *mbz);

63.2  –  Arguments

 mutex

    Address of the mutex object whose object name is to be changed.

 name

    Object name value to copy into the mutex object.

 mbz

    Reserved for future use. The value must be zero (0).

63.3  –  Description

    This routine changes the object name in the mutex object
    specified by the mutex argument to the value specified by the
    name argument. To set a new mutex object's object name, call this
    routine immediately after initializing the mutex object.

    The object name is a C language string and provides an identifier
    that is meaningful to a person debugging a multithreaded
    application. The maximum number of characters in the object name
    is 31.

63.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by mutex is not a valid mutex, or
                the length in characters of name exceeds 31.
    [ENOMEM]    Insufficient memory to create a copy of the object
                name string.

63.5  –  Associated Routines

       pthread_mutex_getname_np()

64  –  pthread_mutex_trylock

    Attempts to lock the specified mutex. If the mutex is already
    locked, the calling thread does not wait for the mutex to become
    available.

64.1  –  C Binding

    #include <pthread.h>

    int
    pthread_mutex_trylock (
             pthread_mutex_t   *mutex);

64.2  –  Arguments

 mutex

    Mutex to be locked.

64.3  –  Description

    This routine attempts to lock the mutex specified in the mutex
    argument. When a thread calls this routine, an attempt is made to
    immediately lock the mutex. If the mutex is successfully locked,
    this routine returns zero (0) and the calling thread becomes the
    mutex's current owner. If the specified mutex is locked when a
    thread calls this routine, the calling thread does not wait for
    the mutex to become available.

    The behavior of this routine is as follows:

    o  For a normal, default, or errorcheck mutex: if the mutex
       is locked by any thread (including the calling thread) when
       this routine is called, this routine returns [EBUSY] and the
       calling thread does not wait to acquire the lock.

    o  For a normal or errorcheck mutex: if the mutex is not owned,
       this routine returns zero (0) and the mutex becomes locked by
       the calling thread.

    o  For a recursive mutex: if the mutex is owned by the current
       thread, this routine returns zero (0) and the mutex lock count
       is incremented. (To unlock a recursive mutex, each call to
       pthread_mutex_trylock() must be matched by a call to pthread_
       mutex_unlock().)

    Use the pthread_mutexattr_settype() routine to set the mutex type
    attribute (normal, default, recursive, or errorcheck).

64.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EBUSY]     The mutex is already locked; therefore, it was not
                acquired.
    [EINVAL]    The value specified by mutex is not a valid mutex.

64.5  –  Associated Routines

       pthread_mutexattr_settype()
       pthread_mutex_destroy()
       pthread_mutex_init()
       pthread_mutex_lock()
       pthread_mutex_unlock()

65  –  pthread_mutex_unlock

    Unlocks the specified mutex.

65.1  –  C Binding

    #include <pthread.h>

    int
    pthread_mutex_unlock (
             pthread_mutex_t   *mutex);

65.2  –  Arguments

 mutex

    Mutex to be unlocked.

65.3  –  Description

    This routine unlocks the mutex specified by the mutex argument.

    This routine behaves as follows, based on the type of the
    specified mutex:

    o  For a normal, default, or errorcheck mutex: if the mutex is
       owned by the calling thread, it is unlocked with no current
       owner. Further, for a normal or default mutex: if the mutex
       is not locked or is locked by another thread, this routine
       can also return [EPERM], but this is not guaranteed. For an
       errorcheck mutex: if the mutex is not locked or is locked by
       another thread, this routine returns [EPERM].

    o  For a recursive mutex: if the mutex is owned by the calling
       thread, the lock count is decremented. The mutex remains
       locked and owned until the lock count reaches zero (0). When
       the lock count reaches zero, the mutex becomes unlocked with
       no current owner.

    If one or more threads are waiting to lock the specified mutex,
    and the mutex becomes unlocked, this routine causes one thread
    to unblock and to try to acquire the mutex. The scheduling policy
    is used to determine which thread to unblock. For the SCHED_FIFO
    and SCHED_RR policies, a blocked thread is chosen in priority
    order, using first-in/first-out within priorities. Note that the
    mutex might not be acquired by the awakened thread, if any other
    running thread attempts to lock the mutex first.

    On Tru64 UNIX, if a signal is delivered to a thread waiting for
    a mutex, upon return from the signal handler, the thread resumes
    waiting for the mutex as if it was not interrupted.

65.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified for mutex is not a valid mutex.
    [EPERM]     The calling thread does not own the mutex.

65.5  –  Associated Routines

       pthread_mutexattr_settype()
       pthread_mutex_destroy()
       pthread_mutex_init()
       pthread_mutex_lock()
       pthread_mutex_trylock()

66  –  pthread_mutexattr_destroy

    Destroys the specified mutex attributes object.

66.1  –  C Binding

    #include <pthread.h>

    int
    pthread_mutexattr_destroy (
             pthread_mutexattr_t   *attr);

66.2  –  Arguments

 attr

    Mutex attributes object to be destroyed.

66.3  –  Description

    This routine destroys a mutex attributes object-that is, the
    object becomes uninitialized. Call this routine when your program
    no longer needs the specified mutex attributes object.

    After this routine is called, the Threads Library may reclaim
    the storage used by the mutex attributes object. Mutexes that
    were created using this attributes object are not affected by the
    destruction of the mutex attributes object.

    The results of calling this routine are unpredictable, if the
    attributes object specified in the attr argument does not exist.

66.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by attr is not a valid attributes
                object.

66.5  –  Associated Routines

       pthread_mutexattr_init()

67  –  pthread_mutexattr_gettype

    Obtains the mutex type attribute in the specified mutex attribute
    object.

67.1  –  C Binding

    #include <pthread.h>

    int
    pthread_mutexattr_gettype (
                const pthread_mutexattr_t   *attr,
                int   *type);

67.2  –  Arguments

 attr

    Mutex attributes object whose mutex type attribute is obtained.

 type

    Receives the value of the mutex type attribute. The type argument
    specifies the type of mutex that can be created. Valid values
    are:

       PTHREAD_MUTEX_NORMAL
       PTHREAD_MUTEX_DEFAULT (default)
       PTHREAD_MUTEX_RECURSIVE
       PTHREAD_MUTEX_ERRORCHECK

67.3  –  Description

    This routine obtains the value of the mutex type attribute in
    the mutex attributes object specified by the attr argument and
    stores it in the location specified by the type argument. See the
    pthread_mutexattr_settype() description for information about
    mutex types.

67.4  –  Return Values

    On successful completion, this routine returns the mutex type in
    the location specified by the type argument.

    If an error condition occurs, this routine returns an integer
    value indicating the type of the error. Possible return values
    are as follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by attr is not a valid mutex
                attributes object.

67.5  –  Associated Routines

       pthread_mutexattr_init()
       pthread_mutexattr_settype()
       pthread_mutex_init()

68  –  pthread_mutexattr_init

    Initializes a mutex attributes object.

68.1  –  C Binding

    #include <pthread.h>

    int
    pthread_mutexattr_init (
             pthread_mutexattr_t   *attr);

68.2  –  Arguments

 attr

    Address of the mutex attributes object to be initialized.

68.3  –  Description

    This routine initializes the mutex attributes object specified
    by the attr argument with a set of default values. A mutex
    attributes object is used to specify the attributes of one or
    more mutexes when they are created. The attributes object created
    by this routine is used only in calls to the pthread_mutex_init()
    routine.

    When a mutex attributes object is used to create a mutex, the
    values of the individual attributes determine the characteristics
    of the new mutex. Thus, attributes objects act as additional
    arguments to mutex creation. Changing individual attributes
    in an attributes object does not affect any mutexes that were
    previously created using that attributes object.

    You can use the same mutex attributes object in successive calls
    to pthread_mutex_init(), from any thread. If multiple threads
    can change attributes in a shared mutex attributes object,
    your program must use a mutex to protect the integrity of the
    attributes object's contents.

    Results are undefined if this routine is called and the attr
    argument specifies a mutex attributes object that is already
    initialized.

68.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [ENOMEM]    Insufficient memory to create the mutex attributes
                object.

68.5  –  Associated Routines

       pthread_mutexattr_destroy()
       pthread_mutexattr_gettype()
       pthread_mutexattr_settype()
       pthread_mutex_init()

69  –  pthread_mutexattr_settype

    Specifies the mutex type attribute that is used when a mutex is
    created.

69.1  –  C Binding

    #include <pthread.h>

    int
    pthread_mutexattr_settype (
             pthread_mutexattr_t   *attr,
             int   type);

69.2  –  Arguments

 attr

    Mutex attributes object whose mutex type attribute is to be
    modified.

 type

    New value for the mutex type attribute. The type argument
    specifies the type of mutex that will be created. Valid values
    are:

       PTHREAD_MUTEX_NORMAL
       PTHREAD_MUTEX_DEFAULT (default)
       PTHREAD_MUTEX_RECURSIVE
       PTHREAD_MUTEX_ERRORCHECK

69.3  –  Description

    This routine sets the mutex type attribute that is used to
    determine which type of mutex is created based on a subsequent
    call to pthread_mutex_init().

69.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by attr or type is not a valid
                mutex attributes type.
    [ESRCH]     The value specified by attr does not refer to an
                existing mutex attributes object.

69.5  –  Associated Routines

       pthread_mutexattr_init()
       pthread_mutexattr_gettype()
       pthread_mutex_init()

70  –  pthread_once

    Calls a routine that is executed by a single thread, once.

70.1  –  C Binding

    #include <pthread.h>

    int
    pthread_once (
             pthread_once_t   *once_control,
             void   (*routine) (void));

70.2  –  Arguments

 once_control

    Address of a record that controls the one-time execution code.
    Each one-time execution routine must have its own unique pthread_
    once_t record.

 routine

    Address of a procedure to be executed once. This routine is
    called only once, regardless of the number of times it and its
    associated once_control block are passed to pthread_once().

70.3  –  Description

    The first call to this routine by any thread in a process with
    a given once_control will call the specified routine with no
    arguments. Subsequent calls to pthread_once() with the same once_
    control will not call the routine. On return from pthread_once(),
    it is guaranteed that the routine has completed.

    For example, a mutex or a per-thread context key must be
    created exactly once. Calling pthread_once() ensures that the
    initialization is serialized across multiple threads. Other
    threads that reach the same point in the code would be delayed
    until the first thread is finished.

                                   NOTE

       If you specify a routine that directly or indirectly results
       in a recursive call to pthread_once() and that specifies the
       same routine argument, the recursive call can result in a
       deadlock.

    To initialize the once_control record, your program can zero out
    the entire structure, or you can use the PTHREAD_ONCE_INIT macro,
    which is defined in the pthread.h header file, to statically
    initialize that structure. If using PTHREAD_ONCE_INIT, declare
    the once_control record as follows:

    pthread_once_t  once_control = PTHREAD_ONCE_INIT;

    Note that it is often easier to simply lock a statically
    initialized mutex, check a control flag, and perform necessary
    initialization (in-line) rather than using pthread_once(). For
    example, you can code an initialization routine that begins with
    the following basic logic:

      init()
      {
       static pthread_mutex_t    mutex = PTHREAD_MUTEX_INITIALIZER;
       static int                flag = FALSE;

       pthread_mutex_lock(&mutex);
       if(!flag)
         {
          /* initialization code goes here */
          flag = TRUE;
         }
       pthread_mutex_unlock(&mutex);
      }

70.4  –  Return Values

    If an error occurs, this routine returns an integer indicating
    the type of error. Possible return values are as follows:

    Return      Description

    0           Successful completion
    [EINVAL]    Invalid argument

71  –  pthread_rwlock_destroy

    Destroys a read-write lock object.

71.1  –  C Binding

    #include <pthread.h>

    int
    pthread_rwlock_destroy (
             pthread_rwlock_t   *rwlock);

71.2  –  Arguments

 rwlock

    Address of the read-write lock object to be destroyed.

71.3  –  Description

    This routine destroys the specified read-write lock object by
    uninitializing it, and should be called when the object is no
    longer referenced in your program. After this routine is called,
    the Threads Library may reclaim internal storage used by the
    specified read-write lock object. The effect of subsequent use of
    the lock is undefined until the lock is reinitialized by another
    call to pthread_rwlock_init().

    It is illegal to destroy a locked read-write lock.

    The results of this routine are unpredictable if the specified
    read-write lock object does not currently exist or is not
    initialized. This routine destroys the read-write lock object
    specified by the rwlock argument and releases any resources that
    the object used.

    A destroyed read-write lock object can be reinitialized using the
    pthread_rwlock_init() routine. The results of otherwise
    referencing a destroyed read-write lock object are undefined.

71.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EBUSY]     An attempt was made to destroy the object referenced
                by rwlock while it is locked or referenced.

71.5  –  Associated Routines

       pthread_rwlock_init()

72  –  pthread_rwlock_getname_np

    Obtains the object name from a read-write lock object.

72.1  –  C Binding

    #include <pthread.h>

    int
    pthread_rwlock_getname_np (
             pthread_rwlock_t   *rwlock,
             char   *name,
             size_t   len);

72.2  –  Arguments

 rwlock

    Address of the read-write lock object whose object name is to be
    obtained.

 name

    Location to store the obtained object name.

 len

    Length in bytes of buffer at the location specified by name.

72.3  –  Description

    This routine copies the object name from the read-write lock
    object specified by rwlock to the buffer at the location name.
    Before calling this routine, your program must allocate the
    buffer indicated by name.

    The object name is a C language string and provides an identifier
    that is meaningful to a person debugging a multithreaded
    application. The maximum number of characters in the object name
    is 31.

    If the specified read-write lock object has not been previously
    set with an object name, this routine copies a C language null
    string into the buffer at location name.

72.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by rwlock is not a valid read-
                write lock.

72.5  –  Associated Routines

       pthread_rwlock_setname_np()

73  –  pthread_rwlock_init

    Initializes a read-write lock object.

73.1  –  C Binding

    #include <pthread.h>

    int
    pthread_rwlock_init (
             pthread_rwlock_t   *rwlock,
             const pthread_rwlockattr_t   *attr);

73.2  –  Arguments

 rwlock

    Read-write lock object to be initialized.

 attr

    Read-write lock attributes object that defines the
    characteristics of the read-write lock to be initialized.

73.3  –  Description

    This routine initializes a read-write lock object with the
    attributes specified by the read-write lock attributes object
    specified in attr. A read-write lock is a synchronization object
    that serializes access to shared information that needs to be
    read frequently and written only occasionally. A thread can
    acquire a read-write lock for shared read access or for exclusive
    write access.

    Upon successful completion of this routine, the read-write lock
    is initialized and set to the unlocked state. If attr is set to
    NULL, the default read-write lock attributes are used; the effect
    is the same as passing the address of a default read-write lock
    attributes object. Once initialized, the lock can be used any
    number of times without being reinitialized.

    Results of calling this routine are undefined if attr specifies
    an already initialized read-write lock or if rwlock is used
    without first being initialized.

    If this routine returns unsuccessfully, rwlock is not initialized
    and the contents of rwlock are undefined.

    A read-write lock is a resource of the process, not part of any
    particular thread. A read-write lock is neither destroyed not
    unlocked automatically when any thread exits. Because read-write
    locks are shared, they may be allocated in heap or static memory,
    but not on a stack.

    In cases where default read-write lock attributes are
    appropriate, you may use the PTHREAD_RWLOCK_INITIALIZER macro
    to statically initialize the lock object without calling this
    routine. The effect is equivalent to dynamic initialization by
    a call to pthread_rwlock_init() with attr specified as NULL,
    except that no error checks are performed. Statically initialized
    read-write locks need not be destroyed using pthread_rwlock_
    destroy().

    Use the PTHREAD_RWLOCK_INITIALIZER macro as follows:

    pthread_rwlock_t rwlock= PTHREAD_RWLOCK_INITIALIZER;

73.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EAGAIN]    The system lacks the necessary resources to
                initialize the read-write lock.
    [EBUSY]     The Threads Library has detected an attempt to
                reinitialize the read-write lock (a previously
                initialized, but not yet destroyed, read-write lock
                object).
    [EINVAL]    The value specified by attr is not a valid attributes
                block.
    [ENOMEM]    Insufficient memory exists to initialize the read-
                write lock.
    [EPERM]     The caller does not have privileges to perform this
                operation.

73.5  –  Associated Routines

       pthread_rwlock_destroy()

74  –  pthread_rwlock_rdlock

    Acquires a read-write lock object for read access.

74.1  –  C Binding

    #include <pthread.h>

    int
    pthread_rwlock_rdlock (
             pthread_rwlock_t   *rwlock);

74.2  –  Arguments

 rwlock

    Address of the read-write lock object to acquire for read access.

74.3  –  Description

    This routine acquires a read-write lock for read access. If no
    thread already holds the lock for write access and there are no
    writers waiting to acquire the lock, the lock for read access
    is granted to the calling thread and this routine returns. If
    a thread already holds the lock for read access, the lock is
    granted and this routine returns.

    A thread can hold multiple, concurrent locks for read access on
    the same read-write lock. In a given thread, for each call to
    this routine that successfully acquires the same read-write lock
    for read access, a corresponding call to pthread_rwlock_unlock
    must be issued.

    If some thread already holds the lock for write access, the
    calling thread will not acquire the read lock. If the read lock
    is not acquired, the calling thread blocks until it can acquire
    the lock for read access. Results are undefined if the calling
    thread has already acquired a lock for write access on rwlock
    when this routine is called.

    If the read-write lock object referenced by rwlock is not
    initialized, the results of calling this routine are undefined.

    If a thread is interrupted (via a Tru64 UNIX signal or an OpenVMS
    AST) while waiting for a read-write lock for read access, upon
    return from the interrupt routine the thread resumes waiting for
    the lock as if it had not been interrupted.

74.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion; the read-write lock object was
                acquired for read access.
    [EINVAL]    The value specified by rwlock does not refer to an
                initialized read-write lock object.
    [EDEADLCK]  The calling thread already owns the specified read-
                write lock object for write access.
    [EAGAIN]    The lock for read access could not be acquired
                because the maximum number of read lock acquisitions
                for rwlock has been exceeded.

74.5  –  Associated Routines

       pthread_rwlock_init()
       pthread_rwlockattr_init()
       pthread_rwlock_tryrdlock()
       pthread_rwlock_wrlock()
       pthread_rwlock_unlock()

75  –  pthread_rwlock_setname_np

    Changes the object name in a read-write lock object.

75.1  –  C Binding

    #include <pthread.h>

    int
    pthread_rwlock_setname_np (
             pthread_rwlock_t   *rwlock,
             const char   *name,
             void   *mbz);

75.2  –  Arguments

 rwlock

    Address of the read-write lock object whose object name is to be
    changed.

 name

    Object name value to copy into the read-write lock object.

 mbz

    Reserved for future use. The value must be zero (0).

75.3  –  Description

    This routine changes the object name in the read-write lock
    object specified by rwlock to the value specified by name. To
    set a new read-write lock object's object name, call this routine
    immediately after initializing the read-write lock object.

    The object name is a C language string and provides an identifier
    that is meaningful to a person debugging a multithreaded
    application. The maximum number of characters in the object name
    is 31.

75.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion, the read-write lock object was
                acquired for read access.
    [EINVAL]    The value specified by rwlock is invalid, or the
                length in characters of name exceeds 31.
    [ENOMEM]    Insufficient memory to create a copy of the object
                name string.

75.5  –  Associated Routines

       pthread_rwlock_getname_np()
       pthread_rwlock_init()

76  –  pthread_rwlock_tryrdlock

    Attempts to acquire a read-write lock object for read access
    without waiting.

76.1  –  C Binding

    #include <pthread.h>

    int
    pthread_rwlock_tryrdlock (
             pthread_rwlock_t    *rwlock);

76.2  –  Arguments

 rwlock

    Address of the read-write lock object to acquire for read access.

76.3  –  Description

    This routine attempts to acquire a read-write lock for read
    access, but does not wait for the lock if it not immediately
    available.

    If no thread already holds the lock for write access and there
    are no writers waiting to acquire the lock, the lock for read
    access is granted to the calling thread and this routine returns.
    If a thread already holds the lock for read access, the lock is
    granted and this routine returns.

    If some thread already holds the lock for write access, the
    calling thread will not acquire the read lock. Results are
    undefined if the calling thread has already acquired a lock for
    write access on rwlock when this routine is called.

    A thread can hold multiple, concurrent locks for read access on
    the same read-write lock. In a given thread, for each call to
    this routine that successfully acquires the same read-write lock
    for read access, a corresponding call to pthread_rwlock_unlock()
    must be issued.

    If the read-write lock object referenced by rwlock is not
    initialized, the results of calling this routine are undefined.

76.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion; the read-write lock object was
                acquired for read access.
    [EAGAIN]    The lock for read access could not be acquired
                because the maximum number of read lock acquisitions
                for rwlock has been exceeded.
    [EBUSY]     The read-write lock could not be acquired for read
                access because another thread already acquired it
                for write access or is blocked and waiting for it for
                write access.
    [EDEADLCK]  The current thread already owns the read-write lock
                for writing.
    [EINVAL]    The value specified by rwlock does not refer to an
                initialized read-write lock object.

76.5  –  Associated Routines

       pthread_rwlockattr_init()
       pthread_rwlock_init()
       pthread_rwlock_rdlock()
       pthread_rwlock_unlock()
       pthread_rwlock_wrlock()

77  –  pthread_rwlock_trywrlock

    Attempts to acquire a read-write lock object for write access
    without waiting.

77.1  –  C Binding

    #include <pthread.h>

    int
    pthread_rwlock_trywrlock (
             pthread_rwlock_t   *rwlock);

77.2  –  Arguments

 rwlock

    Address of the read-write lock object to acquire for write
    access.

77.3  –  Description

    This routine attempts to acquire the read-write lock referenced
    by rwlock for write access. If any thread already holds that lock
    for write access or read access, this routine fails and returns
    [EBUSY] and the calling thread does not wait for the lock to
    become available.

    Results are undefined if the calling thread holds the read-write
    lock (whether for read or write access) at the time this routine
    is called.

    If the read-write lock object referenced by rwlock is not
    initialized, the results of calling this routine are undefined.

    Realtime applications can encounter priority inversion when using
    read-write locks. The problem occurs when a high-priority thread
    acquires a read-write lock that is about to be unlocked (that
    is, posted) by a low-priority thread, but the low-priority thread
    is preempted by a medium-priority thread. This scenario leads to
    priority inversion in that a high-priority thread is blocked by
    lower-priority threads for an unlimited period of time. During
    system design, realtime programmers must take into account the
    possibility of priority inversion and can deal with it in a
    number of ways, such as by having critical sections that are
    guarded by read-write locks execute at a high priority, so that
    a thread cannot be preempted while executing in its critical
    section.

77.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion, the read-write lock object was
                acquired for write access.
    [EBUSY]     The read-write lock could not be acquired for write
                access because it was already locked for write access
                or for read access.
    [EDEADLCK]  The current thread already owns the read-write lock
                for write or read access.
    [EINVAL]    The value specified by rwlock does not refer to an
                initialized read-write lock object.

77.5  –  Associated Routines

       pthread_rwlockattr_init()
       pthread_rwlock_init()
       pthread_rwlock_rdlock()
       pthread_rwlock_unlock()
       pthread_rwlock_wrlock()

78  –  pthread_rwlock_unlock

    Unlocks a read-write lock object.

78.1  –  C Binding

    #include <pthread.h>

    int
    pthread_rwlock_unlock (
             pthread_rwlock_t   *rwlock);

78.2  –  Arguments

 rwlock

    Address of the read-write lock object to be unlocked.

78.3  –  Description

    This routine releases a lock acquisition held on the read-write
    lock object referenced by rwlock. Results are undefined if rwlock
    is not held by the calling thread.

    If this routine is called to release a lock for read access on
    rwlock and the calling thread also currently holds other locks
    for read access on rwlock, the read-write lock object remains
    in the read locked state. If this routine releases the calling
    thread's last lock for read access on rwlock, the calling thread
    is no longer one of the owners of the lock object.

    If this routine is called to release a lock for write access
    on rwlock, the lock object is put in the unlocked state with no
    owners.

    If a call to this routine results in the read-write lock object
    becoming unlocked and there are multiple threads waiting to
    acquire that lock for write access, the Threads Library uses
    the scheduling policy of those waiting threads to determine
    which thread next acquires the lock object for write access. If
    there are multiple threads waiting to acquire the read-write lock
    object for read access, the Threads Library uses the scheduling
    policy of those waiting threads to determine the order in which
    those threads acquire the lock for read access. If there are
    multiple threads waiting to acquire the read-write lock object
    for both read and write access, it is unspecified whether a
    thread waiting for read access or for write access next acquires
    the lock object.

    If the read-write lock object referenced by rwlock is not
    initialized, the results of calling this routine are undefined.

78.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The values specified by rwlock does not refer to an
                initialized read-write lock object.
    [EPERM]     The calling thread does not hold the read-write lock
                object.

78.5  –  Associated Routines

       pthread_rwlockattr_init()
       pthread_rwlock_init()
       pthread_rwlock_rdlock()
       pthread_rwlock_wrlock()

79  –  pthread_rwlock_wrlock

    Acquires a read-write lock for write access.

79.1  –  C Binding

    #include <pthread.h>

    int
    pthread_rwlock_wrlock (
             pthread_rwlock_t   *rwlock);

79.2  –  Arguments

 rwlock

    Address of the read-write lock object to acquire for write
    access.

79.3  –  Description

    This routine attempts to acquire a read-write lock for write
    access. If any thread already has acquired the lock for write
    access or read access, the lock is not granted and the calling
    thread blocks until it can acquire the lock. A thread can hold
    only one lock for write access on a read-write lock.

    Results are undefined if the calling thread holds the read-write
    lock (whether for read or write access) at the time this routine
    is called.

    If the read-write lock object referenced by rwlock is not
    initialized, the results of calling this routine are undefined.

    If a thread is interrupted (via a Tru64 UNIX signal or an OpenVMS
    AST) while waiting for a read-write lock for write access, upon
    return from the interrupt routine the thread resumes waiting for
    the lock as if it had not been interrupted.

    Realtime applications can encounter priority inversion when using
    read-write locks. The problem occurs when a high-priority thread
    acquires a read-write lock that is about to be unlocked (that
    is, posted) by a low-priority thread, but the low-priority thread
    is preempted by a medium-priority thread. This scenario leads to
    priority inversion in that a high-priority thread is blocked by
    lower-priority threads for an unlimited period of time. During
    system design, realtime programmers must take into account the
    possibility of priority inversion and can deal with it in a
    number of ways, such as by having critical sections that are
    guarded by read-write locks execute at a high priority, so that
    a thread cannot be preempted while executing in its critical
    section.

79.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion, the read-write lock object was
                acquired for write access.
    [EDEADLCK]  The calling thread already owns the read-write lock
                for write or read access.
    [EINVAL]    The value specified by rwlock does not refer to an
                initialized read-write lock object.

79.5  –  Associated Routines

       pthread_rwlockattr_init()
       pthread_rwlock_init()
       pthread_rwlock_rdlock()
       pthread_rwlock_trywrlock()
       pthread_rwlock_unlock()

80  –  pthread_rwlockattr_destroy

    Destroys a previously initialized read-write lock attributes
    object.

80.1  –  C Binding

    #include <pthread.h>

    int
    pthread_rwlockattr_destroy (
             pthread_rwlockattr_t   *attr);

80.2  –  Arguments

 attr

    Address of the read-write lock attributes object to be destroyed.

80.3  –  Description

    This routine destroys the read-write lock attributes object
    referenced by attr; that is, the object becomes uninitialized.

    After successful completion of this routine, the results of using
    attr in a call to any routine (other than pthread_rwlockattr_
    init()) are unpredictable.

80.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by attr is not a valid attributes
                block.

80.5  –  Associated Routines

       pthread_rwlockattr_init()
       pthread_rwlock_init()

81  –  pthread_rwlockattr_init

    Initializes a read-write lock attributes object.

81.1  –  C Binding

    #include <pthread.h>

    int
    pthread_rwlockattr_init (
             pthread_rwlockattr_t   *attr);

81.2  –  Arguments

 attr

    Address of the read-write lock attributes object to be
    initialized.

81.3  –  Description

    This routine initializes the read-write lock attributes object
    referenced by attr and sets its attributes with default values.

    The results of calling this routine are undefined if attr
    references an already initialized read-write lock attributes
    object.

    After an initialized read-write lock attributes object has been
    used to initialize one or more read-write lock objects, any
    operation on that attributes object (including destruction) has
    no effect on those read-write lock objects.

81.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion
    [ENOMEM]    Insufficient memory to initialize the read-write lock
                attributes object

81.5  –  Associated Routines

       pthread_rwlockattr_destroy()
       pthread_rwlock_init()

82  –  pthread_self

    Obtains the identifier of the calling thread.

82.1  –  C Binding

    #include <pthread.h>

    pthread_t
    pthread_self (void);

82.2  –  Arguments

    None

82.3  –  Description

    This routine returns the address of the calling thread's own
    thread identifier. For example, you can use this thread object
    to obtain the calling thread's own sequence number. To do so,
    pass the return value from this routine in a call to the pthread_
    getsequence_np() routine, as follows:

       .
       .
       .
       unsigned long     this_thread_nbr;
       .
       .
       .
       this_thread_nbr = pthread_getsequence_np( pthread_self( ) );
       .
       .
       .

    The return value from the pthread_self() routine becomes
    meaningless after the calling thread is destroyed.

82.4  –  Return Values

    Returns the address of the calling thread's own thread object.

82.5  –  Associated Routines

       pthread_cancel()
       pthread_create()
       pthread_detach()
       pthread_exit()
       pthread_getsequence_np()
       pthread_join()
       pthread_kill()
       pthread_sigmask()

83  –  pthread_setcancelstate

    Sets the calling thread's cancelability state.

83.1  –  C Binding

    #include <pthread.h>

    int
    pthread_setcancelstate (
             int   state,
             int   *oldstate );

83.2  –  Arguments

 state

    State of general cancelability to set for the calling thread. The
    following are valid cancel state values:

       PTHREAD_CANCEL_ENABLE
       PTHREAD_CANCEL_DISABLE

 oldstate

    Previous cancelability state for the calling thread.

83.3  –  Description

    This routine sets the calling thread's cancelability state and
    returns the calling thread's previous cancelability state in
    oldstate.

    When cancelability state is set to PTHREAD_CANCEL_DISABLE, a
    cancelation request cannot be delivered to the thread, even if a
    cancelable routine is called or asynchronous cancelability type
    is enabled.

    When a thread is created, its default cancelability state is
    PTHREAD_CANCEL_ENABLE.
    Possible Problems When Disabling Cancelability
    The most important use of thread cancelation is to ensure
    that indefinite wait operations are terminated. For example, a
    thread that waits on some network connection, which can possibly
    take days to respond (or might never respond), should be made
    cancelable.

    When a thread's cancelability is disabled, no routine in that
    thread is cancelable. As a result, the user is unable to
    cancel the operation performed by that thread. When disabling
    cancelability, be sure that no long waits can occur or that it is
    necessary for other reasons to defer cancelation requests around
    that particular region of code.

83.4  –  Return Values

    On successful completion, this routine returns the calling
    thread's previous cancelability state in the location specified
    by the oldstate argument.

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The specified state is not PTHREAD_CANCEL_ENABLE or
                PTHREAD_CANCEL_DISABLE.

83.5  –  Associated Routines

       pthread_cancel()
       pthread_setcanceltype()
       pthread_testcancel()

84  –  pthread_setcanceltype

    Sets the calling thread's cancelability type.

84.1  –  C Binding

    #include <pthread.h>

    int
    pthread_setcanceltype (
                int   type,
                int   *oldtype);

84.2  –  Arguments

 type

    The cancelability type to set for the calling thread. The
    following are valid values:

       PTHREAD_CANCEL_DEFERRED
       PTHREAD_CANCEL_ASYNCHRONOUS

 oldtype

    Returns the previous cancelability type.

84.3  –  Description

    This routine sets the cancelability type and returns the previous
    type in location oldtype.

    When a thread's cancelability state is set to PTHREAD_CANCEL_
    DISABLE, (see pthread_setcancelstate()), a cancelation request
    cannot be delivered to that thread, even if a cancelable routine
    is called or asynchronous cancelability type is enabled.

    When the cancelability state is set to PTHREAD_CANCEL_ENABLE,
    cancelability depends on the thread's cancelability type, as
    follows:

    o  If the thread's cancelability type is PTHREAD_CANCEL_DEFERRED,
       the thread can only receive a cancelation request at a
       cancelation point (including condition waits, thread joins,
       and calls to pthread_testcancel()).

    o  If the thread's cancelability type is PTHREAD_CANCEL_
       ASYNCHRONOUS, the thread can be canceled at any point in its
       execution.

    When a thread is created, the default cancelability type is
    PTHREAD_CANCEL_DEFERRED.

                                 CAUTION

       If the asynchronous cancelability type is set, do not call
       any routine unless it is explicitly documented as "safe for
       asynchronous cancelation." Note that none of the general
       run-time libraries and none of the POSIX Threads libraries
       are safe for asynchronous cancelation except for pthread_
       setcanceltype() and pthread_setcancelstate().

       Use asynchronous cancelability only when you have a compute-
       bound section of code that carries no state and makes no
       routine calls.

84.4  –  Return Values

    On successful completion, this routine returns the previous
    cancelability type in oldtype.

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The specified type is not PTHREAD_CANCEL_DEFERRED or
                PTHREAD_CANCEL_AYNCHRONOUS.

84.5  –  Associated Routines

       pthread_cancel()
       pthread_setcancelstate()
       pthread_testcancel()

85  –  pthread_setconcurrency

    Changes the value of the concurrency level global variable for
    this process.

85.1  –  C Binding

    #include <pthread.h>

    int
    pthread_setconcurrency (
                int   level);

85.2  –  Arguments

 level

    New value for the concurrency level for this process.

85.3  –  Description

    This routine stores the value specified in the level argument in
    the "concurrency level" global setting for the calling thread's
    process. Because the Threads Library automatically manages the
    concurrency of all threads in a multithreaded process, it ignores
    this concurrency level value.

    "Concurrency level" is a parameter used to coerce "simple" 2-
    level schedulers into allowing application concurrency. The
    Threads Library supplies the maximum concurrency at all times,
    automatically. It has no need for coercion, and calls pthread_
    setconcurrency() merely to determine the value returned by the
    next call to pthread_getconcurrency().

    The concurrency level value has no effect on the behavior of a
    multithreaded program that uses the Threads Library. This routine
    is provided for Single UNIX Specification, Version 2 source code
    compatibility and has no other effect when called.

    After calling this routine, subsequent calls to the pthread_
    getconcurrency() routine return the same value, until another
    call to pthread_setconcurrency() changes that value.

    The initial concurrency level is zero (0), indicating that the
    Threads Library manages the concurrency level. To indicate in a
    portable manner that the implementation is to resume control of
    concurrency level, call this routine with a level argument of
    zero (0).

    The concurrency level value can be obtained using the pthread_
    getconcurrency() routine.

85.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EAGAIN]    The value specified by new_level would cause a system
                resource to be exceeded.
    [EINVAL]    The value specified by new_level is negative.

85.5  –  Associated Routines

       pthread_getconcurrency()

86  –  pthread_setname_np

    Changes the object name in the thread object for an existing
    thread.

86.1  –  C Binding

    #include <pthread.h>

    int
    pthread_setname_np (
             pthread_thread_t   thread,
             const char   *name,
             void   *mbz);

86.2  –  Arguments

 thread

    Thread object whose object name is to be changed.

 name

    Object name value to copy into the thread object.

 mbz

    Reserved for future use. The value must be zero (0).

86.3  –  Description

    This routine changes the object name in the thread object for the
    thread specified by the thread argument to the value specified
    by the name argument. To set an existing thread's object name,
    call this routine after creating the thread. However, with this
    approach your program must account for the possibility that the
    target thread either has already exited or has been canceled
    before this routine is called.

    The object name is a C language string and provides an identifier
    that is meaningful to a person debugging a multithreaded
    application. The maximum number of characters in the object name
    is 31.

    This routine contrasts with pthread_attr_setname_np(), which
    changes the object name attribute in a thread attributes object
    that is used to create a new thread.

86.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The length in characters of name exceeds 31.
    [ENOMEM]    Insufficient memory to create a copy of the object
                name string.
    [ESRCH]     The thread specified by thread does not exist.

86.5  –  Associated Routines

       pthread_attr_getname_np()
       pthread_attr_setname_np()
       pthread_getname_np()

87  –  pthread_setschedparam

    Changes a thread's scheduling policy and scheduling parameters.

87.1  –  C Binding

    #include <pthread.h>

    int
    pthread_setschedparam (
             pthread_t   thread,
             int   policy,
             const struct sched_param   *param);

87.2  –  Arguments

 thread

    Thread whose scheduling policy and parameters are to be changed.

 policy

    New scheduling policy value for the thread specified in thread.
    The following are valid values:

       SCHED_BG_NP
       SCHED_FG_NP
       SCHED_FIFO
       SCHED_OTHER
       SCHED_RR

 param

    New values of the scheduling parameters associated with the
    scheduling policy for the thread specified in thread. Valid
    values for the sched_priority field of a sched_param structure
    depend on the chosen scheduling policy. Use the POSIX routines
    sched_get_priority_min() or sched_get_priority_max()  to
    determine the low and high limits of each policy.

    Additionally, the Threads Librray provides nonportable priority
    range constants, as follows:

    Low              High

    PRI_FIFO_MIN     PRI_FIFO_MAX
    PRI_RR_MIN       PRI_RR_MAX
    PRI_OTHER_MIN    PRI_OTHER_MAX
    PRI_FG_MIN_NP    PRI_FG_MAX_NP
    PRI_BG_MIN_NP    PRI_BG_MAX_NP

    The default priority varies by platform. On Tru64 UNIX, the
    default is 19 (that is, the POSIX priority of a normal timeshare
    process). On other platforms the default priority is the midpoint
    between PRI_FG_MIN_NP and PRI_FG_MAX_NP.

87.3  –  Description

    This routine changes both the current scheduling policy and
    associated scheduling parameters of the thread specified by
    thread to the policy and associated parameters provided in policy
    and param, respectively.

    All currently implemented scheduling policies have one scheduling
    parameter called sched_priority. For the policy you choose, you
    must specify an appropriate value in the sched_priority field of
    the sched_param structure.

    Changing the scheduling policy or priority, or both, of a thread
    can cause it either to start executing or to be preempted by
    another thread. A thread changes its own scheduling policy and
    priority by using the handle returned by the pthread_self()
    routine.

    This routine differs from pthread_attr_setschedpolicy() and
    pthread_attr_setschedparam(), in that those routines set the
    scheduling policy and parameter attributes that are used to
    establish the scheduling priority and scheduling policy of a
    new thread when it is created. However, this routine changes the
    scheduling policy and parameters of an existing thread.

87.4  –  Return Values

    If an error condition occurs, no scheduling policy or parameters
    are changed for the target thread, and this routine returns
    an integer value indicating the type of error. Possible return
    values are as follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value specified by policy or param is invalid.
    [ENOTSUP]   An attempt was made to set the scheduling policy or a
                parameter to an unsupported value.
    [EPERM]     The caller does not have the appropriate privileges
                to set the scheduling policy or parameters of the
                specified thread.
    [ESRCH]     The value specified by thread does not refer to an
                existing thread.

87.5  –  Associated Routines

       pthread_attr_setschedparam()
       pthread_attr_setschedpolicy()
       pthread_create()
       pthread_self()
       sched_yield()

88  –  pthread_setspecific

    Sets the thread-specific data value associated with the specified
    key for the calling thread.

88.1  –  C Binding

    #include <pthread.h>

    int
    pthread_setspecific (
             pthread_key_t   key,
             const void   *value);

88.2  –  Arguments

 key

    Thread-specific key that identifies the thread-specific data to
    receive value. This key value must be obtained from pthread_key_
    create().

 value

    New thread-specific data value to associate with the specified
    key for the calling thread.

88.3  –  Description

    This routine sets the thread-specific data value associated with
    the specified key for the current thread. If a value is defined
    for the key in this thread (the current value is not NULL),
    the new value is substituted for it. The key is obtained by a
    previous call to pthread_key_create().

    Different threads can bind different values to the same key.
    These values are typically pointers to blocks of dynamically
    allocated memory that are reserved for use by the calling thread.

    Do not call this routine from a thread-specific data destructor
    function.

    Note that although the type for value (void *) implies that it
    represents an address, the type is being used as a "universal
    scalar type." The Threads Library simply stores value for later
    retrieval.

88.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The specified key is invalid.
    [ENOMEM]    Insufficient memory to associate the value with the
                key.

88.5  –  Associated Routines

       pthread_getspecific()
       pthread_key_create()
       pthread_key_delete()

89  –  pthread_testcancel

    Requests delivery of a pending cancelation request to the calling
    thread.

89.1  –  C Binding

    #include <pthread.h>

    void
    pthread_testcancel (void);

89.2  –  Arguments

    None

89.3  –  Description

    This routine requests delivery of a pending cancelation request
    to the calling thread. Thus, calling this routine creates a
    cancelation point within the calling thread.

    The cancelation request is delivered only if a request is pending
    for the calling thread and the calling thread's cancelability
    state is enabled. (A thread disables delivery of cancelation
    requests to itself by calling pthread_setcancelstate().)

    When called within very long loops, this routine ensures that
    a pending cancelation request is noticed by the calling thread
    within a reasonable amount of time.

89.4  –  Return Values

    None

89.5  –  Associated Routines

       pthread_setcancelstate()

90  –  pthread_unlock_global_np

    Unlocks the Threads Library global mutex.

90.1  –  C Binding

    #include <pthread.h>

    int
    pthread_unlock_global_np (void);

90.2  –  Arguments

    None

90.3  –  Description

    This routine unlocks the Threads Library global mutex. Because
    the global mutex is recursive, the unlock occurs when each call
    to pthread_lock_global_np() has been matched by a call to this
    routine. For example, if you called pthread_lock_global_np()
    three times, pthread_unlock_global_np() unlocks the global mutex
    when you call it the third time.

    If no threads are waiting for the global mutex, it becomes
    unlocked with no current owner. If one or more threads are
    waiting to lock the global mutex, this routine causes one thread
    to unblock and to try to acquire the global mutex. The scheduling
    policy is used by this routine to determine which thread is
    awakened. For the policies SCHED_FIFO and SCHED_RR, a blocked
    thread is chosen in priority order, using first-in/first-out
    (FIFO) within priorities.

90.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EPERM]     The mutex is unlocked or owned by another thread.

90.5  –  Associated Routines

       pthread_lock_global_np()

91  –  pthread_yield_np

    Notifies the scheduler that the current thread is willing to
    release its processor to other threads of the same or higher
    priority.

    Syntax

      pthread_yield_np();

91.1  –  C Binding

    int
    pthread_yield_np (void);

91.2  –  Arguments

    None

91.3  –  Description

    This routine notifies the thread scheduler that the current
    thread is willing to release its processor to other threads of
    equivalent or greater scheduling precedence. (A thread generally
    will release its processor to a thread of a greater scheduling
    precedence without calling this routine.) If no other threads of
    equivalent or greater scheduling precedence are ready to execute,
    the thread continues.

    This routine can allow knowledge of the details of an application
    to be used to improve its performance. If a thread does not call
    pthread_yield_np(), other threads may be given the opportunity
    to run at arbitrary points (possibly even when the interrupted
    thread holds a required resource). By making strategic calls to
    pthread_yield_np(), other threads can be given the opportunity
    to run when the resources are free. This improves performance by
    reducing contention for the resource.

    As a general guideline, consider calling this routine after a
    thread has released a resource (such as a mutex) which is heavily
    contended for by other threads. This can be especially important
    either if the program is running on a uniprocessor machine, or
    if the thread acquires and releases the resource inside a tight
    loop.

    Use this routine carefully and sparingly, because misuse can
    cause unnecessary context switching which will increase overhead
    and actually degrade performance. For example, it is counter-
    productive for a thread to yield while it holds a resource that
    the threads to which it is yielding will need. Likewise, it is
    pointless to yield unless there is likely to be another thread
    that is ready to run.

                                   NOTE

       pthread_yield_np() is equivalent to sched_yield(). Use
       sched_yield() since it is part of the standard portable
       POSIX Threads Library.

91.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [ENOSYS]    The routine pthread_yield_np()  is not supported by
                this implementation.

91.5  –  Associated Routines

       pthread_attr_setschedparam()
       pthread_getschedparam()
       pthread_setschedparam()

92  –  sched_get_priority_max

    Returns the maximum priority for the specified scheduling policy.

    Syntax

      sched_get_priority_max(

                             policy);

      Argument       Data Type            Access

      policy         integer              read

92.1  –  C Binding

    #include <sched.h>

    int
    sched_get_priority_max (
                int   policy);

92.2  –  Arguments

 policy

    One of the scheduling policies, as defined in sched.h.

92.3  –  Description

    This routine returns the maximum priority for the scheduling
    policy specified in the policy argument. The argument value
    must be one of the scheduling policies (SCHED_FIFO, SCHED_RR,
    or SCHED_OTHER), as defined in the sched.h header file.

    No special privileges are required to use this routine.

92.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value of the policy argument does not represent a
                defined scheduling policy.

93  –  sched_get_priority_min

    Returns the minimum priority for the specified scheduling policy.

    Syntax

      sched_get_priority_min(

                             policy);

      Argument       Data Type            Access

      policy         integer              read

93.1  –  C Binding

    #include <sched.h>

    int
    sched_get_priority_min (
                int   policy);

93.2  –  Arguments

 policy

    One of the scheduling policies, as defined in sched.h.

93.3  –  Description

    This routine returns the minimum priority for the scheduling
    policy specified in the policy argument. The argument value
    must be one of the scheduling policies (SCHED_FIFO, SCHED_RR,
    or SCHED_OTHER), as defined in the sched.h header file.

    No special privileges are required to use this routine.

93.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The value of the policy argument does not represent a
                defined scheduling policy.

94  –  sched_yield

    Yields execution to another thread.

    Syntax

      sched_yield();

94.1  –  C Binding

    #include <sched.h>
    #include <unistd.h>

    int
    sched_yield (void);

94.2  –  Arguments

    None

94.3  –  Description

    In conformance with the IEEE POSIX.1-1996 standard, the sched_
    yield() function causes the calling thread to yield execution
    to another thread. It is useful when a thread running under the
    SCHED_FIFO scheduling policy must allow another thread at the
    same priority to run. The thread that is interrupted by sched_
    yield() goes to the end of the queue for its priority.

    If no other thread is runnable at the priority of the calling
    thread, the calling thread continues to run.

    Threads with higher priority are allowed to preempt the calling
    thread, so the sched_yield() function has no effect on the
    scheduling of higher- or lower-priority threads.

    The sched_yield() routine takes no arguments. No special
    privileges are needed to use the sched_yield() function.

94.4  –  Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [ENOSYS]    The routine sched_yield()  is not supported by this
                implementation.

94.5  –  Associated Routines

       pthread_attr_setschedparam()
       pthread_getschedparam()
       pthread_setschedparam()
Close Help