Guide to DECthreads

The global errno variable is not used by these routines. To indicate errors, the pthread routines return integer values indicating the type of error.

Routine names with the _np suffix denote that the routine is not portable, with respect to the POSIX.1c standard. That is, the routine might not be available in implementations of POSIX.1c other than DECthreads.

pthread_atfork

Declares handlers to be called when the process forks a child.
This routine is for Digital UNIX systems only.

Syntax

pthread_atfork(
prepare ,
parent ,
child );

Argument Data Type Access

prepare Handler read

parent Handler read

child Handler read

Argument	Data Type	Access
prepare	Handler	read
parent	Handler	read
child	Handler	read

C Binding #include <pthread.h>

int
pthread_atfork (
void (*prepare)(void),
void (*parent)(void),
void (*child)(void) );

ARGUMENTS

prepare
Address of a procedure that performs the fork preparation handling. This routine is called in the parent process before creating 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 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) execution 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.

Note
It is not legal to call pthread_atfork() from within a handler routine. Doing so could cause a deadlock.

Mutex locks might be held by threads that no longer exist in a child process 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. For example, if your library uses the mutex my_mutex, you might provide 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(); 
    } 

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

Return	Description
0	Successful completion.
[ENOMEM]	Insufficient table space exists to record the fork handler addresses.

Associated Routines

pthread_create()

pthread_attr_destroy

Destroys a thread attributes object.

Syntax

pthread_attr_destroy(
attr );

Argument Data Type Access

attr opaque pthread_attr_t modify

Argument	Data Type	Access
attr	opaque pthread_attr_t	modify

C Binding #include <pthread.h>

int
pthread_attr_destroy (
pthread_attr_t *attr);

ARGUMENTS

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 specified 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 indicating the type of error. Possible return values are as follows:

Return	Description
0	Successful completion.
[EINVAL]	The value specified by attr is invalid.

Associated Routines

pthread_attr_init()
pthread_create()

pthread_attr_getdetachstate

Obtains the detachstate attribute of the specified thread attributes object.

Syntax

pthread_attr_getdetachstate(
attr ,
detachstate );

Argument Data Type Access

attr opaque pthread_attr_t read

detachstate integer write

Argument	Data Type	Access
attr	opaque pthread_attr_t	read
detachstate	integer	write

C Binding #include <pthread.h>

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

ARGUMENTS

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 specified thread attributes object are created in a detached state.
On successful completion, this routine returns a zero and the detachstate attribute is set in detachstate. A value of PTHREAD_CREATE_JOINABLE indicates the thread is not detached, and a value of PTHREAD_CREATE_DETACHED indicates the thread is detached.
See the pthread_attr_setdetachstate() description for information about the detachstate attribute.

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

Return Description

0 Successful completion.

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

Associated Routines

pthread_attr_init()
pthread_attr_setdetachstate()

pthread_attr_getguardsize_np

Obtains the guardsize attribute of the specified thread attributes object.

Syntax

pthread_attr_getguardsize_np(
attr ,
guardsize );

Argument Data Type Access

attr opaque pthread_attr_t read

guardsize size_t write

Argument	Data Type	Access
attr	opaque pthread_attr_t	read
guardsize	size_t	write

C Binding #include <pthread.h>

int
pthread_attr_getguardsize_np (
const pthread_attr_t *attr
size_t *guardsize);

ARGUMENTS

attr
Thread attributes object whose guardsize attribute is obtained.
guardsize
Receives the value for 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 indicating the type of error. Possible return values are as follows:

Return	Description
0	Successful completion.
[EINVAL]	The value specified by attr is invalid.

Associated Routines

pthread_attr_init()
pthread_attr_setstacksize()
pthread_attr_setguardsize_np()
pthread_create()

pthread_attr_getinheritsched

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

Syntax

pthread_attr_getinheritsched(
attr ,
inheritsched );

Argument Data Type Access

attr opaque pthread_attr_t read

inheritsched integer write

Argument	Data Type	Access
attr	opaque pthread_attr_t	read
inheritsched	integer	write

C Binding #include <pthread.h>

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

ARGUMENTS

attr
Thread attributes object whose inherit scheduling attribute is obtained.
inheritsched
Receives the value of the inherit scheduling attribute. Refer to the description of the pthread_attr_setinheritsched() function for valid values.

