pthread_condattr_setpshared() — Set the process-shared condition variable attribute

Standards

Standards / Extensions	C or C++	Dependencies
Language Environment Extension Single UNIX Specification, Version 3	both	z/OS® V1R2

Format

#define _OPEN_THREADS
#define _OPEN_SYS_MUTEX_EXT
#include <pthread.h>

int  pthread_condattr_setpshared(pthread_condattr_t *attr,
                                 int pshared);

SUSV3:

#define _UNIX03_THREADS
#define _OPEN_SYS_MUTEX_EXT
#include <pthread.h>

int  pthread_condattr_setpshared(pthread_condattr_t *attr,
                                 int pshared);

General description

Sets the attribute pshared for the condition variable attribute object attr.

A condition variable attribute object (attr) allows you to manage the characteristics of condition variables in your application by defining a set of values to be used for a condition variable during its creation. By establishing a condition variable attribute object, you can create many condition variables with the same set of characteristics, without needing to define the characteristics for each and every condition variable. By using attr, you can define its process-shared value for a condition variable.

Valid values for the attribute pshared are:

Value: Description
PTHREAD_PROCESS_SHARED: Permits a condition variable to be operated upon by any thread that has access to the memory where the condition variable is allocated; even if the condition variable is allocated in memory that is shared by multiple processes.
PTHREAD_PROCESS_PRIVATE: A condition variable can only be operated upon by threads created within the same process as the thread that initialized the condition variable. If threads of differing processes attempt to operate on such a condition variable, only the process to initialize the condition variable will succeed. When a new process is created by the parent process it will receive a different copy of the private condition variable which can only be used to serialize between threads in the child process.
Note: This is the default value of pshared.

Returned value

If successful, 0 is returned. If unsuccessful, -1 is returned and the errno value is set. The following is the value of errno:

Value: Description
EINVAL: The value specified for attr is not valid.

Special behavior for Single UNIX Specification, Version 3: If unsuccessful, pthread_condattr_setpshared() returns an error number to indicate the error.

Usage notes

It is recommended that you define and initialize pthread_cond_t objects in the same compile unit. If you pass a pthread_cond_t object around to be initialized, make sure the initialization code has been compiled with the same _OPEN_SYS_MUTEX_EXT feature setting as the code that defines the object.

The following sequence may cause storage overlay with unpredictable results:

Declare or define a pthread_cond_t object (in shared storage) without #define of the _OPEN_SYS_MUTEX_EXT feature. The created pthread_cond_t object is standard size (i.e. small) without the _OPEN_SYS_MUTEX_EXT feature defined.
Pass the pthread_cond_t object to another code unit, which was compiled with the _OPEN_SYS_MUTEX_EXT feature defined, to be initialized as a shared object. The pthread_cond_t initialization generally involves the following steps:
1. pthread_condattr_init()
2. pthread_condattr_setpshared(). This step sets the attribute of the pthread_cond_t as PTHREAD_PROCESS_SHARED and designates the object to be of extended size.
3. pthread_cond_init(). This step initializes the passed-in (small) pthread_cond_t object as if it is an extended object, causing storage overlay.