int
pthread_atfork (
void (*prepare)(void),
void (*parent)(void),
void (*child)(void) );
prepare
Address of a routine that performs the fork preparation handling. This routine is called in the parent process before creating the child process.parent
Address of a routine that performs the fork parent handling. This routine is called in the parent process after creating the child process and before returning to the caller of fork(2).child
Address of a routine that performs the fork child handling. This routine is called in the child process before returning to the caller of fork(2).
This routine allows a main program or library to control resources during a DIGITAL UNIX fork(2) operation by declaring fork handler routines, as follows:Return Values If an error occurs, this routine returns an integer indicating the type of error. Possible return values are as follows:
- The fork handler routine specified in the prepare argument is called before fork(2) executes.
- The fork handler routine specified in the parent argument is called after fork(2) executes within the parent process.
- The fork handler routine specified in the child argument is called in the new child process after fork(2) executes.
Your program (or library) can use fork handlers to ensure that program context in the child process is consistent and meaningful. After fork(2) executes, only the calling thread exists in the child process, and the state of all memory in the parent process is replicated in the child process, including the states of any mutexes, condition variables, and so on.
For example, in the new child process there might exist locked mutexes that are copies of mutexes that were locked in the parent process by threads that do not exist in the child process. Therefore, any associated program state might be inconsistent in the child process.
The program can avoid this problem by calling pthread_atfork() to provide routines that acquire and release resources that are critical to the child process. For example, the prepare handler should lock all mutexes that you want to be usable in the child process. The parent handler just unlocks those mutexes. The child handler will also unlock them all---and might also create threads or reset any program state for the child process.
To illustrate, if your library uses the mutex my_mutex, you might provide pthread_atfork() handler routines coded as follows:
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(); }If no fork handling is desired, you can set any of this routine's arguments to NULL.
Note
It is not legal to call pthread_atfork() from within a fork handler routine. Doing so could cause a deadlock.
Return | Description |
---|---|
0 | Successful completion. |
[ENOMEM] | Insufficient table space exists to record the fork handler routines' addresses. |
Destroys a thread attributes object.
C Binding #include <pthread.h>pthread_attr_destroy(
attr );
Argument Data Type Access attr opaque pthread_attr_t modify
int
pthread_attr_destroy (
pthread_attr_t *attr);
attr
Thread attributes object to be destroyed.
This routine destroys a thread attributes object. Call this routine when a thread attributes object will no longer be referenced.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows: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 | Description |
---|---|
0 | Successful completion. |
[EINVAL] | The value specified by attr is invalid. |
Obtains the detachstate attribute of the specified thread attributes object.
C Binding #include <pthread.h>pthread_attr_getdetachstate(
attr ,
detachstate );
Argument Data Type Access attr opaque pthread_attr_t read detachstate integer write
int
pthread_attr_getdetachstate (
const pthread_attr_t *attr,
int *detachstate);
attr
Thread attributes object whose detachstate attribute is obtained.detachstate
Receives the value of the detachstate attribute.
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.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows: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 | Description |
---|---|
0 | Successful completion. |
[EINVAL] | The value specified by attr does not refer to an existing thread attributes object. |
Obtains the guardsize attribute of the specified thread attributes object.
C Binding #include <pthread.h>pthread_attr_getguardsize(
attr ,
guardsize );
Argument Data Type Access attr opaque pthread_attr_t read guardsize size_t write
int
pthread_attr_getguardsize (
const pthread_attr_t *attr,
size_t *guardsize);
attr
Address of the thread attributes object whose guardsize attribute is obtained.guardsize
Receives the value of the guardsize attribute of the thread attributes object specified by attr.
This routine obtains the value of the guardsize attribute of the thread attributes object specified in the attr argument and stores it in the location specified by the guardsize argument. The specified attributes object must already be initialized at the time this routine is called.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:When creating a thread, use a thread attributes object to specify nondefault values for thread attributes. The guardsize attribute of a thread attributes object specifies the minimum size (in bytes) of the guard area for the stack of a new thread.
A guard area can help a multithreaded program detect overflow of a thread's stack. A guard area is a region of no-access memory that DECthreads allocates at the overflow end of the thread's stack. When any thread attempts to access a memory location within this region, a memory addressing violation occurs.
Note that the value of the guardsize attribute of a particular thread attributes object does not necessarily correspond to the actual size of the guard area of any existing thread in your multithreaded program.
Return | Description |
---|---|
0 | Successful completion. |
[EINVAL] | The value specified by attr is invalid. |
Obtains the guardsize attribute of the specified thread attributes object.
C Binding #include <pthread.h>pthread_attr_getguardsize_np(
attr ,
guardsize );
Argument Data Type Access attr opaque pthread_attr_t read guardsize size_t write
int
pthread_attr_getguardsize_np (
const pthread_attr_t *attr,
size_t *guardsize);
attr
Address of the thread attributes object whose guardsize attribute is obtained.guardsize
Receives the value of the guardsize attribute of the thread attributes object specified by attr.
This routine obtains the value of the guardsize attribute of the thread attributes object specified in the attr argument and stores it in the location specified by the guardsize argument. The specified attributes object must already be initialized at the time this routine called.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:When creating a thread, use a thread attributes object to specify nondefault values for thread attributes. The guardsize attribute of a thread attributes object specifies the minimum size (in bytes) of the guard area for the stack of a new thread.
A guard area can help a multithreaded program detect overflow of a thread's stack. A guard area is a region of no-access memory that DECthreads allocates at the overflow end of the thread's stack. When any thread attempts to access a memory location within this region, a memory addressing violation occurs.
Note that the value of the guardsize attribute of a particular thread attributes object does not necessarily correspond to the actual size of the stack guard area of any existing thread in your multithreaded program.
Note
This routine has been superseded by the pthread_attr_getguardsize() routine, as specified by the Single UNIX Specification, Version 2.
Return | Description |
---|---|
0 | Successful completion. |
[EINVAL] | The value specified by attr is invalid. |
Obtains the inherit scheduling attribute of the specified thread attributes object.
C Binding #include <pthread.h>pthread_attr_getinheritsched(
attr ,
inheritsched );
Argument Data Type Access attr opaque pthread_attr_t read inheritsched integer write
int
pthread_attr_getinheritsched (
const pthread_attr_t *attr,
int *inheritsched);
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.
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. |
Obtains the object name attribute from a thread attributes object.
C Binding #include <pthread.h>pthread_attr_getname_np(
attr ,
name ,
len ,
mbz );
Argument Data Type Access attr opaque pthread_attr_t read name char write len opaque size_t read mbz void write
int
pthread_attr_getname_np (
const pthread_attr_t *attr,
char *name,
size_t len,
void **mbz);
attr
Address of the thread attributes object whose object name attribute is to be obtained.name
Location to store the obtained object name.len
Length in bytes of buffer at the location specified by name.mbz
(Must be zero) Location for use by DECthreads. On DIGITAL UNIX Alpha and OpenVMS Alpha platforms, the value to which this argument points must be a 64-bit pointer. If compiling with short pointers, ensure that you have allocated a 64-bit value to receive the result.
This routine copies the object name attribute from the thread attributes object specified by the attr argument to the buffer at the location specified by the name argument. Before calling this routine, your program must allocate the buffer indicated by name. A new thread created using the thread attributes object is initialized with the object name that was set in that attributes object.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:The object name is a C language string and provides an identifier that is meaningful to a person debugging a DECthreads-based multithreaded application. The maximum number of characters in the object name is 31.
If the specified thread attributes object has not been previously set with an object name, this routine copies a C language null string into the buffer at location name.
This routine contrasts with pthread_getname_np(), which obtains the object name from the thread object for an existing thread.
Return | Description |
---|---|
0 | Successful completion. |
[EINVAL] | The value specified by attr is invalid. |
Obtains the scheduling parameters for an attribute of the specified thread attributes object.
C Binding #include <pthread.h>pthread_attr_getschedparam(
attr ,
param );
Argument Data Type Access attr opaque pthread_attr_t read param struct sched_param write
int
pthread_attr_getschedparam (
const pthread_attr_t *attr,
struct sched_param *param);
attr
Thread attributes object of the scheduling policy attribute whose parameters are obtained.param
Receives the values of scheduling parameters for the scheduling policy attribute of the attributes object specified by the attr argument. Refer to the description of the pthread_attr_setschedparam() routine for valid parameters and their values.
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. |
Obtains the scheduling policy attribute of the specified thread attributes object.
C Binding #include <pthread.h>pthread_attr_getschedpolicy(
attr ,
policy );
Argument Data Type Access attr opaque pthread_attr_t read policy integer write
int
pthread_attr_getschedpolicy (
const pthread_attr_t *attr,
int *policy);
attr
Thread attributes object whose scheduling policy attribute is obtained.policy
Receives the value of the scheduling policy attribute. Refer to the description of the pthread_attr_setschedpolicy() routine for valid values.
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. |
Obtains the contention scope attribute of the specified thread attributes object.
C Binding #include <pthread.h>pthread_attr_getscope(
attr ,
scope );
Argument Data Type Access attr opaque pthread_attr_t read scope int write
int
pthread_attr_getscope (
const pthread_attr_t *attr,
int *scope);
attr
Address of the thread attributes object whose contention scope attribute is obtained.scope
Receives the value of the contention scope attribute of the thread attributes object specified by attr.
This routine obtains the value of the contention scope attribute of the thread attributes object specified in the attr argument and stores it in the location specified by the scope argument. The specified attributes object must already be initialized at the time this routine is called.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:The contention scope attribute specifies the set of threads with which a thread must compete for processing resources. The contention scope attribute specifies whether the new thread competes for processing resources only with other threads in its own process, called process contention scope, or with all threads on the system, called system contention scope.
DECthreads selects at most one thread to execute on each processor at any point in time. DECthreads resolves the contention based on each thread's scheduling attributes (for example, priority) and scheduling policy (for example, round-robin).
A thread created using a thread attributes object whose contention scope attribute is set to PTHREAD_SCOPE_PROCESS contends for processing resources with other threads within its own process that also were created with PTHREAD_SCOPE_PROCESS. It is unspecified how such threads are scheduled relative to threads in other processes or threads in the same process that were created with PTHREAD_SCOPE_SYSTEM contention scope.
A thread created using a thread attributes object whose contention scope attribute is set to PTHREAD_SCOPE_SYSTEM contends for processing resources with other threads in any process that also were created with PTHREAD_SCOPE_SYSTEM.
Note that the value of the contention scope attribute of a particular thread attributes object does not necessarily correspond to the actual scheduling contention scope of any existing thread in your multithreaded program.
Return | Description |
---|---|
0 | Successful completion. |
[ENOSYS] | This routine is not supported by the implementation. |
Obtains the stack address attribute of the specified thread attributes object.
C Binding #include <pthread.h>pthread_attr_getstackaddr(
attr ,
stackaddr );
Argument Data Type Access attr opaque pthread_attr_t read stackaddr void write
int
pthread_attr_getstackaddr (
const pthread_attr_t *attr,
void **stackaddr);
attr
Address of the thread attributes object whose stack address attribute is obtained.stackaddr
Receives the value of the stack address attribute of the thread attributes object specified by attr.
This routine obtains the value of the stack address attribute of the thread attributes object specified in the attr argument and stores it in the location specified by the stackaddr argument. The specified attributes object must already be initialized at the time this routine is called.
Previous | Next | Contents