DESCRIPTION

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

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

Return	Description
0	Successful completion.
[EINVAL]	The value specified by attr is invalid.

Associated Routines

pthread_attr_init()
pthread_attr_setinheritsched()
pthread_create()

pthread_attr_getschedparam

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

Syntax

pthread_attr_getschedparam(
attr ,
param );

Argument Data Type Access

attr opaque pthread_attr_t read

param struct sched_param write

Argument	Data Type	Access
attr	opaque pthread_attr_t	read
param	struct sched_param	write

C Binding #include <pthread.h>

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

ARGUMENTS

attr
Thread attributes object of the scheduling policy attribute whose parameters are obtained.
param
Receives the values of scheduling parameters for the scheduling policy attribute of the attributes object specified by the attr argument. Refer to the description of the pthread_attr_setschedparam() function for valid parameters and their values.

DESCRIPTION

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

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

Return	Description
0	Successful completion.
[EINVAL]	The value specified by attr is invalid.

Associated Routines

pthread_attr_init()
pthread_attr_setschedparam()
pthread_create()

pthread_attr_getschedpolicy

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

Syntax

pthread_attr_getschedpolicy(
attr ,
policy );

Argument Data Type Access

attr opaque pthread_attr_t read

policy integer write

Argument	Data Type	Access
attr	opaque pthread_attr_t	read
policy	integer	write

C Binding #include <pthread.h>

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

ARGUMENTS

attr
Thread attributes object whose scheduling policy attribute is obtained.
policy
Receives the value of the scheduling policy attribute. Refer to the description of the pthread_attr_setschedpolicy() 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 indicating the type of error. Possible return values are as follows:

Return	Description
0	Successful completion.
[EINVAL]	The value specified by attr is invalid.

Associated Routines

pthread_attr_init()
pthread_attr_setschedpolicy()
pthread_create()

pthread_attr_getstacksize

Obtains the stacksize attribute of the specified thread attributes object.

Syntax

pthread_attr_getstacksize(
attr ,
stacksize );

Argument Data Type Access

attr opaque pthread_attr_t read

stacksize size_t write

Argument	Data Type	Access
attr	opaque pthread_attr_t	read
stacksize	size_t	write

C Binding #include <pthread.h>

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

ARGUMENTS

attr
Thread attributes object whose stacksize attribute is obtained.
stacksize
Receives the value for the stacksize attribute.

DESCRIPTION

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

Return Values On successful completion, this routine returns a zero (0) and the stacksize value in the stacksize variable.

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

Return Description

0 Successful completion.

EINVAL The value specified by attr is invalid.

Associated Routines

pthread_attr_init()
pthread_attr_setstacksize()
pthread_create()

pthread_attr_init

Initializes a thread attributes object.

Syntax

pthread_attr_init(
attr );

Argument Data Type Access

attr opaque pthread_attr_t write

Argument	Data Type	Access
attr	opaque pthread_attr_t	write

C Binding #include <pthread.h>

int
pthread_attr_init (
pthread_attr_t *attr);

ARGUMENTS

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 created by this routine is used only in calls to pthread_create().
The following routines change the initialized individual attributes of a thread attributes object:

pthread_attr_setdetachstate()
pthread_attr_setguardsize_np()
pthread_attr_setinheritsched()
pthread_attr_setschedparam()
pthread_attr_setschedpolicy()
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 thread attribute setting 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 created 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, specifying 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:

Return	Description
0	Successful completion.
[EINVAL]	The value specified by attr is invalid.
[ENOMEM]	Insufficient memory exists to initialize the thread attributes object.

Associated Routines

pthread_attr_destroy()
pthread_attr_setdetachstate()
pthread_attr_setguardsize_np()
pthread_attr_setinheritsched()
pthread_attr_setschedparam()
pthread_attr_setschedpolicy()
pthread_attr_setstacksize()
pthread_create()

pthread_attr_setdetachstate

Changes the detachstate attribute in the specified thread attributes object.

Syntax

pthread_attr_setdetachstate(
attr ,
detachstate );

Argument Data Type Access

attr opaque pthread_attr_t write

detachstate integer read

Argument	Data Type	Access
attr	opaque pthread_attr_t	write
detachstate	integer	read

C Binding #include <pthread.h>

