.\" $NetBSD: pthread_attr_getscope.3,v 1.2 2010/07/07 10:22:33 njoly Exp $
.\"
.\" Copyright (c) 2010 Jukka Ruohonen <jruohonen@iki.fi>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd July 7, 2010
.Dt PTHREAD_ATTR_GETSCOPE 3
.Os
.Sh NAME
.Nm pthread_attr_getscope
.Nd get and set the contention scope attribute
.Sh LIBRARY
.Lb libpthread
.Sh SYNOPSIS
.In pthread.h
.Ft int
.Fn pthread_attr_getscope \
"const pthread_attr_t * restrict attr" "int * restrict contentionscope"
.Ft int
.Fn pthread_attr_setscope "pthread_attr_t *attr" "int contentionscope"
.Sh DESCRIPTION
The
.Fn pthread_attr_getscope
and
.Fn pthread_attr_setscope
functions get and set, respectively, the contention scope attribute in the
.Fa attr
object.
.Pp
The
.Fa contentionscope
parameter specifies the scheduling contention scope of a thread.
It is only possible to set the scope of a thread before the thread is created.
There are two possible contention scopes:
.Bl -tag -width PTHREAD_SCOPE_PROCESS -offset 2n
.It Dv PTHREAD_SCOPE_SYSTEM
The thread will contend for
.Tn CPU
resources with all other processes and threads in the system.
Generally this means that the user thread is bound directly to the
kernel scheduling for its entire lifetime.
.It Dv PTHREAD_SCOPE_PROCESS
The thread will contend with other threads with the same scope attribute.
In general, this means that all
.Dv PTHREAD_SCOPE_PROCESS
threads are grouped together and this group of threads contends for
.Tn CPU
resources.
This is commonly seen to require a hybrid
.Pq Dq M:N
threading model in order to multiplex the user and kernel space scheduling.
.El
.Pp
Only
.Dv PTHREAD_SCOPE_SYSTEM
is supported in
.Nx .
.Sh RETURN VALUES
Upon successful completion, both functions return 0.
Otherwise an error number is returned to indicate the error.
.Sh ERRORS
No errors are defined for
.Fn pthread_attr_getscope .
.Pp
The
.Fn pthread_attr_setscope
function shall fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
Invalid parameter.
.El
.Sh SEE ALSO
.Xr pthread_attr 3 ,
.Xr csf 9
.Sh STANDARDS
Both functions conform to
.St -p1003.1-96 .