summaryrefslogtreecommitdiffstats
path: root/man3/pthread_attr_setscope.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/pthread_attr_setscope.3')
-rw-r--r--man3/pthread_attr_setscope.3140
1 files changed, 140 insertions, 0 deletions
diff --git a/man3/pthread_attr_setscope.3 b/man3/pthread_attr_setscope.3
new file mode 100644
index 0000000..c9acfc4
--- /dev/null
+++ b/man3/pthread_attr_setscope.3
@@ -0,0 +1,140 @@
+'\" t
+.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
+.\" <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH pthread_attr_setscope 3 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+pthread_attr_setscope, pthread_attr_getscope \- set/get contention scope
+attribute in thread attributes object
+.SH LIBRARY
+POSIX threads library
+.RI ( libpthread ", " \-lpthread )
+.SH SYNOPSIS
+.nf
+.B #include <pthread.h>
+.PP
+.BI "int pthread_attr_setscope(pthread_attr_t *" attr ", int " scope );
+.BI "int pthread_attr_getscope(const pthread_attr_t *restrict " attr ,
+.BI " int *restrict " scope );
+.fi
+.SH DESCRIPTION
+The
+.BR pthread_attr_setscope ()
+function sets the contention scope attribute of the
+thread attributes object referred to by
+.I attr
+to the value specified in
+.IR scope .
+The contention scope attribute defines the set of threads
+against which a thread competes for resources such as the CPU.
+POSIX.1 specifies two possible values for
+.IR scope :
+.TP
+.B PTHREAD_SCOPE_SYSTEM
+The thread competes for resources with all other threads
+in all processes on the system that are in the same scheduling
+allocation domain (a group of one or more processors).
+.B PTHREAD_SCOPE_SYSTEM
+threads are scheduled relative to one another
+according to their scheduling policy and priority.
+.TP
+.B PTHREAD_SCOPE_PROCESS
+The thread competes for resources with all other threads
+in the same process that were also created with the
+.B PTHREAD_SCOPE_PROCESS
+contention scope.
+.B PTHREAD_SCOPE_PROCESS
+threads are scheduled relative to other threads in the process
+according to their scheduling policy and priority.
+POSIX.1 leaves it unspecified how these threads contend
+with other threads in other process on the system or
+with other threads in the same process that
+were created with the
+.B PTHREAD_SCOPE_SYSTEM
+contention scope.
+.PP
+POSIX.1 requires that an implementation support at least one of these
+contention scopes.
+Linux supports
+.BR PTHREAD_SCOPE_SYSTEM ,
+but not
+.BR PTHREAD_SCOPE_PROCESS .
+.PP
+On systems that support multiple contention scopes, then,
+in order for the parameter setting made by
+.BR pthread_attr_setscope ()
+to have effect when calling
+.BR pthread_create (3),
+the caller must use
+.BR pthread_attr_setinheritsched (3)
+to set the inherit-scheduler attribute of the attributes object
+.I attr
+to
+.BR PTHREAD_EXPLICIT_SCHED .
+.PP
+The
+.BR pthread_attr_getscope ()
+function returns the contention scope attribute of the
+thread attributes object referred to by
+.I attr
+in the buffer pointed to by
+.IR scope .
+.SH RETURN VALUE
+On success, these functions return 0;
+on error, they return a nonzero error number.
+.SH ERRORS
+.BR pthread_attr_setscope ()
+can fail with the following errors:
+.TP
+.B EINVAL
+An invalid value was specified in
+.IR scope .
+.TP
+.B ENOTSUP
+.I scope
+specified the value
+.BR PTHREAD_SCOPE_PROCESS ,
+which is not supported on Linux.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR pthread_attr_setscope (),
+.BR pthread_attr_getscope ()
+T} Thread safety MT-Safe
+.TE
+.sp 1
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
+.SH NOTES
+The
+.B PTHREAD_SCOPE_SYSTEM
+contention scope typically indicates that a user-space thread is
+bound directly to a single kernel-scheduling entity.
+This is the case on Linux for the obsolete LinuxThreads implementation
+and the modern NPTL implementation,
+which are both 1:1 threading implementations.
+.PP
+POSIX.1 specifies that the default contention scope is
+implementation-defined.
+.SH SEE ALSO
+.ad l
+.nh
+.BR pthread_attr_init (3),
+.BR pthread_attr_setaffinity_np (3),
+.BR pthread_attr_setinheritsched (3),
+.BR pthread_attr_setschedparam (3),
+.BR pthread_attr_setschedpolicy (3),
+.BR pthread_create (3),
+.BR pthreads (7)