1.\" Copyright (c) 2017 The DragonFly Project. All rights reserved. 2.\" 3.\" This code is derived from software contributed to The DragonFly Project 4.\" by Sepherosa Ziehau <sepherosa@gmail.com>. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in 14.\" the documentation and/or other materials provided with the 15.\" distribution. 16.\" 3. Neither the name of The DragonFly Project nor the names of its 17.\" contributors may be used to endorse or promote products derived 18.\" from this software without specific, prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 21.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 23.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 24.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 25.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, 26.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 27.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 28.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 30.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" SUCH DAMAGE. 32.\" 33.Dd January 14, 2017 34.Dt LWP_SETAFFINITY 2 35.Os 36.Sh NAME 37.Nm lwp_setaffinity, 38.Nm lwp_getaffinity 39.Nd set and get a LWP's CPU affinity mask 40.Sh LIBRARY 41.Lb libc 42.Sh SYNOPSIS 43.In sys/types.h 44.In sys/usched.h 45.Ft int 46.Fn lwp_setaffinity "pid_t pid" "lwpid_t tid" "const cpumask_t *mask" 47.Ft int 48.Fn lwp_getaffinity "pid_t pid" "lwpid_t tid" "cpumask_t *mask" 49.Sh DESCRIPTION 50The 51.Fn lwp_setaffinity 52system call sets the CPU affinity mask of the LWP, 53which is identified by the 54.Fa pid 55and the 56.Fa tid , 57to the value specified by the 58.Fa mask . 59If the 60.Fa pid 61is zero, 62then the pid of the calling process is used. 63If the 64.Fa tid 65is less than zero, 66then all LWPs of the process identified by the 67.Fa pid 68are affected. 69If the LWP specified by the 70.Fa pid 71and the 72.Fa tid 73is the current LWP it will be migrated immediately, 74if necessary, otherwise it will be migrated by the scheduler later. 75.Pp 76A process created by 77.Xr fork 2 , 78.Xr vfork 2 , 79and 80.Xr rfork 2 81inherits the calling LWP's CPU affinity mask. 82Same applies to the LWPs created by 83.Xr lwp_create 2 , 84and the threads created by 85.Xr pthread_create 3 . 86.Pp 87.Fn lwp_getaffinity 88writes the affinity mask of the LWP, 89which is identified by the 90.Fa pid 91and the 92.Fa tid , 93to the cpumask_t structure pointed to by 94.Fa mask . 95If the 96.Fa pid 97is zero, 98then the pid of the calling process is used. 99If the 100.Fa tid 101is less than zero, 102then the first LWP of specified process is used. 103.Sh RETURN VALUES 104These system calls return \-1 on error and 1050 upon successful completion. 106.Sh ERRORS 107The 108.Fn lwp_setaffinity 109and 110.Fn lwp_getaffinity 111system calls will fail if: 112.Bl -tag -width Er 113.It Bq Er EFAULT 114The 115.Fa name 116parameter is outside the process's allocated address space. 117.It Bq Er EINVAL 118The 119.Fa pid 120parameter is negative. 121.It Bq Er ESRCH 122The LWP identified by the 123.Fa pid 124and the 125.Fa tid 126does not exist. 127.It Bq Er EPERM 128The 129.Fa mask 130does not contain a valid CPU. 131.El 132.Sh SEE ALSO 133.Xr fork 2 134.Xr lwp_create 2 135.Xr pthread_create 3 136.Xr pthread_getaffinity_np 3 137.Xr pthread_setaffinity_np 3 138.Xr rfork 2 139.Xr sched_getaffinity 2 140.Xr sched_setaffinity 2 141.Xr vfork 2 142.Sh HISTORY 143The 144.Fn lwp_setaffinity 145and 146.Fn lwp_getaffinity 147functions first appeared in 148.Dx 4.7 . 149