xref: /dflybsd-src/lib/libc/sys/lwp_setaffinity.2 (revision 480ed3de1b262fe0d036ad078a8dec4a4164a74c)

.\" Copyright (c) 2017 The DragonFly Project.  All rights reserved.
.\"
.\" This code is derived from software contributed to The DragonFly Project
.\" by Sepherosa Ziehau <sepherosa@gmail.com>.
.\"
.\" 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.
.\" 3. Neither the name of The DragonFly Project nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific, prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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
.\" COPYRIGHT HOLDERS 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 January 11, 2017
.Dt LWP_SETAFFINITY 2
.Os
.Sh NAME
.Nm lwp_setaffinity,
.Nm lwp_getaffinity
.Nd set and get a LWP's CPU affinity mask
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In sys/types.h
.In sys/usched.h
.Ft int
.Fn lwp_setaffinity "pid_t pid" "lwpid_t tid" "const cpumask_t *mask"
.Ft int
.Fn lwp_getaffinity "pid_t pid" "lwpid_t tid" "cpumask_t *mask"
.Sh DESCRIPTION
The
.Fn lwp_setaffinity
system call sets the CPU affinity mask of the LWP,
which is identified by the
.Fa pid
and the
.Fa tid ,
to the value specified by the
.Fa mask .
If the
.Fa pid
is zero,
then the pid of the calling LWP's process is used.
If the
.Fa tid
is less than zero,
then all threads of the calling LWP are affected.
If the LWP specified by the
.Fa pid
and the
.Fa tid
is the current thread it will be migrated immediately,
if necessary, otherwise it will be migrated by the scheduler
later.
.Pp
A process created by
.Xr fork 2 ,
.Xr vfork 2 ,
and
.Xr rfork 2
inherits the calling LWP's CPU affinity mask.
Same applies to the LWPs created by
.Xr lwp_create 2 ,
and the threads created by
.Xr pthread_create 3 .
.Pp
.Fn lwp_getaffinity
writes the affinity mask of the LWP,
which is identified by the
.Fa pid
and the
.Fa tid ,
to the cpumask_t structure pointed to by
.Fa mask .
If the
.Fa pid
is zero,
then the pid of the calling LWP's process is used.
If the
.Fa tid
is less than zero,
then the first thread of specified process is used.
.Sh RETURN VALUES
These system calls return \-1 on error and
0 upon successful completion.
.Sh ERRORS
The
.Fn lwp_setaffinity
and
.Fn lwp_getaffinity
system calls will fail if:
.Bl -tag -width Er
.It Bq Er EFAULT
The
.Fa name
parameter is outside the process's allocated address space.
.It Bq Er EINVAL
The
.Fa pid
parameter is negative.
.It Bq Er ESRCH
The LWP identified by the
.Fa pid
and the
.Fa tid
does not exist.
.It Bq Er EPERM
The
.Fa mask
does not contain a valid CPU.
.El
.Sh SEE ALSO
.Xr fork 2
.Xr lwp_create 2
.Xr pthread_create 3
.Xr rfork 2
.Xr vfork 2
.Sh HISTORY
The
.Fn lwp_setaffinity
and
.Fn lwp_getaffinity
functions first appeared in
.Dx 4.7 .