int
pthread_attr_setdetachstate (
pthread_attr_t *attr,
int detachstate);

ARGUMENTS

attr
Thread attributes object to be modified.
detachstate
New value for the detachstate attribute. Valid values are as follows:

PTHREAD_CREATE_JOINABLE This is the default value. Threads are created in "undetached" 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 THREAD_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 indicating the type of error. Possible return values are as follows:

Return	Description
0	Successful completion.
[EINVAL]	The value specified by the detachstate argument is invalid.

Associated Routines

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

pthread_attr_setguardsize_np

Changes the guardsize attribute of the specified thread attributes object.

Syntax

pthread_attr_setguardsize_np(
attr ,
guardsize );

Argument Data Type Access

attr opaque pthread_attr_t write

guardsize size_t read

Argument	Data Type	Access
attr	opaque pthread_attr_t	write
guardsize	size_t	read

C Binding #include <pthread.h>

int
pthread_attr_setguardsize_np (
pthread_attr_t *attr,
size_t guardsize);

ARGUMENTS

attr
Threads 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 indicating the type of error. Possible return values are as follows:

Return	Description
0	Successful completion.
[EINVAL]	The value specified by attr is invalid.

Associated Routines

pthread_attr_init()
pthread_attr_getguardsize_np()

pthread_attr_setinheritsched

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

Syntax

pthread_attr_setinheritsched(
attr ,
inheritsched );

Argument Data Type Access

attr opaque pthread_attr_t write

inheritsched integer read

Argument	Data Type	Access
attr	opaque pthread_attr_t	write
inheritsched	integer	read

C Binding #include <pthread.h>

  6493P007.HTM
  OSSG Documentation
  22-NOV-1996 13:20:05.80

Legal

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

Return	Description
0	Successful completion.
EINVAL	The value specified by attr is invalid.

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

Guide to DECthreads

pthread_atfork

Syntax

pthread_atfork( prepare , parent , child );

ARGUMENTS

prepare

parent

child

DESCRIPTION

Associated Routines

pthread_attr_destroy

Syntax

pthread_attr_destroy( attr );

ARGUMENTS

attr

DESCRIPTION

Associated Routines

pthread_attr_getdetachstate

Syntax

pthread_attr_getdetachstate( attr , detachstate );

ARGUMENTS

attr

detachstate

DESCRIPTION

Associated Routines

pthread_attr_getguardsize_np

Syntax

pthread_attr_getguardsize_np( attr , guardsize );

ARGUMENTS

attr

guardsize

DESCRIPTION

Associated Routines

pthread_attr_getinheritsched

Syntax

pthread_attr_getinheritsched( attr , inheritsched );

ARGUMENTS

attr

inheritsched

DESCRIPTION

Associated Routines

pthread_attr_getschedparam

Syntax

pthread_attr_getschedparam( attr , param );

ARGUMENTS

attr

param

DESCRIPTION

Associated Routines

pthread_attr_getschedpolicy

Syntax

pthread_attr_getschedpolicy( attr , policy );

ARGUMENTS

attr

policy

DESCRIPTION

Associated Routines

pthread_attr_getstacksize

Syntax

pthread_attr_getstacksize( attr , stacksize );

ARGUMENTS

attr

stacksize

DESCRIPTION

Associated Routines

pthread_attr_init

Syntax

pthread_attr_init( attr );

ARGUMENTS

attr

DESCRIPTION

Associated Routines

pthread_attr_setdetachstate

Syntax

pthread_attr_setdetachstate( attr , detachstate );

ARGUMENTS

attr

detachstate

DESCRIPTION

Associated Routines

pthread_atfork(
prepare ,
parent ,
child );

pthread_attr_destroy(
attr );

pthread_attr_getdetachstate(
attr ,
detachstate );

pthread_attr_getguardsize_np(
attr ,
guardsize );

pthread_attr_getinheritsched(
attr ,
inheritsched );

pthread_attr_getschedparam(
attr ,
param );

pthread_attr_getschedpolicy(
attr ,
policy );

pthread_attr_getstacksize(
attr ,
stacksize );

pthread_attr_init(
attr );

pthread_attr_setdetachstate(
attr ,
detachstate );

pthread_attr_setguardsize_np(
attr ,
guardsize );

pthread_attr_setinheritsched(
attr ,
inheritsched );