-------------------------------------------------- Introduction to POSIX Threads (pthreads) -------------------------------------------------- DESCRIPTION DECthreads are a set of POSIX thread (pthread) routines that you can call to create a multithreaded program. The pthread routines are the DECthreads implementation of the IEEE Std 1003.1c-1995, POSIX System Application Pro- gram Interface. Note that POSIX Standard 1003.1c now supercedes the draft standard 1003.4a. A thread is a single, sequential flow of control within a program. Within a single thread, there is a single point of execution. Most traditional programs consist of a single thread. Using DECthreads, Digital's multithreading run-time library, a programmer can create several threads within a program. Threads execute concurrently, and, within a multithreaded program, there are at any time multiple points of execution. Threads execute within (and share) a single address space. Therefore, threads read and write the same memory locations. Synchroniza- tion elements such as mutexes and condition variables ensure that the shared memory is accessed correctly. DECthreads provides routines that allow you to create and use these synchronization elements. Mutexes and condition variables are discussed in the Guide to DECthreads. Previous pthread users should be aware that applications consistent with the P1003.4a/D4 interface require significant modifications to upgrade to the DECthreads interface that conforms to the final 1003.1c standard. Routine names ending with the _np suffix denote that the routine is not portable; the routine might not be available in other vendor implementa- tions of POSIX 1003.1c. Compile a multithreaded application using shared versions of libmach and libpthread as follows: cc -o myprog myprog.c -pthread If you use a compiler front-end or other (not C) language environment that does not support the -pthread compilation switch, you must use the -D_THREAD_SAFE compilation switch. You must link your multithreaded application using these switches: -lpthread -lmach -lexc -lc Each C module that utiltizes DECthreads exceptions must include the pthread_exception.h header file. The Guide to DECthreads describes the use of DECthreads exceptions. For more information, see the routine manpages and the Guide to DECthreads. The Guide to DECthreads describes important considerations for threaded application development, particularly for the Digital UNIX operating system. The pthread interface routines are grouped in the following functional cat- egories: o General Threads Routines o Attributes Object Routines o Condition Variable Routines o Mutex Routines o Thread-Specific Data Routines o Thread Cancelation Routines o Thread Priority and Scheduling Routines DECthreads also provides routines that implement nonportable extensions to the POSIX 1003.1c standard. These routines are grouped into these func- tional categories: o Attributes Object Routines o Debugging Support Routines o Thread-Specific Data Routines *** General Threads Routines pthread_atfork Declares fork handlers to be called. pthread_create Creates a thread object and thread. pthread_detach Marks a thread object for deletion. pthread_equal Compares one thread identifier to another thread identifier. pthread_exit Terminates the calling thread. pthread_join Causes the calling thread to wait for the termination of a specified thread and detach it. pthread_kill Delivers a signal to a specified thread. pthread_once Calls an initialization routine to be executed only once. pthread_self Obtains the identifier of the current thread. pthread_sigmask Examines or changes the current thread's signal mask. *** Attributes Object Routines pthread_attr_destroy Destroys a thread attributes object. pthread_attr_getdetachstate Obtains the detachstate attribute from the specified thread attributes object. pthread_attr_getinheritsched Obtains the inherit scheduling attribute from the specified thread attributes object. pthread_attr_getschedparam Obtains the scheduling parameters for an attribute of the specified thread attributes object. pthread_attr_getschedpolicy Obtains the scheduling policy attribute of the specified thread attributes object. pthread_attr_getstacksize Obtains the stacksize attribute of the specified thread attributes object. pthread_attr_init Initializes a thread attributes object. pthread_attr_setdetachstate Changes the detachstate attribute in the specified thread attributes object. pthread_attr_setinheritsched Changes the inherit scheduling attribute of the specified thread attributes object. pthread_attr_setschedparam Changes the values of the parameters associated with the scheduling policy attribute of the specified thread attributes object. pthread_attr_setschedpolicy Changes the scheduling policy attribute of the specified thread attributes object. pthread_attr_setstacksize Changes the stacksize attribute in the specified thread attributes object. *** Condition Variable Attributes Object Routines pthread_condattr_init Initializes a condition variable attributes object that spec- ifies condition variable attributes when created. pthread_condattr_destroy Destroys a condition variable attributes object. Mutex Attributes Object Routines pthread_mutexattr_init Initializes a mutex attributes object. pthread_mutexattr_destroy Destroys a mutex attributes object. *** Mutex Routines pthread_mutex_destroy Destroys a mutex. pthread_mutex_init Initializes a mutex with attributes specified by the attributes argument. pthread_mutex_lock Locks an unlocked mutex. If locked, the caller waits for the mutex to become available. pthread_mutex_trylock Locks an unlocked mutex or returns immediately if mutex is locked. pthread_mutex_unlock Unlocks a mutex. *** Condition Variable Routines pthread_cond_broadcast Wakes all threads waiting on a condition variable. pthread_cond_destroy Destroys a condition variable. pthread_cond_init Initializes a condition variable. pthread_cond_signal Wakes at least one thread that is waiting on a condition variable. pthread_cond_timedwait Causes a thread to wait for a condition variable to be sig- naled or broadcasted for a specified period of time. pthread_cond_wait Causes a thread to wait for a condition variable to be sig- naled or broadcasted. *** Thread-Specific Data Routines pthread_getspecific Obtains the thread-specific data associated with the speci- fied key. pthread_key_create Generates a unique thread-specific data key. pthread_setspecific Sets the thread-specific data value associated with the spec- ified key for the current thread. pthread_key_delete Deletes a thread-specific data key. *** Thread Cancellation Routines pthread_cancel Allows a thread to request that it, or another thread termi- nate execution. pthread_cleanup_pop Removes a cleanup handler at the top of the cleanup stack and optionally executes it. pthread_cleanup_push Establishes a cleanup handler to be executed when the thread exits or is canceled. pthread_setcancelstate Sets the current thread's cancelability state. pthread_setcanceltype Sets the current thread's cancelability type. pthread_testcancel Requests delivery of any pending cancel to the current thread. *** Thread Priority and Scheduling Routines pthread_getschedparam Obtains the current scheduling policy and sceduling parame- ters of a thread. pthread_getsequence_np Obtains a thread sequence number. pthread_setschedparam Changes the current scheduling policy and scheduling parame- ters of a thread. sched_yield Notifies the scheduler that the current thread will release its processor to other threads of the same or higher prior- ity. *** Non-Portable Extensions Non-Portable Extensions: Thread Attributes Routines pthread_attr_getguardsize_np Obtains the guardsize attribute of the specified thread attibutes object. pthread_attr_setguardsize_np Changes the guardsize attribute of the specified thread attributes object. Non-Portable Extensions: Thread Execution Routines pthread_delay_np Causes a thread to delay execution. pthread_getexpiration_np Obtains a value representing a desired expiration time. pthread_getsequence_np Obtains the thread sequence number. Non-Portable Extensions: Mutex Routines pthread_lock_global_np Locks the global mutex if it is unlocked. pthread_unlock_global_np Unlocks a global mutex. Non-Portable Extensions: Mutex Attributes Routines pthread_mutexattr_gettype_np Obtains the mutex type attribute used when a mutex is cre- ated. pthread_mutexattr_settype_np Specifies the mutex type attribute that is used when a mutex is created. Non-Portable Extensions: Condition Variable Routines pthread_cond_signal_int_np Wakes one thread that is waiting on a condition variable. Non-Portable Extensions: Debugging Support Routines pthread_debug Invokes the DECthreads internal debugger. pthread_debug_cmd Passes a list of commands to the DECthreads internal debug- ger. delim off delim off *** /usr/man/man3/pthread_atfork.3.gz *** pthread_atfork(3) pthread_atfork(3) NAME pthread_atfork - Declares handlers to be called when the process forks a child. LIBRARY Standard C Library (libc.so, libc.a) SYNOPSIS #include int pthread_atfork( void (*prepare)(void), void (*parent)(void), void (*child)(void)); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS prepare Address of a procedure that performs the fork preparation han- dling. This routine is called in the parent process before cre- ating the child. parent Address of a procedure that performs the fork parent handling. This routine is called in the parent process after creating the child and before returning to the caller of fork(2). child Address of a procedure that performs the fork child handling. This routine is called in the child process before returning to the caller of fork(2). DESCRIPTION This routine allows a main program or library to control resources during a UNIX fork(2) operation by declaring fork handlers that are called before and after the fork(2) execution. The prepare fork handler is called before the fork(2) execution. The parent handler is called after the fork(2) exe- cution within the parent process, and the child handler is called after fork(2) in the new child process. If no handling is desired, you can set any of the arguments to a NULL. Mutex locks might be held by threads that no longer exist in a child pro- cess, and any associated state might be inconsistent. The program can avoid this problem by calling pthread_atfork to provide code that acquires and releases locks critical to the child process. NOTES It is not legal to call pthread_atfork from within a handler routine. Doing so could cause a deadlock. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion [ENOMEM] Insufficient table space exists to record the fork handler addresses. ERRORS None EXAMPLES For example, if your library uses a mutex named "my_mutex", you might pro- vide pthread_atfork handlers like: void my_prepare(void) { pthread_mutex_lock(&my_mutex); } void my_parent(void) { pthread_mutex_unlock(&my_mutex); } void my_child(void) { pthread_mutex_unlock(&my_mutex); /* Reinitialize state that doesn't apply...like heap owned */ /* by other threads */ } { . . . pthread_atfork(my_prepare, my_parent, my_child); . . fork(); } RELATED INFORMATION Functions: pthread_create(3) Manuals: Guide to DECthreads, Programmer's Guide delim off *** /usr/man/man3/pthread_attr_destroy.3.gz *** pthread_attr_destroy(3) pthread_attr_destroy(3) NAME pthread_attr_destroy - Destroys a thread attributes object. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_attr_destroy( pthread_attr_t *attr); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS attr Thread attributes object to be destroyed. 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 speci- fied by the attr argument refers to a thread attributes object that does not exist. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion [EINVAL] The value specified for attr is invalid. ERRORS None RELATED INFORMATION Functions: pthread_attr_init(3), pthread_create(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_attr_getdetachstate.3.gz *** pthread_attr_getdetachstate(3) pthread_attr_getdetachstate(3) NAME pthread_attr_getdetachstate - Obtains the detachstate attribute of the specified thread attributes object. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_attr_getdetachstate( const pthread_attr_t *attr, int *detachstate); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS attr Thread attributes object whose detachstate attribute is obtained. detachstate Receives the value of the detachstate attribute. DESCRIPTION This routine obtains the detachstate attribute of a thread attributes object. This attribute specifies whether threads created using the speci- fied thread attributes object are created in detached state. See the pthread_attr_setdetachstate description for information about the detachstate attribute. RETURN VALUES On successful completion, this routine returns a zero, and the detachstate attribute is set in detachstate. A value of PTHREAD_CREATE_JOINABLE indi- cates the thread is not detached, and a value of PTHREAD_CREATE_DETACHED indicates the thread is detached. If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. The detached state attribute is returned in detachstate. [EINVAL] The value specified by attr does not refer to an existing thread attributes object. ERRORS None RELATED INFORMATION Functions: pthread_attr_setdetachstate(3), pthread_attr_init(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_attr_getguardsize_np.3.gz *** pthread_attr_getguardsize_np(3) pthread_attr_getguardsize_np(3) NAME pthread_attr_getguardsize_np - Obtains the guardsize attribute of the spec- ified thread attributes object. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_attr_getguardsize_np( const pthread_attr_t *attr, size_t *guardsize); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS attr Thread attributes object whose guardsize attribute is obtained. guardsize Receives the value of the guardsize attribute. The guardsize argument specifies the minimum size (in bytes) of the guard area for a thread. DESCRIPTION This routine obtains the minimum size (in bytes) of the guard area for the stack of a thread that is created using the attributes object specified by the attr argument. A guard area helps to detect stack overflows by preventing memory access beyond the thread's stack. Large guard areas are necessary when threads might allocate large structures on the stack. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] The value specified by attr is invalid. ERRORS None RELATED INFORMATION Functions: pthread_attr_init(3), pthread_attr_setstacksize(3), pthread_attr_setguardsize_np(3), pthread_create(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_attr_getinheritsched.3.gz *** pthread_attr_getinheritsched(3) pthread_attr_getinheritsched(3) NAME pthread_attr_getinheritsched - Obtains the inherit scheduling attribute of the specified thread attributes object. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_attr_getinheritsched( const pthread_attr_t *attr, int *inheritsched); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS 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. DESCRIPTION This routine obtains the value of the inherit scheduling attribute of the specified thread attributes object. The inherit scheduling attribute speci- fies 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_cre- ate. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] The value specified by attr is invalid. ERRORS None RELATED INFORMATION Functions: pthread_attr_init(3), pthread_attr_setinheritsched(3), pthread_create(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_attr_getschedparam.3.gz *** pthread_attr_getschedparam(3) pthread_attr_getschedparam(3) NAME pthread_attr_getschedparam - Obtains the scheduling parameters for an attribute of the specified thread attributes object. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_attr_getschedparam( const pthread_attr_t *attr, struct sched_param *param); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS 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_setsched- param function for valid parameters and their values. DESCRIPTION This routine obtains the scheduling parameters associated with the schedul- ing policy attribute of the specified thread attributes object. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] The value specified by attr is invalid. ERRORS None RELATED INFORMATION Functions: pthread_attr_init(3), pthread_attr_setschedparam(3), pthread_create(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_attr_getschedpolicy.3.gz *** pthread_attr_getschedpolicy(3) pthread_attr_getschedpolicy(3) NAME pthread_attr_getschedpolicy - Obtains the scheduling policy attribute of the specified thread attributes object. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_attr_getschedpolicy( const pthread_attr_t *attr, int *policy); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS attr Thread attributes object whose scheduling policy attribute is obtained. policy Receives the value of scheduling policy attribute. Refer to the description of the pthread_attr_setschedpolicy function for valid values. 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. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] The value specified by attr is invalid. ERRORS None RELATED INFORMATION Functions: pthread_attr_init(3), pthread_attr_setschedpolicy(3), pthread_create(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_attr_getstacksize.3.gz *** pthread_attr_getstacksize(3) pthread_attr_getstacksize(3) NAME pthread_attr_getstacksize - Obtains the value of the stacksize attribute in the specified thread attributes object. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_attr_getstacksize( const pthread_attr_t *attr, size_t *stacksize); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS attr Thread attributes object whose stacksize attribute is obtained. stacksize Receives the value of the stacksize attribute. DESCRIPTION This routine obtains the stacksize attribute of a specified thread attributes (attr) object. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] The value specified by attr is invalid. ERRORS None RELATED INFORMATION Functions: pthread_attr_init(3), pthread_attr_setstacksize(3), pthread_cre- ate(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_attr_init.3.gz *** pthread_attr_init(3) pthread_attr_init(3) NAME pthread_attr_init - Initializes a thread attributes object. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_attr_init( pthread_attr_t *attr,); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS attr Thread attributes object to be initialized. DESCRIPTION This routine initializes a thread attributes object that is used to specify the attributes of threads when they are created. The attributes object cre- ated by this routine is used only in calls to pthread_create. The following routines change the initialized individual attributes of a thread attributes object: o pthread_attr_setdetachstate o pthread_attr_setguardsize_np o pthread_attr_setinheritsched o pthread_attr_setschedparam o pthread_attr_setschedpolicy o pthread_attr_setstacksize The individual attributes (internal fields) of the attributes object are initialized to default values. The default values of each attribute are discussed in the descriptions of the routines listed above. When an attributes object is used to create a thread, the values of the individual attributes determine the characteristics of the new thread. Attributes objects act as additional arguments to thread creation. Changing individual attributes does not affect any threads that were previously cre- ated using the attributes object. You can use a single attributes object in multiple calls to pthread_create, from any thread. If multiple threads might change attributes in a shared attributes object, the application code must protect the integrity of the attributes object by using a mutex. When you set the scheduling policy or scheduling parameters, or both, in an 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, use the pthread_attr_setinheritsched routine, spec- ifying the value PTHREAD_EXPLICIT_SCHED for the inherit argument, before calling pthread_create. 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: 0 Successful completion. [EINVAL] The value specified by attr is invalid. [ENOMEM] Insufficient memory exists to initialize the thread attributes object. ERRORS None RELATED INFORMATION Functions: pthread_attr_destroy(3), pthread_attr_setdetachstate(3), pthread_setguardsize_np(3), pthread_setinheritsched(3), pthread_attr_setschedparam(3), pthread_attr_setschedpolicy(3), pthread_attr_setstacksize(3), pthread_attr_setguardsize_np(3), pthread_cre- ate(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_attr_setdetachstate.3.gz *** pthread_attr_setdetachstate(3) pthread_attr_setdetachstate(3) NAME pthread_attr_setdetachstate - Changes the detachstate attribute of the specified thread attributes object. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_attr_setdetachstate( pthread_attr_t *attr, int detachstate); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS attr Thread attributes object to be modified. detachstate New value for the detachstate attribute. The following are valid values: PTHREAD_CREATE_JOINABLE This the default value. Threads are created in "unde- tached" state. PTHREAD_CREATE_DETACHED The created thread is detached immediately, before it begins running. DESCRIPTION This routine changes the detachstate attribute in the thread creation attributes. This attribute specifies whether the threads created using the specified thread attributes object are 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. You cannot use the thread handle (the value of type pthread_t that is returned by pthread_create) for a detached thread. This means that you cannot cancel the thread with pthread_cancel. You also cannot use pthread_join to wait for the thread to complete or to retrieve the thread's return status. When a thread that has not been detached completes execution, DECthreads will retain the state of that thread to allow another thread to join with it. If the thread is detached before it completes, DECthreads 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, create the thread initially detached. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. The detached state attribute is returned in detachstate. [EINVAL] The value specified by the detachstate argument is invalid. ERRORS None RELATED INFORMATION Functions: pthread_attr_init(3), pthread_attr_getdetachstate(3), pthread_create(3), pthread_join(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_attr_setguardsize_np.3.gz *** pthread_attr_setguardsize_np(3) pthread_attr_setguardsize_np(3) NAME pthread_attr_setguardsize_np - Changes the guardsize attribute of the spec- ified thread attributes object. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_attr_setguardsize_np( pthread_attr_t *attr, size_t guardsize); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS attr Thread attributes object to be modified. guardsize New value for the guardsize attribute. The guardsize argument specifies the minimum size (in bytes) of the guard area for the stack of a thread. DESCRIPTION This routine sets the minimum size (in bytes) of the guard area for the stack of a thread that is created using the attributes object specified by the attr argument. A guard area helps to detect stack overflows by preventing memory access beyond the thread's stack. Large guard areas are necessary when threads might allocate large structures on the stack. The default value is platform dependent, but will always be at least one "hardware protection unit" (at least one page). RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] The value specified by attr is invalid. ERRORS None RELATED INFORMATION Functions: pthread_attr_init(3), pthread_attr_getguardsize_np(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_attr_setinheritsched.3.gz *** pthread_attr_setinheritsched(3) pthread_attr_setinheritsched(3) NAME pthread_attr_setinheritsched - Changes the inherit scheduling attribute of the specified thread attributes object. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_attr_setinheritsched( pthread_attr_t *attr, int inheritsched); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS attr Thread attributes object to be modified. inheritsched New value for the inherit scheduling attribute. The following are valid values: PTHREAD_INHERIT_SCHED The created thread inherits the scheduling policy and asso- ciated 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_SCHED The scheduling policy and associated scheduling attributes of the created thread are set to the corresponding values from the attribute object specified by the pthread_create attr argument. DESCRIPTION This routine changes the inherit scheduling attribute of thread creation. The inherit scheduling attribute specifies whether threads created using the specified attributes object inherit the scheduling attributes of the creating thread, or use 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, respectively. Inheriting scheduling attributes (instead of using the scheduling attributes stored in the attributes object) is useful when a thread is cre- ating several helper threads---threads that are intended to work closely with the creating thread to cooperatively solve the same problem. For exam- ple, inherited scheduling attributes ensure that helper threads created in a sort routine execute with the same priority as the calling thread. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] One or both of the values specified by inherit or by attr is invalid. [ENOTSUP] An attempt was made to set the attribute to an unsupported value. ERRORS None RELATED INFORMATION Functions: pthread_attr_init(3), pthread_attr_getinheritsched(3), pthread_attr_setschedpolicy(3), pthread_attr_setschedparam(3), pthread_cre- ate(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_attr_setschedparam.3.gz *** pthread_attr_setschedparam(3) pthread_attr_setschedparam(3) NAME pthread_attr_setschedparam - Changes the values of the parameters associ- ated with a scheduling policy of the specified thread attributes object. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_attr_setschedparam( pthread_attr_t *attr, const struct sched_param *param); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS attr Thread attributes object for the scheduling policy whose parame- ters are to be set. param A structure containing new values for scheduling parameters asso- ciated with the scheduling policy attribute defined for the spec- ified thread attributes object. Note that DECthreads provides only the sched_priority scheduling parameter. It allows you to specify the scheduling priority. See the Description section for information about this scheduling parameter. DESCRIPTION This routine sets the scheduling parameters associated with the scheduling policy attribute for the thread attributes object specified by the attr argument. Use the sched_priority scheduling parameter 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 inher- itance must be disabled at the time the thread is created. Call pthread_attr_setinheritsched and specify the value PTHREAD_EXPLICIT_SCHED for the inherit argument before calling pthread_create. 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 ACCESSING SHARED DATA. With a sufficient number of proces- sors executing, all ready threads, regardless of priority, execute simulta- neously. Valid values of the sched_priority scheduling parameter depend on the cho- sen policy and fall within one of the following policy ranges: SCHED_FIFO: PRI_FIFO_MIN to PRI_FIFO_MAX SCHED_RR: PRI_RR_MIN to PRI_RR_MAX SCHED_OTHER: PRI_OTHER_MIN to PRI_OTHER_MAX SCHED_FG_NP: PRI_FG_MIN_NP to PRI_FG_MAX_NP SCHED_BG_NP: PRI_BG_MIN_NP to PRI_BG_MAX_NP The default priority is the midpoint between PRI_OTHER_MIN and PRI_OTHER_MAX for the SCHED_OTHER policy. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] The value specified by param is invalid. [ENOTSUP] An attempt was made to set the attribute to an unsupported value. ERRORS None RELATED INFORMATION Functions: pthread_attr_init(3), pthread_attr_getschedparam(3), pthread_attr_setinheritsched(3), pthread_attr_setschedpolicy(3), pthread_create(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_attr_setschedpolicy.3.gz *** pthread_attr_setschedpolicy(3) pthread_attr_setschedpolicy(3) NAME pthread_attr_setschedpolicy - Changes the scheduling policy attribute of the specified thread attributes object. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_attr_setschedpolicy( pthread_attr_t *attr, int policy); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS attr Thread attributes object to be modified. policy New value for the scheduling policy attribute. Valid values are as follows: o SCHED_FIFO, SCHED_RR, SCHED_FG_NP (also known as SCHED_OTHER), SCHED_BG_NP o SCHED_OTHER is the default value. 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 priority of the thread calling pthread_create. To specify a priority using this routine, scheduling inher- itance must be disabled at the time the thread is created. Call pthread_attr_setinheritsched and specify the value PTHREAD_EXPLICIT_SCHED for the inherit argument before calling pthread_create. Never attempt to use scheduling as a mechanism for synchronization. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] The value specified by policy is invalid. ERRORS None RELATED INFORMATION Functions: pthread_attr_init(3), pthread_attr_getschedpolicy(3), pthread_attr_setinheritsched(3), pthread_attr_setschedparam(3), pthread_create(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_attr_setstacksize.3.gz *** pthread_attr_setstacksize(3) pthread_attr_setstacksize(3) NAME pthread_attr_setstacksize - Changes the stacksize attribute in the speci- fied thread attributes object. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_attr_setstacksize( pthread_attr_t *attr, size_t stacksize); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS attr Thread attributes object to be modified. stacksize New value for the stacksize attribute. The stacksize argument must be greater than or equal to PTHREAD_STACK_MIN. PTHREAD_STACK_MIN specifies the minimum size (in bytes) of stack needed for a thread. DESCRIPTION This routine sets the stacksize attribute in the attr object. Use this rou- tine to adjust the size of the writable area of the stack for threads that will be created. A thread's stack is fixed at the time of thread creation. Only the initial thread can dynamically extend its stack. Many compilers do not check for stack overflow. Ensure that your thread stack is large enough for anything that you call from the thread. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] The value specified by attr is invalid, or the value specified by stacksize is less than PTHREAD_STACK_MIN or exceeds a system- imposed limit. ERRORS None RELATED INFORMATION Functions: pthread_attr_init(3), pthread_attr_getstacksize(3), pthread_cre- ate(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_cancel.3.gz *** pthread_cancel(3) pthread_cancel(3) NAME pthread_cancel - Allows a thread to request that it or another thread ter- minate execution. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_cancel( pthread_t thread); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS thread Thread that receives a cancel request. DESCRIPTION This routine sends a cancel to the specified thread. A cancel is a mecha- nism by which a calling thread requests the specified thread to terminate as quickly as possible. Issuing a cancel does not guarantee that the speci- fied thread will receive or handle the cancel. When the cancellation is acted on, all active cleanup handlers for thread are called. When the last cleanup handler returns, the thread-specific data destructor functions shall be called for each thread-specific data key with a destructor and for which the thread has a non-NULL value. Finally, the thread is terminated. The cancellation processing in the target thread runs asychronously with respect to the calling thread returning from pthread_cancel. The target thread cancelability state and type determine when or if the cancellation takes place: o The canceled thread can delay cancellation during critical operations by setting its cancelability state to PTHREAD_CANCEL_DISABLE. o Because of communication delays, the calling thread can only rely on the fact that a cancel will eventually become pending in the desig- nated thread (provided that the thread does not terminate beforehand). o The calling thread has no guarantee that a pending cancel will be delivered, because delivery is controlled by the designated thread. When a cancel is delivered to a thread, termination processing is similar to pthread_exit. For more information about thread termination, see the discussion of thread termination in pthread_create(3). This routine is preferred in implementing an Ada abort statement and any other language- or software-defined construct for requesting thread cancellation. The results of this routine are unpredictable if the value specified in thread refers to a thread that does not currently exist. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] The specified thread is invalid. [ESRCH] thread does not specify an existing thread. ERRORS None RELATED INFORMATION Functions: pthread_create(3), pthread_exit(3), pthread_join(3), pthread_setcanceltype(3), pthread_setcancelstate(3), pthread_cleanup_pop(3), pthread_cleanup_push(3), pthread_testcancel(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_cleanup_pop.3.gz *** pthread_cleanup_pop(3) pthread_cleanup_pop(3) NAME pthread_cleanup_pop - Removes the cleanup handler and optionally executes it. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_cleanup_pop( int execute); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS execute Integer that specifies whether the cleanup routine specified in the matching call to pthread_cleanup_push is executed. A nonzero value will cause the routine to be executed. The routine can be used to clean up from a block of code, whether exited by cancel- lation or normal completion. DESCRIPTION This routine removes the cleanup routine and executes it if the value spec- ified in execute is nonzero. 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 (}). RETURN VALUES None RELATED INFORMATION Functions: pthread_cancel(3), pthread_create(3), pthread_cleanup_push(3), pthread_exit(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_cleanup_push.3.gz *** pthread_cleanup_push(3) pthread_cleanup_push(3) NAME pthread_cleanup_push - Establishes a cleanup handler that is executed when the thread exits or is canceled. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_cleanup_push( void (*routine)(void *), void *arg); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS routine Routine executed as the cleanup handler. arg Argument executed with the cleanup routine. DESCRIPTION This routine pushes the specified routine onto the calling thread's cleanup stack. The cleanup routine is popped from the stack and executed with the arg argument when any of the following actions occur: o The thread calls pthread_exit. o The thread is canceled. o An exception is raised (while the cleanup routine is in effect) and results in an unwind through the scope of the pthread_cleanup_push and pthread_cleanup_pop pair. o The thread calls pthread_cleanup_pop and specifies a nonzero value for the execute argument. 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 (}). RETURN VALUES None RELATED INFORMATION Functions: pthread_cancel(3), pthread_create(3), pthread_cleanup_pop(3), pthread_exit(3), thread_testcancel(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_cond_broadcast.3.gz *** pthread_cond_broadcast(3) pthread_cond_broadcast(3) NAME pthread_cond_broadcast - Wakes all threads that are waiting on a condition variable. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_cond_broadcast( pthread_cond_t *cond); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS cond Condition variable upon which the threads to be awakened are waiting. DESCRIPTION This routine unblocks all threads waiting on the specified condition vari- able cond. Calling this routine implies that data guarded by the associ- ated mutex has changed, so that it might be possible for one or more wait- ing threads to proceed. The threads that are unblocked shall contend for the mutex according to the scheduling policy (if applicable). If only one of the threads waiting on a condition variable may be able to proceed, but any single thread 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, then 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, then this routine takes no action. The broadcast does not propagate to the next con- dition variable wait. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] The value specified by cond is invalid. ERRORS None RELATED INFORMATION Functions: pthread_cond_destroy(3), pthread_cond_init(3), pthread_cond_sig- nal(3), pthread_cond_timedwait(3), pthread_cond_wait(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_cond_destroy.3.gz *** pthread_cond_destroy(3) pthread_cond_destroy(3) NAME pthread_cond_destroy - Destroys a condition variable. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_cond_destroy( pthread_cond_t *cond); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS cond Condition variable to destroy. DESCRIPTION This routine destroys the condition variable specified by cond. This effectively uninitializes the condition variable. You call this routine when a condition variable will no longer be referenced. Destroying a con- dition variable may allow DECthreads 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 does not exist or is not initialized. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] The value specified by cond is invalid. [EBUSY] The object being referenced by cond is being referenced by another thread that is currently executing a pthread_cond_wait or pthread_cond_timedwait on the condition variable specified in cond. ERRORS None RELATED INFORMATION Functions: pthread_cond_broadcast(3), pthread_cond_init(3), pthread_cond_signal(3), pthread_cond_timedwait(3), pthread_cond_wait(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_cond_init.3.gz *** pthread_cond_init(3) pthread_cond_init(3) NAME pthread_cond_init - Initializes a condition variable. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_cond_init( pthread_cond_t *cond, const pthread_condattr_t *attr); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS cond Condition variable to initialize. attr Condition variable attributes object that defines the character- istics of the condition variable to initialize. DESCRIPTION This routine initializes a condition variable (cond) with attributes refer- enced by attr. 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 shared data; 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 termi- nates. The macro PTHREAD_COND_INITIALIZER can be used to initialize statically allocated condition variables to the default condition variable attributes. To call this macro, enter: pthread_cond_t condition = PTHREAD_COND_INITIALIZER When statically initialized, a condition variable should not also be using pthread_cond_init. Also, a statically initialized condition variable need not be destroyed using pthread_cond_destroy. Under certain circumstances, it may 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 may return ENOMEM. You can avoid this possibility by initializing critical condition variables with pthread_cond_init. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error, the condition variable is not initialized, and the contents of cond are undefined. Possible return values are as follows: 0 Successful completion. [EINVAL] The value specified by attr is invalid. [EAGAIN] The system lacks the necessary resources to initialize another condition variable, or The system-imposed limit on the total number of condition vari- ables 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. [ENOMEM] Insufficient memory exists to initialize the condition variable. ERRORS None RELATED INFORMATION Functions: pthread_cond_broadcast(3), pthread_cond_destroy(3), pthread_cond_signal(3), pthread_cond_timedwait(3), pthread_cond_wait(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_cond_signal.3.gz *** pthread_cond_signal(3) pthread_cond_signal(3) NAME pthread_cond_signal - Wakes at least one thread that is waiting on a condi- tion variable. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_cond_signal( pthread_cond_t *cond); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS cond Condition variable to be signaled. DESCRIPTION This routine unblocks at least one thread waiting on the specified condi- tion variable cond. Calling this routine implies that data guarded by the associated mutex has changed, so that it might be possible for one of the waiting threads to proceed. In general, only one will be released. If no threads are waiting on the specified condition variable, then this routine takes no action. The signal does not propagate to the next condi- tion variable wait. This routine should be called when any thread waiting on the specified con- dition variable might find its predicate true, but only one thread should proceed. If more than one thread can proceed, or if any thread 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. You can call this routine even when the associated mutex is locked. How- ever, if predictable scheduling behavior is required, then that mutex should be locked by the thread calling pthread_cond_signal. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] The value specified by cond is invalid. ERRORS None RELATED INFORMATION Functions: pthread_cond_broadcast(3), pthread_cond_destroy(3), pthread_cond_init(3), pthread_cond_timedwait(3), pthread_cond_wait(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_cond_signal_int_np.3.gz *** pthread_cond_signal_int_np(3) pthread_cond_signal_int_np(3) NAME pthread_cond_signal_int_np - Wakes one thread that is waiting on a condi- tion variable (called from interrupt level only). LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_cond_signal_int_np( pthread_cond_t *cond); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS cond Condition variable to be signaled. DESCRIPTION This routine wakes one thread waiting on a condition variable. It can only be called from a software interrupt handler routine (that is, from a Digi- tal 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 returns. You can call this routine regardless of whether the associated mutex is locked. Never try to lock a mutex from an interrupt handler. Note This routine allows you to signal a thread from a software interrupt handler. Do not call this routine from noninterrupt code. To signal a thread from the normal noninterrupt level, use pthread_cond_signal. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] The value specified by cond is invalid. ERRORS None RELATED INFORMATION Functions: pthread_cond_broadcast(3), pthread_cond_signal(3), pthread_cond_timedwait(3), pthread_cond_wait(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_cond_timedwait.3.gz *** pthread_cond_timedwait(3) pthread_cond_timedwait(3) NAME pthread_cond_timedwait - Causes a thread to wait for a condition variable to be signaled or broadcasted, such that it will awake after a specified period of time. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_cond_timedwait( pthread_cond_t *cond, pthread_mutex_t *mutex, const struct timespec *abstime); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS cond Condition variable that a 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 broadcasted. 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. Seconds since the Epoch is a value interpreted as the number of seconds between a specified time and the Epoch. DESCRIPTION This routine causes a thread to wait until one of the following occurs: o The specified condition variable is signaled or broadcasted. 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 broadcasted; specifi- cally, when a 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. The atomicity is important, because it means the thread cannot miss a wakeup while the mutex is unlocked. When the timer expires or when the wait is satisfied as a result of some thread calling thread_cond_signal or pthread_cond_broadcast, the mutex is reacquired before returning to the caller. If the current time equals or exceeds the expiration time, this routine returns immediately, without releasing the mutex or causing the current thread to wait. 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 lock the mutex specified in mutex. The results of this routine are unpredictable if this routine is called without first locking the mutex. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 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 cur- rent thread at the time of the call. [ETIMEDOUT] The time specified by abstime expired. [ENOMEM] DECthreads cannot acquire memory needed to block using a stati- cally initialized condition variable. ERRORS None RELATED INFORMATION Functions: pthread_cond_broadcast(3), pthread_cond_destroy(3), pthread_cond_init(3), pthread_cond_signal(3), pthread_cond_wait(3), pthread_get_expiration_np(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_cond_wait.3.gz *** pthread_cond_wait(3) pthread_cond_wait(3) NAME pthread_cond_wait - Causes a thread to wait for a condition variable to be signaled or broadcasted. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_cond_wait( pthread_cond_t *cond, pthread_mutex_t *mutex); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS cond Condition variable that a thread waits on. mutex Mutex associated with the condition variable specified in cond. DESCRIPTION This routine causes a thread to wait for a condition variable to be sig- naled or broadcasted. Each condition corresponds to one or more Boolean relations (predicates) 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. The atomicity is important, because it means the thread cannot miss a wakeup while the mutex is unlocked. When the wait is satisfied as a result of some thread calling pthread_cond_signal or pthread_cond_broadcast, the mutex is reacquired before returning to the caller. 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 vari- able has not been signaled or broadcasted. When this occurs, the mutex is reacquired before the routine returns. To handle this type of situation, enclose this routine in a loop that checks the predicate. The loop pro- vides documentation of your intent and protects against these spurious wakeups while also allowing correct behavior, even if another thread con- sumes the desired state before the awakened thread runs. It is illegal for threads to wait on the same condition variable by speci- fying different mutexes. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] The value specified by cond, or mutex is invalid, or: Different mutexes are supplied for concurrent pthread_cond_timed- wait operations or pthread_cond_wait operations on the same con- dition variable, or: The mutex was not owned by the current thread at the time of the call. [ENOMEM] DECthreads cannot acquire memory needed to block using a stati- cally initialized condition variable. ERRORS None RELATED INFORMATION Functions: pthread_cond_broadcast(3), pthread_cond_destroy(3), pthread_cond_init(3), pthread_cond_signal(3), pthread_cond_timedwait(3), Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_condattr_destroy.3.gz *** pthread_condattr_destroy(3) pthread_condattr_destroy(3) NAME pthread_condattr_destroy - Destroys a condition variable attributes object. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_condattr_destroy( pthread_condattr_t *attr); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS attr Condition variable attributes object to be destroyed. DESCRIPTION This function destroys a condition variable attributes object (the object becomes uninitialized). Condition variables that were created using this attributes object are not affected by the destruction of the condition variable attributes object. After calling this routine, the results of using attr in a call to any rou- tine (other than pthread_condattr_init are unpredictable. RETURN VALUES If an error condition occurs, this function returns an integer value indi- cating the type of error. Possible error return values are as follows: 0 Successful completion [EINVAL] The attributes object specified by attr is invalid. ERRORS None RELATED INFORMATION Functions: pthread_condattr_init(3) Manuals: Guide to DECthreads, Programmer's Guide delim off *** /usr/man/man3/pthread_condattr_init.3.gz *** pthread_condattr_init(3) pthread_condattr_init(3) NAME pthread_condattr_init - Initializes a condition variable attributes object that can be used to specify the attributes of condition variables when they are created. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_condattr_init( pthread_condattr_t *attr); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS attr Condition variable attributes object to initialize. DESCRIPTION This routine initializes the condition variable attributes object (attr) that is used to specify the attributes of condition variables when they are initialized. The condition variable attributes object is initialized with the default attribute values. When a condition variable attributes object is used to initialize a condi- tion variable, the values of the individual attributes determine the char- acteristics of the new object. Attributes objects act like additional argu- ments to object initialization. Changing individual attributes does not affect objects that were previously initialized using the attributes object. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [ENOMEM] Insufficient memory exists to initialize the condition variable attributes object. ERRORS None RELATED INFORMATION Functions: pthread_condattr_destroy(3), pthread_cond_init(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_create.3.gz *** pthread_create(3) pthread_create(3) NAME pthread_create - Creates a thread. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_create( pthread_t *thread, const pthread_attr_t *attr, void * (*start_routine)(void *), void *arg); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS thread Thread object 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. 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 rou- tine, including any nested routine invocations. Successful execution of this routine includes the following actions: o An internal thread object is created to describe and control the thread. The thread object includes a Thread Environment Block (TEB) that programs can use (with care). 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 A thread is created in the ready state to begin executing the function specified by the start_routine argument. The new thread may execute imme- diately. The newly created thread may preempt its creator, depending on scheduling policy and priority. The thread identifier (pthread_t) speci- fied in pthread_create will be written before the new thread executes. The new thread's scheduling policy and priority are, by default, inherited from the creating thread---the scheduling policy and priority set in the attributes object are ignored. To create a thread using the scheduling pol- icy and priority set in the attributes object, you must first disable the inherit scheduling attribute by calling pthread_attr_setinheritsched before calling pthread_create. The 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 Termina- tion). The caller of pthread_create can synchronize with the newly created thread through the use of the pthread_join routine, or any other mutexes or condi- tion variables they agree to use. On Digital UNIX, the signal state of the new thread is initialized as fol- lows: o The signal mask is inherited from the creating thread. o 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 An exception is raised (or re-raised) in the thread during execution, and the exception is not handled. o The thread calls the pthread_exit routine. o The thread is canceled. The following actions are performed when a thread terminates: o If the thread has been canceled, a return value of PTHREAD_CANCELED is copied into the thread object. If the thread terminated by returning from its start routine or calling pthread_exit, the return value is copied into the thread object. The return value can be retrieved by other threads by calling the pthread_join routine. If the start routine returns normally and the start routine is a pro- cedure that does not return a value, then the result obtained by pthread_join is unpredictable. o If the termination results from a cancellation, an unhandled excep- tion, or a call to pthread_exit, each cleanup handler that has been declared by pthread_cleanup_push and not yet removed by pthread_cleanup_pop is called. Cleanup handlers are called in order, starting with the most recently pushed handler. o For each thread-specific data key for which the thread has a non-NULL value, the destructor routine (if available) is called. Destructors are called in unspecified order. Before each destructor is called, the thread's value for the corresponding key is set to NULL. This step repeats until all thread-specific data values in the thread are NULL, or for up to four iterations (PTHREAD_DESTRUCTOR_ITERATIONS). o The thread waiting in a call to pthread_join, if any, is awakened. o The thread object is marked to indicate that it is no longer needed by the thread itself. A check is made to determine whether the thread is already detached. If it is detached, then the thread object is released. 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: 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 invalid. [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. ERRORS None RELATED INFORMATION Functions: pthread_atfork(3), pthread_attr_destroy(3), pthread_attr_init(3), pthread_attr_setdetachstate(3), pthread_attr_set- inheritsched(3), pthread_attr_setschedparam(3), pthread_attr_setschedpol- icy(3), pthread_attr_setstacksize(3), pthread_cancel(3), pthread_detach(3), pthread_exit(3), pthread_join(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_debug.3.gz *** pthread_debug(3) pthread_debug(3) NAME pthread_debug - Invokes the DECthreads internal debugger. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include void pthread_debug(void); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS None DESCRIPTION This routine invokes the DECthreads internal debugger as a callable func- tion. It takes no arguments and does not return a value. It enters the internal debugger parsing loop. Type exit to return to the program. To pass a list of debugging commands to DECthreads, call pthread_debug_cmd. RETURN VALUES None RELATED INFORMATION Functions: pthread_debug_cmd(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_debug_cmd.3.gz *** pthread_debug_cmd(3) pthread_debug_cmd(3) NAME pthread_debug_cmd - Passes a list of pthread_debug commands to DECthreads. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include pthreadDbgStatus_t pthread_debug_cmd( char *cmd); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS cmd NULL-terminated pthread_debug command string to pass to DEC- threads debug. Use semicolons to separate debug commands. DESCRIPTION This routine passes a list of debugging commands to DECthreads. Each com- mand (separated by a semicolon) is executed in sequence. Any output is written to standard output. This routine returns the status of the last specified operation in the command string when the final command (or Exit command) is executed. To invoke the DECthreads debugger for interactive commands, use pthread_debug. EXAMPLES The following are two examples of listing commands in a call to this rou- tine: pthread_debug_cmd("thread -b; mu -lq; cond -wq"); pthread_debug_cmd("att"); RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Command successful. [PTHREAD_DBG_QUIT] (1) Last command was quit or exit [PTHREAD_DBG_NONESEL] (2) No objects selected (for example, thread -br) [PTHREAD_DBG_SUCCESSPEND] (3) Alternate success [PTHREAD_DBG_NOPRIV] (-1) No privilege for command [PTHREAD_DBG_INVPARAM] (-2) Invalid parameter on command [PTHREAD_DBG_INVSEQ] (-3) Invalid object sequence number given [PTHREAD_DBG_INCONSTATE] (-4) Inconsistent state for operation [PTHREAD_DBG_CORRUPT] (-5) Unable to complete due to internal corruption [PTHREAD_DBG_INVOPTION] (-6) Invalid command options [PTHREAD_DBG_NOARG] (-7) Missing command argument [PTHREAD_DBG_INVADDR] (-8) Invalid address [PTHREAD_DBG_INVCMD] (-9) Invalid command [PTHREAD_DBG_NULLCMD] (-10) No command given [PTHREAD_DBG_CONFLICT] (-11) Conflicting options [PTHREAD_DBG_UNIMPL] (-12) Unimplemented feature ERRORS None RELATED INFORMATION Functions: pthread_debug(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_delay_np.3.gz *** pthread_delay_np(3) pthread_delay_np(3) NAME pthread_delay_np - Causes a thread to delay execution. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_delay_np( const struct timespec *interval); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS interval Number of seconds and nanoseconds to delay execution. The value specified for each must be greater than or equal to zero. DESCRIPTION This routine causes a thread to delay execution for a specific period of time. This period ends at the current time plus the specified interval. The routine will not return before the end of the period is reached, but may return an arbitrary amount of time after the period has gone by. This is due to system load, thread priorities, and system timer granularity. Specifying an interval of 0 seconds and 0 nanoseconds is allowed and can be used to force the thread to give up the processor or to deliver a pending cancel. The struct timespec structure contains the following two fields: o tv_sec is an integer number of seconds. o tv_nsec is an integer number of nanoseconds. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] The value specified by interval is invalid. ERRORS None RELATED INFORMATION Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_detach.3.gz *** pthread_detach(3) pthread_detach(3) NAME pthread_detach - Marks a thread object for deletion. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_detach( pthread_t thread); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS thread Thread object being marked for deletion. DESCRIPTION A call to this routine indicates that storage for the specified 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. A thread can be created "pre-detached" using its thread object's detach- state attribute. The pthread_join function also detaches the target thread when pthread_join returns successfully. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 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. ERRORS None RELATED INFORMATION Routines: pthread_cancel(3), pthread_create(3), pthread_exit(3), pthread_join(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_equal.3.gz *** pthread_equal(3) pthread_equal(3) NAME pthread_equal - Compares one thead identifier to another thread identifier. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_equal( pthread_t t1, pthread_t t2); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS t1 The first thread identifier to be compared. t2 The second thread identifier to be compared. DESCRIPTION This routine compares one thread identifier to another thread identifier. If either t1 or t2 are not valid thread IDs, the behavior is undefined. RETURN VALUES Possible return values are as follows: 0 Values of t1 and t2 do not designate the same object. Non-zero Values of t1 and t2 designate the same object. ERRORS None RELATED INFORMATION Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_exit.3.gz *** pthread_exit(3) pthread_exit(3) NAME pthread_exit - Terminates the calling thread. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include void pthread_exit( void *value_ptr); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS 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. DECthreads treats the value_ptr as a value and stores it to be returned by pthread_join. 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 cancellation 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 cancellation cleanup handlers have been executed, appropriate destructor functions shall be 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 lim- ited 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. An implicit call to pthread_exit is issued when a thread returns from the start routine that was used to create it. The function's return value serves as the thread's exit status. The process exits when the last run- ning 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 unde- fined. So, references to local variables of the existing thread should not be used for the value_ptr parameter value of the pthread_exit routine. RETURN VALUES None ERRORS None RELATED INFORMATION Functions: pthread_cancel(3), pthread_create(3), pthread_detach(3), thread_join(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_get_expiration_np.3.gz *** pthread_get_expiration_np(3) pthread_get_expiration_np(3) NAME pthread_get_expiration_np - Obtains a value representing a desired expira- tion time. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_get_expiration_np( const struct timespec *delta, struct timespec *abstime); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS 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). This value should be passed to the pthread_cond_timedwait routine. DESCRIPTION This routine adds a specified interval to the current absolute system time and returns a new absolute time. This new absolute time is used as the expiration time in a call to pthread_cond_timedwait. The struct timespec structure contains the following two fields: o tv.sec is an integer number of seconds. o tv.nsec is an integer number of nanoseconds. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] The value specified by delta is invalid. ERRORS None RELATED INFORMATION Functions: pthread_cond_timedwait(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_getschedparam.3.gz *** pthread_getschedparam(3) pthread_getschedparam(3) NAME pthread_getschedparam - Obtains the current scheduling policy and schedul- ing parameters of a thread. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_getschedparam( pthread_t thread, int *policy, struct sched_param *param); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS thread Thread whose scheduling policy and parameters are obtained. policy Receives the value of the scheduling policy for the thread speci- fied in thread. Refer to the description of the pthread_setsched- param function for valid parameters and their values. param Receives the value of the scheduling parameters for the thread specified in thread. Refer to the description of the pthread_setschedparam function for valid values. DESCRIPTION This routine obtains both the current scheduling policy and associated scheduling parameters of the thread specified by thread. The priority value returned in the param structure is the value specified in attr at pthread_create or by the most recent pthread_setschedparam call affecting the target thread. This routine differs from pthread_attr_getschedpolicy and pthread_attr_getschedparam, in that those routines get the scheduling pol- icy and parameter attributes that are used to establish the priority and scheduling policy of a new thread when it is created. This routine, how- ever, obtains the scheduling policy and parameters of an existing thread. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [ESRCH] The value specified by thread does not refer to an existing thread. ERRORS None RELATED INFORMATION Functions: pthread_create(3), pthread_self(3), pthread_attr_getschedpol- icy(3), pthread_attr_getschedparam(3), pthread_setschedparam(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_getsequence_np.3.gz *** pthread_getsequence_np(3) pthread_getsequence_np(3) NAME pthread_getsequence_np - Obtains the thread sequence number. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include unsigned long pthread_getsequence_np( pthread_t *thread); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS thread Receives the value for the thread sequence number. DESCRIPTION This routine obtains the thread sequence number, which provides a unique identifier for each concurrent thread. Thread sequence numbers are never reused while a thread exists, but may be reused after the thread termi- nates. The debugger interfaces use this sequence number to identify each thread in commands and in display output. RETURN VALUES No errors are returned. The function pthread_getsequence_np returns the sequence number of the specified thread. The result is undefined if thread is not a valid thread. ERRORS None RELATED INFORMATION Functions: pthread_create(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_getspecific.3.gz *** pthread_getspecific(3) pthread_getspecific(3) NAME pthread_getspecific - Obtains the thread-specific data associated with the specified key. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include void *pthread_getspecific( pthread_key_t key); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS key Context key identifies the thread-specific data to be obtained. This key must be obtained from pthread_key_create. DESCRIPTION This routine obtains the thread-specific data associated with the specified key for the current thread. This function 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. RETURN VALUES No errors are returned. The function pthread_getspecific returns the thread-specific data value associated with the given key. If no thread- specific data value is associated with key, or if key is not defined, then a NULL value is returned. RELATED INFORMATION Functions: pthread_key_create(3), pthread_setspecific(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_intro.3.gz *** pthread(3) pthread(3) NAME pthread, pthread_intro - Introduction to POSIX Threads (pthreads) DESCRIPTION DECthreads are a set of POSIX thread (pthread) routines that you can call to create a multithreaded program. The pthread routines are the DECthreads implementation of the IEEE Std 1003.1c-1995, POSIX System Application Pro- gram Interface. Note that POSIX Standard 1003.1c now supercedes the draft standard 1003.4a. A thread is a single, sequential flow of control within a program. Within a single thread, there is a single point of execution. Most traditional programs consist of a single thread. Using DECthreads, Digital's multithreading run-time library, a programmer can create several threads within a program. Threads execute concurrently, and, within a multithreaded program, there are at any time multiple points of execution. Threads execute within (and share) a single address space. Therefore, threads read and write the same memory locations. Synchroniza- tion elements such as mutexes and condition variables ensure that the shared memory is accessed correctly. DECthreads provides routines that allow you to create and use these synchronization elements. Mutexes and condition variables are discussed in the Guide to DECthreads. Previous pthread users should be aware that applications consistent with the P1003.4a/D4 interface require significant modifications to upgrade to the DECthreads interface that conforms to the final 1003.1c standard. Routine names ending with the _np suffix denote that the routine is not portable; the routine might not be available in other vendor implementa- tions of POSIX 1003.1c. Compile a multithreaded application using shared versions of libmach and libpthread as follows: cc -o myprog myprog.c -pthread If you use a compiler front-end or other (not C) language environment that does not support the -pthread compilation switch, you must use the -D_THREAD_SAFE compilation switch. You must link your multithreaded application using these switches: -lpthread -lmach -lexc -lc Each C module that utiltizes DECthreads exceptions must include the pthread_exception.h header file. The Guide to DECthreads describes the use of DECthreads exceptions. For more information, see the routine manpages and the Guide to DECthreads. The Guide to DECthreads describes important considerations for threaded application development, particularly for the Digital UNIX operating system. The pthread interface routines are grouped in the following functional cat- egories: o General Threads Routines o Attributes Object Routines o Condition Variable Routines o Mutex Routines o Thread-Specific Data Routines o Thread Cancelation Routines o Thread Priority and Scheduling Routines DECthreads also provides routines that implement nonportable extensions to the POSIX 1003.1c standard. These routines are grouped into these func- tional categories: o Attributes Object Routines o Debugging Support Routines o Thread-Specific Data Routines General Threads Routines pthread_atfork Declares fork handlers to be called. pthread_create Creates a thread object and thread. pthread_detach Marks a thread object for deletion. pthread_equal Compares one thread identifier to another thread identifier. pthread_exit Terminates the calling thread. pthread_join Causes the calling thread to wait for the termination of a specified thread and detach it. pthread_kill Delivers a signal to a specified thread. pthread_once Calls an initialization routine to be executed only once. pthread_self Obtains the identifier of the current thread. pthread_sigmask Examines or changes the current thread's signal mask. Attributes Object Routines pthread_attr_destroy Destroys a thread attributes object. pthread_attr_getdetachstate Obtains the detachstate attribute from the specified thread attributes object. pthread_attr_getinheritsched Obtains the inherit scheduling attribute from the specified thread attributes object. pthread_attr_getschedparam Obtains the scheduling parameters for an attribute of the specified thread attributes object. pthread_attr_getschedpolicy Obtains the scheduling policy attribute of the specified thread attributes object. pthread_attr_getstacksize Obtains the stacksize attribute of the specified thread attributes object. pthread_attr_init Initializes a thread attributes object. pthread_attr_setdetachstate Changes the detachstate attribute in the specified thread attributes object. pthread_attr_setinheritsched Changes the inherit scheduling attribute of the specified thread attributes object. pthread_attr_setschedparam Changes the values of the parameters associated with the scheduling policy attribute of the specified thread attributes object. pthread_attr_setschedpolicy Changes the scheduling policy attribute of the specified thread attributes object. pthread_attr_setstacksize Changes the stacksize attribute in the specified thread attributes object. Condition Variable Attributes Object Routines pthread_condattr_init Initializes a condition variable attributes object that spec- ifies condition variable attributes when created. pthread_condattr_destroy Destroys a condition variable attributes object. Mutex Attributes Object Routines pthread_mutexattr_init Initializes a mutex attributes object. pthread_mutexattr_destroy Destroys a mutex attributes object. Mutex Routines pthread_mutex_destroy Destroys a mutex. pthread_mutex_init Initializes a mutex with attributes specified by the attributes argument. pthread_mutex_lock Locks an unlocked mutex. If locked, the caller waits for the mutex to become available. pthread_mutex_trylock Locks an unlocked mutex or returns immediately if mutex is locked. pthread_mutex_unlock Unlocks a mutex. Condition Variable Routines pthread_cond_broadcast Wakes all threads waiting on a condition variable. pthread_cond_destroy Destroys a condition variable. pthread_cond_init Initializes a condition variable. pthread_cond_signal Wakes at least one thread that is waiting on a condition variable. pthread_cond_timedwait Causes a thread to wait for a condition variable to be sig- naled or broadcasted for a specified period of time. pthread_cond_wait Causes a thread to wait for a condition variable to be sig- naled or broadcasted. Thread-Specific Data Routines pthread_getspecific Obtains the thread-specific data associated with the speci- fied key. pthread_key_create Generates a unique thread-specific data key. pthread_setspecific Sets the thread-specific data value associated with the spec- ified key for the current thread. pthread_key_delete Deletes a thread-specific data key. Thread Cancellation Routines pthread_cancel Allows a thread to request that it, or another thread termi- nate execution. pthread_cleanup_pop Removes a cleanup handler at the top of the cleanup stack and optionally executes it. pthread_cleanup_push Establishes a cleanup handler to be executed when the thread exits or is canceled. pthread_setcancelstate Sets the current thread's cancelability state. pthread_setcanceltype Sets the current thread's cancelability type. pthread_testcancel Requests delivery of any pending cancel to the current thread. Thread Priority and Scheduling Routines pthread_getschedparam Obtains the current scheduling policy and sceduling parame- ters of a thread. pthread_getsequence_np Obtains a thread sequence number. pthread_setschedparam Changes the current scheduling policy and scheduling parame- ters of a thread. sched_yield Notifies the scheduler that the current thread will release its processor to other threads of the same or higher prior- ity. Non-Portable Extensions: Thread Attributes Routines pthread_attr_getguardsize_np Obtains the guardsize attribute of the specified thread attibutes object. pthread_attr_setguardsize_np Changes the guardsize attribute of the specified thread attributes object. Non-Portable Extensions: Thread Execution Routines pthread_delay_np Causes a thread to delay execution. pthread_getexpiration_np Obtains a value representing a desired expiration time. pthread_getsequence_np Obtains the thread sequence number. Non-Portable Extensions: Mutex Routines pthread_lock_global_np Locks the global mutex if it is unlocked. pthread_unlock_global_np Unlocks a global mutex. Non-Portable Extensions: Mutex Attributes Routines pthread_mutexattr_gettype_np Obtains the mutex type attribute used when a mutex is cre- ated. pthread_mutexattr_settype_np Specifies the mutex type attribute that is used when a mutex is created. Non-Portable Extensions: Condition Variable Routines pthread_cond_signal_int_np Wakes one thread that is waiting on a condition variable. Non-Portable Extensions: Debugging Support Routines pthread_debug Invokes the DECthreads internal debugger. pthread_debug_cmd Passes a list of commands to the DECthreads internal debug- ger. delim off delim off *** /usr/man/man3/pthread_join.3.gz *** pthread_join(3) pthread_join(3) NAME pthread_join - Causes the calling thread to wait for the termination of a specified thread. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_join( pthread_t thread, void **value_ptr); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS thread Thread whose termination is awaited by the caller of this rou- tine. value_ptr Return value of the terminating thread (when that thread calls pthread_exit or returns). DESCRIPTION This routine suspends execution of the calling thread until the specified thread terminates. A call to a pthread_join routine returns after the specified thread termi- nates. The pthread_join routine is a deferred cancellation point: the tar- get thread will not be detached if the thread blocked in pthread_join is canceled. 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 ref- erenced by value_ptr, and the terminating thread is detached. If more than one thread attempts to join with a single thread, the results are unpre- dictable. If a thread calls this routine and specifies its own pthread_t, a deadlock can result. The pthread_join (or pthread_detach) function should eventually be called for every thread that is created with the detachstate attribute of its thread attributes object set to PTHREAD_CREATE_JOINABLE, so that storage associated with the thread may be reclaimed. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 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 the value of thread specifies the calling thread. ERRORS None RELATED INFORMATION Functions: pthread_cancel(3), pthread_create(3), pthread_detach(3), pthread_exit(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_key_create.3.gz *** pthread_key_create(3) pthread_key_create(3) NAME pthread_key_create - Generates a unique thread-specific data key. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_key_create( pthread_key_t *key, void (*destructor)(void *)); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS key The new thread-specific data key. destructor Procedure called to destroy a thread-specific data value associ- ated 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. 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 may 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. Thread-specific data allows client software to associate "static" informa- tion 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 vari- able. 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 may 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 the process is repeated. If there are still non-NULL values for any key with a destructor after four repeti- tions of this process, DECthreads will terminate the thread. 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. Destructor code should attempt to avoid this sort of circularity. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EAGAIN] The system lacked the necessary resources to create another thread-specific data key, or the system-imposed limit on the total number of keys per process (that is, PTHREAD_KEYS_MAX) has been exceeded. [ENOMEM] Insufficient memory exists to create the key. ERRORS None RELATED INFORMATION Functions: pthread_getspecific(3), pthread_setspecific(3), pthread_key_delete(3), pthread_once(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_key_delete.3.gz *** pthread_key_delete(3) pthread_key_delete(3) NAME pthread_key_delete - Deletes a thread-specific data key. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_key_delete( pthread_key_t key); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS key Context key to be deleted. DESCRIPTION This routine deletes a thread-specific data key that was 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 applica- tion must free any application storage or perform any cleanup actions for data structures related to the the deleted key or associated thread-spe- cific data in any threads. This cleanup can be done before or after this routine call. Do not attempt to use the key after calling this routine, because this results in unpredictable behavior. No destructor functions are invoked by this routine. Any destructor func- tions 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. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] The key value is an invalid argument. ERRORS None RELATED INFORMATION Functions: pthread_getspecific(3), pthread_key_create(3), pthread_exit(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_kill.3.gz *** pthread_kill(3) pthread_kill(3) NAME pthread_kill - Delivers a signal to a specified thread. (This routine is for Digital UNIX systems only.) LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_kill( pthread_t thread, int sig); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS thread Thread to receive a signal request. sig A signal request. If sig is zero, error checking is performed, but no signal is sent. DESCRIPTION This routine sends a signal to the specified thread. Any signal defined to stop, continue, or terminate will stop or terminate the process, even though it may be handled by the thread. For example, SIGTERM terminates all threads in the process, even though it may be handled by the thread to which it is sent. The name of the "kill" routine is sometimes misleading, because many signals do not terminate a thread. The various signals are as follows: o SIGHUP, SIGPIPE, SIGTTIN o SIGINT, SIGALRM, SIGTTOU o SIGQUIT, SIGTERM, SIGIO o SIGTRAP, SIGUSR1, SIGXCPU o SIGABRT, SIGSYS, SIGXFSZ o SIGEMT, SIGURG, SIGVTALRM o SIGFPE, SIGSTOP, SIGPROF o SIGKILL, SIGTSTP, SIGINFO o SIGBUS, SIGCONT, SIGUSR1 o SIGSEGV, SIGCHLD, SIGUSR2 If this routine does not execute successfully, no signal is sent. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] The value of sig is invalid or unsupported signal value. [ESRCH] The value of thread does not specify an existing thread. ERRORS None RELATED INFORMATION Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_lock_global_np.3.gz *** pthread_lock_global_np(3) pthread_lock_global_np(3) NAME pthread_lock_global_np - Locks the global mutex if it is unlocked. If the global mutex is locked by another thread, causes the thread to wait for the global mutex to become available. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_lock_global_np(void); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS None DESCRIPTION This routine locks the global mutex. If the global mutex is currently held by another thread when a thread calls this routine, the thread waits for the global mutex to become available. 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 uses the same lock. This prevents problems resulting from dependencies among threads that call library functions and those func- tions' 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. (To allow another thread to lock the global mutex, the locking thread must call pthread_unlock_global_np as many times as it called this routine.) RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. ERRORS None RELATED INFORMATION Functions: pthread_unlock_global_np(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_mutex_destroy.3.gz *** pthread_mutex_destroy(3) pthread_mutex_destroy(3) NAME pthread_mutex_destroy - Destroys a mutex. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_mutex_destroy( pthread_mutex_t *mutex); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS mutex The mutex to be destroyed. DESCRIPTION This routine destroys a mutex by uninitializing it, and should be called when a mutex object is no longer referenced. This routine may reclaim internal storage used by the mutex object. 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. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EBUSY] An attempt is made to destroy the object referenced by mutex while it is locked or referenced. [EINVAL] The value specified for mutex is invalid. ERRORS None RELATED INFORMATION Functions: pthread_mutex_init(3), pthread_mutex_lock(3), pthread_mutex_try- lock(3), pthread_mutex_unlock(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_mutex_init.3.gz *** pthread_mutex_init(3) pthread_mutex_init(3) NAME pthread_mutex_init - Initializes a mutex with attributes specified by the attr argument. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_mutex_init( pthread_mutex_t *mutex, const pthread_mutexattr_t *attr); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS mutex Mutex created. attr Mutex attributes object to be used in initializing the character- istics of the created mutex. DESCRIPTION This routine initializes a mutex with the attributes specified by 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_set- type_np routine can be used to specify the type of mutex that is created (normal, recursive, or errorcheck). 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. Because mutexes are shared, they may be allocated in heap or static memory but not on a stack. The PTHREAD_MUTEX_INITIALIZER macro can be used 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. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error, the mutex is not initialized, and the contents of mutex are undefined. Possible return values are as follows: 0 Successful completion. [EAGAIN] The system lacks the necessary resources to initialize a mutex. [ENOMEM] Insufficient memory exists 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 invalid. [EPERM] The caller does not have privileges to perform the operation. ERRORS None RELATED INFORMATION Functions: pthread_mutexattr_init(3), pthread_mutexattr_gettype_np(3), pthread_mutexattr_settype_np(3), pthread_mutex_lock(3), pthread_mutex_try- lock(3), pthread_mutex_unlock(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_mutex_lock.3.gz *** pthread_mutex_lock(3) pthread_mutex_lock(3) NAME pthread_mutex_lock - Locks an unlocked mutex. If the mutex is already locked, the calling thread blocks until the mutex becomes available. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_mutex_lock( pthread_mutex_t *mutex); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS mutex Mutex to be locked. DESCRIPTION This routine locks a mutex with varying behavior as follows: o If a recursive mutex was specified, the current owner of a mutex can relock the same mutex without blocking. The lock count is incremented for each recursive lock within the thread. o If an error-check mutex was specified and the current owner tries to lock the mutex a second time, the EDEADLK error is reported. If the mutex is locked by another thread, the calling thread waits for the mutex to become available. o If a normal mutex is specified, a deadlock can result if the current owner of a mutex calls this routine in an attempt to lock the mutex a second time. (The deadlock is not detected or reported.) See pthread_mutexattr_settype_np for information about normal, recursive, and error-check mutexes. The thread that has locked a mutex becomes its current owner and remains the owner until the same thread has unlocked it. This routine returns with the mutex in the locked state and with the current thread as the mutex's current owner. A recursive or error-check mutex records the identity of the thread that locks it, allowing debuggers to display this information. In most cases, normal mutexes do not record the thread identity. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] The value specified for mutex is invalid, or The mutex was created with the protocol attribute set to PTHREAD_PRIO_PROTECT and the calling thread's priority set higher than the mutex's current priority ceiling.) [EDEADLK] A deadlock condition is detected. ERRORS None RELATED INFORMATION Functions: pthread_mutexattr_settype_np(3), pthread_mutex_destroy(3), pthread_mutex_init(3), pthread_mutex_trylock(3), pthread_mutex_unlock(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_mutex_trylock.3.gz *** pthread_mutex_trylock(3) pthread_mutex_trylock(3) NAME pthread_mutex_trylock - Tries to lock a mutex. If the mutex is already locked, the calling thread does not wait for the mutex to become available. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_mutex_trylock( pthread_mutex_t *mutex); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS mutex Mutex to be locked. DESCRIPTION This routine tries to lock a mutex. When a thread calls this routine, an attempt is made to immediately lock the mutex. If the mutex is successfully locked, 0 is returned and the current thread is then 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 If a recursive mutex is owned by the current thread, a zero is returned and the mutex lock count is incremented. (To unlock a recur- sive mutex, each call to pthread_mutex_trylock must be matched by a call to pthread_mutex_unlock.) o If a normal or error-check mutex is locked by any thread (including the current thread) when this routine is called, EBUSY is returned and the thread does not wait to acquire the lock. o If a normal or error-check mutex is not owned, a zero is returned and the mutex becomes locked. Use the pthread_mutexattr_settype_np routine to set the mutex type attribute (normal, recursive, or error-check). RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EBUSY] The mutex is already locked; therefore, it was not acquired. [EINVAL] The value specified by mutex is invalid, or The mutex was created with the protocol attribute set to PTHREAD_PRIO_PROTECT and the calling thread's priority set higher than the mutex's current priority ceiling. ERRORS None RELATED INFORMATION Functions: pthread_mutexattr_settype_np(3), pthread_mutex_destroy(3), pthread_mutex_init(3), pthread_mutex_lock(3), pthread_mutex_unlock(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_mutex_unlock.3.gz *** pthread_mutex_unlock(3) pthread_mutex_unlock(3) NAME pthread_mutex_unlock - Unlocks a mutex. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_mutex_unlock( pthread_mutex_t *mutex); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS mutex Mutex to be unlocked. DESCRIPTION This routine unlocks a mutex. The following describes the varied behavior of this routine: o When an owner unlocks a recursive mutex that it owns, the lock count is decremented. The mutex remains locked and owned until the count reaches 0. When the lock count reaches 0, or for any other type of mutex, the mutex becomes unlocked with no current owner. o If a normal or error-check mutex is owned by the current thread, it is unlocked. o If an error-check mutex is not locked or is locked by another thread, EPERM is returned. A normal mutex may also return EPERM, but this is not guaranteed. 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 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 priori- ties. Note that the mutex may not be acquired by the awakened thread if any other running thread attempts to lock the mutex first. On Digital UNIX systems, 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. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] The value specified for mutex is invalid. [EPERM] The calling thread does not own the mutex. ERRORS None RELATED INFORMATION Functions: pthread_mutexattr_settype_np(3), pthread_mutex_destroy(3), pthread_mutex_init(3), pthread_mutex_lock(3), pthread_mutex_trylock(3), pthread_unlock_global_np(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_mutexattr_destroy.3.gz *** pthread_mutexattr_destroy(3) pthread_mutexattr_destroy(3) NAME pthread_mutexattr_destroy - Destroys a mutex attributes object. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_mutexattr_destroy( pthread_mutexattr_t *attr); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS attr Attributes object to be destroyed. DESCRIPTION This routine destroys a mutex attributes object (that is, the object becomes uninitialized). Call this routine when a mutex attributes object is no longer needed. This routine gives permission to reclaim storage for 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. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] The object value specified by attr is invalid. ERRORS None RELATED INFORMATION Functions: pthread_mutexattr_init(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_mutexattr_gettype_np.3.gz *** pthread_mutexattr_gettype_np(3) pthread_mutexattr_gettype_np(3) NAME pthread_mutexattr_gettype_np - Obtains the mutex type attribute used when a mutex is created. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_mutexattr_gettype_np( const pthread_mutexattr_t *attr, int *type); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS attr Mutex attributes object whose mutex type is obtained. type Receives the value of the mutex type attribute. The type argu- ment specifies the type of mutex that is created. Valid values are: o PTHREAD_MUTEX_NORMAL_NP (default) o PTHREAD_MUTEX_RECURSIVE_NP o PTHREAD_MUTEX_ERRORCHECK_NP DESCRIPTION This routine obtains the mutex type attribute that is used when a mutex is created. See the pthread_mutexattr_settype_np description for information about mutex type attributes. RETURN VALUES On successful completion, this routine returns the mutex type in type. If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] The value specified by attr is invalid. ERRORS None RELATED INFORMATION Functions: pthread_mutexattr_init(3), pthread_mutexattr_settype_np(3), pthread_mutex_init(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_mutexattr_init.3.gz *** pthread_mutexattr_init(3) pthread_mutexattr_init(3) NAME pthread_mutexattr_init - Initializes a mutex attributes object that is used to specify the attributes of mutexes when they are created. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_mutexattr_init( pthread_mutexattr_t *attr); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS attr Mutex attributes object to be initialized. DESCRIPTION This routine initializes a mutex attributes object (attr) used to specify the attributes of mutexes when they are created. The mutex attributes object is initialized with the default value for all of the attributes defined by DECthreads. When a mutex attributes object is used to initialize a mutex, the values of the individual attributes determine the characteristics of the new object. Attributes objects act like additional arguments to object creation. Changing individual attributes or destroying the attributes object does not affect any objects that were previously created using the attributes object. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [ENOMEM] Insufficient memory while attempting to create the mutex attributes object. ERRORS None RELATED INFORMATION Functions: pthread_create(3), pthread_mutexattr_gettype_np(3), pthread_mutexattr_settype_np(3), pthread_mutex_init(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_mutexattr_settype_np.3.gz *** pthread_mutexattr_settype_np(3) pthread_mutexattr_settype_np(3) NAME pthread_mutexattr_settype_np - Specifies the mutex type attribute that is used when a mutex is created. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_mutexattr_settype_np( pthread_mutexattr_t *attr, int type); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS attr Mutex attributes object whose mutex type attribute is modified. type New value for the mutex type attribute. The type argument speci- fies the type of mutex that is created. Valid values are: o PTHREAD_MUTEX_NORMAL_NP (default) o PTHREAD_MUTEX_RECURSIVE_NP o PTHREAD_MUTEX_ERRORCHECK_NP DESCRIPTION This routine sets the mutex type attribute that is used to determine which type of mutex is created on a call to pthread_mutex_init. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] The value specified for attr or type is invalid. [ESRCH] The value specified by attr does not refer to an existing mutex attributes object. ERRORS None RELATED INFORMATION Functions: pthread_mutexattr_init(3), pthread_mutexattr_gettype_np(3), pthread_mutex_init(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_once.3.gz *** pthread_once(3) pthread_once(3) NAME pthread_once - Calls an initialization routine that can be executed by a single thread, once. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_once( pthread_once_t *once_control, void (*init_routine)(void)); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS once_control Address of a record that defines the one-time initialization code. Each one-time initialization routine must have its own unique pthread_once_t record. init_routine Address of a procedure that performs the initialization. This routine is called only once, regardless of the number of times it and its associated once_control are passed to pthread_once. DESCRIPTION The first call to this routine by any thread in a process with a given once_control will call the init_routine with no arguments. Subsequent calls to pthread_once with the same once_control will not call the init_routine. On return from pthread_once, it is guaranteed that the ini- tialization 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. The pthread_once_t variable must be statically initialized using the PTHREAD_ONCE_INIT macro or by zeroing out the entire structure. Note If you specify an init_routine that directly or indirectly results in a recursive call to pthread_once specifying the same init_block argu- ment, the recursive call may result in a deadlock. The PTHREAD_ONCE_INIT macro, defined in the header file, must be used to initialize a once_control record. A once_control record must be declared 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, code an init routine beginning with the following basic logic: init() { static pthread_mutex_t mutex = PTHREAD_MUTEX_INIT; static int flag = FALSE; pthread_mutex_lock(&mutex); if(!flag) { flag = TRUE; /* initialize code */ } pthread_mutex_unlock(&mutex); } RETURN VALUES If an error condition occurs, this routine returns an integer indicating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] Invalid argument. ERRORS None RELATED INFORMATION Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_self.3.gz *** pthread_self(3) pthread_self(3) NAME pthread_self - Obtains the identifier of the current thread. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include pthread_t pthread_self(void); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS None DESCRIPTION This routine allows a thread to obtain its own thread identifier. This value becomes meaningless when the thread is deleted. RETURN VALUES Returns the identifier of the calling thread. ERRORS None RELATED INFORMATION Functions: pthread_cancel(3), pthread_create(3), pthread_detach(3), pthread_exit(3), pthread_join(3), pthread_kill(3), pthread_sigmask(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_setcancelstate.3.gz *** pthread_setcancelstate(3) pthread_setcancelstate(3) NAME pthread_setcancelstate - Sets the thread's cancelability state. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_setcancelstate( int state, int *oldstate); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS state State of general cancelability to set for the calling thread. The following are valid cancel state values: o PTHREAD_CANCEL_ENABLE o PTHREAD_CANCEL_DISABLE oldstate Previous cancelability state. DESCRIPTION This routine sets the current thread's cancelability state and returns the previous cancelability state in oldstate. When cancelability state is set to PTHREAD_CANCEL_DISABLE, a cancel cannot be delivered to the thread, even if a cancelable routine is called or asyn- chronous cancelability type is enabled. When a thread is created, the default general cancelability state is PTHREAD_CANCEL_ENABLE. Possible Problems When Disabling Cancelability The most important use of cancel calls is to ensure that indefinite wait operations are terminated. For example, a thread waiting on some network connection, which may take days to respond (or may never respond), should be made cancelable. When cancelability is disabled, no routine is cancelable. As a result, the user is unable to cancel the operation. When disabling cancelability, be sure that no long waits can occur or that it is necessary for other reasons to defer cancels around that particular region of code. RETURN VALUES On successful completion, this routine returns the previous state of gen- eral cancelability in oldstate. If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] The specified state is not PTHREAD_CANCEL_ENABLE or PTHREAD_CAN- CEL_DISABLE. ERRORS None RELATED INFORMATION Functions: pthread_cancel(3), pthread_setcanceltype(3), pthread_testcan- cel(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_setcanceltype.3.gz *** pthread_setcanceltype(3) pthread_setcanceltype(3) NAME pthread_setcanceltype - Sets the current thread's cancelability type. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_setcanceltype( int type, int *oldtype); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS type The cancelability type to set for the calling thread. The fol- lowing are valid values: o PTHREAD_CANCEL_DEFERRED o PTHREAD_CANCEL_ASYNCHRONOUS oldtype The previous cancelability type. DESCRIPTION This routine sets the cancelability type and returns the previous type in oldtype. When the cancelability state is set to PTHREAD_CANCEL_DISABLE, (see pthread_setcancelstate), a cancel cannot be delivered to the 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. When the thread's cancelabil- ity state is PTHREAD_CANCEL_ENABLE and the thread's cancelability type is set to PTHREAD_CANCEL_DEFERRED, the thread can only receive a cancel at specific cancellation points (including condition waits, thread joins, and calls to pthread_testcancel.) If the thread's cancelability state is PTHREAD_CANCEL_ENABLE and its cancelability type is PTHREAD_CANCEL_ASYN- CHRONOUS, the thread can be canceled at any point in its execution. When a thread is created, the default cancelability type is PTHREAD_CAN- CEL_DEFERRED. Warning If the asynchronous cancelability type is set, do not call any routine unless it is explicitly documented as safe to be called with the asynchronous cancelability type. Note that none of the general run- time libraries and none of the DECthreads libraries are safe except for pthread_setcanceltype, pthread_setcancelstate, and cma_alert_restore. The asynchronous cancelability type should only be used when you have a compute-bound section of code that carries no state and makes no routine calls. 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 indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] The specified type is not PTHREAD_CANCEL_DEFERRED or PTHREAD_CAN- CEL_ASYNCHRONOUS. ERRORS None RELATED INFORMATION Functions: pthread_cancel(3), pthread_setcancelstate(3), pthread_testcan- cel(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_setschedparam.3.gz *** pthread_setschedparam(3) pthread_setschedparam(3) NAME pthread_setschedparam - Changes the current scheduling policy and schedul- ing parameters of a thread. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_setschedparam( pthread_t thread, int policy, const struct sched_param *param); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS 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: o SCHED_BG_NP o SCHED_FG_NP o SCHED_FIFO o SCHED_OTHER o SCHED_RR See Guide to DECthreads for a description of the scheduling policies. param New values of the scheduling parameters associated with the scheduling policy for the thread specified in thread. Valid val- ues for the sched_priority field of struct sched_param depend on the chosen policy and fall within one of the following ranges: o PRI_FIFO_MIN (low) to PRI_FIFO_MAX (high) o PRI_RR_MIN (low) to PRI_RR_MAX (high) o PRI_OTHER_MIN (low) to PRI_OTHER_MAX (high) o PRI_FG_MIN_NP (low) to PRI_FG_MAX_NP (high) o PRI_BG_MIN_NP (low) to PRI_BG_MAX_NP (high) Calculate the priority using the appropriate symbols, such as PRI_FIFO_MIN or PRI_FIFO_MAX. Avoid using numeric constants as priorities. 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 DECthreads scheduling policies have one schedul- ing parameter called sched_priority. You must specify an appropriate sched_priority parameter for the policy you choose. Changing the scheduling policy or priority, or both, of a thread can cause it 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 pthread_self. This routine differs from pthread_attr_setschedpolicy and pthread_attr_setschedparam, in that those routines set the scheduling pol- icy and parameter attributes that are used to establish the priority and scheduling policy of a new thread when it is created. This routine, how- ever, changes the scheduling policy and parameters of an existing thread. 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: 0 Successful completion. [EINVAL] The value specified by policy or param is invalid. [ENOTSUP] An attempt is 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. ERRORS None RELATED INFORMATION Functions: pthread_create(3), pthread_getschedparam(3), pthread_self(3), pthread_attr_setschedpolicy(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_setspecific.3.gz *** pthread_setspecific(3) pthread_setspecific(3) NAME pthread_setspecific - Sets the thread-specific data value associated with the specified key for the current thread. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_setspecific( pthread_key_t key, const void *value); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS 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 current thread. DESCRIPTION This routine sets the thread-specific data value associated with the speci- fied 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 an address, the type is being used as a "universal scalar type". DECthreads does nothing with value other than store it for later retrieval. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] The specified key is invalid. [ENOMEM] Insufficient memory exists to associate the value with the key. ERRORS None RELATED INFORMATION Functions: pthread_getspecific(3), pthread_key_create(3), pthread_key_delete(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_sigmask.3.gz *** pthread_sigmask(3) pthread_sigmask(3) NAME pthread_sigmask - Examine or change the current thread's signal mask. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_sigmask( int how, const sigset_t *set, sigset_t *oset); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS how Indicates the manner in which the set of masked signals is changed. The optional values are as follows: SIG_BLOCK The resulting set is the union of the current set and the signal set pointed to by the set argument.) SIG_UNBLOCK The resulting set is the intersection of the current set and the complement of the signal set pointed to by the set argu- ment. SIG_SETMASK The resulting set is the signal set pointed to by the set argument. set Specifies the signal set by pointing to a set of signals used to change the blocked set. If this set value is NULL, the how argu- ment is ignored and the process signal mask is unchanged. oset Receives the value of the current signal mask (unless this value is NULL). DESCRIPTION This routine is for Digital UNIX systems only. This routine examines or changes the calling thread's signal mask. Typi- cally, you use the SIG_BLOCK option for the how value to block signals dur- ing a critical section of code, and then use the SIG_SETMASK option of this routine to restore the mask to the previous value returned by the previous call to the pthread_sigmask function. If there are any unblocked signals pending after a call to this routine, at least one of those signals will be delivered before this routine returns. This routine does not allow the SIGKILL or SIGSTOP signals to be blocked. If a program attempts to block one of these signals, pthread_sigmask gives no indication of the error. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] The value specified for how is invalid. ERRORS None RELATED INFORMATION Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_testcancel.3.gz *** pthread_testcancel(3) pthread_testcancel(3) NAME pthread_testcancel - Requests delivery of any pending cancel to the current thread. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include void pthread_testcancel(void); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS None DESCRIPTION This routine requests delivery of a pending cancel to the current thread. The cancel is delivered only if a cancel is pending for the current thread and the cancelability state is enabled. (A thread disables delivery of cancels to itself by calling pthread_setcancelstate.) This routine, when called within very long loops, ensures that a pending cancel is noticed within a reasonable amount of time. RETURN VALUES None RELATED INFORMATION Functions: pthread_setcancelstate(3) Manuals: Guide to DECthreads and Programmer's Guide delim off *** /usr/man/man3/pthread_unlock_global_np.3.gz *** pthread_unlock_global_np(3) pthread_unlock_global_np(3) NAME pthread_unlock_global_np - Unlocks a global mutex. LIBRARY DECthreads POSIX 1003.1c Library (libpthread.so) SYNOPSIS #include int pthread_unlock_global_np(void); STANDARDS Interfaces documented on this reference page conform to industry standards as follows: IEEE Std 1003.1c-1995, POSIX System Application Program Interface PARAMETERS None DESCRIPTION This routine unlocks the global mutex. Since the global mutex is recur- sive, the unlock will occur 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 try to acquire the mutex. The scheduling policy is used to determine which thread is awak- ened. For the policies SCHED_FIFO and SCHED_RR, a blocked thread is chosen in priority order, using first-in/first-out within priorities. RETURN VALUES If an error condition occurs, this routine returns an integer value indi- cating the type of error. Possible return values are as follows: 0 Successful completion. [EPERM] The mutex is unlocked or owned by another thread. ERRORS None RELATED INFORMATION Functions: pthread_lock_global_np(3) Manuals: Guide to DECthreads and Programmer's Guide delim off