1.\" $NetBSD: pset.3,v 1.6 2008/06/22 08:24:40 wiz Exp $ 2.\" 3.\" Copyright (c) 2008 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Mindaugas Rasiukevicius <rmind at NetBSD org>. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd June 16, 2008 31.Dt PSET 3 32.Os 33.Sh NAME 34.Nm pset_create , 35.Nm pset_assign , 36.Nm pset_bind , 37.Nm pset_destroy 38.Nd processor sets 39.Sh SYNOPSIS 40.In sys/pset.h 41.Ft int 42.Fn pset_create "psetid_t *psid" 43.Ft int 44.Fn pset_assign "psetid_t psid" "cpuid_t cpuid" "psetid_t *opsid" 45.Ft int 46.Fn pset_bind "psetid_t psid" "idtype_t type" "id_t id" "psetid_t *opsid" 47.Ft int 48.Fn pset_destroy "psetid_t psid" 49.Sh DESCRIPTION 50The processor sets API provides the possibility to bind processes or 51threads to specific processors or groups of processors. 52This section describes the functions used to control processor sets. 53.Ss FUNCTIONS 54.Bl -tag -width compact 55.It Fn pset_create psid 56Creates a processor set, and returns its ID into 57.Fa psid . 58.It Fn pset_assign psid cpu opsid 59Assigns the processor specified by 60.Fa cpuid 61to the processor set specified by 62.Fa psid . 63Stores the current processor set ID of the processor or 64.Dv PS_NONE 65into 66.Fa opsid , 67if the pointer is not 68.Dv NULL . 69.Pp 70If 71.Fa psid 72is set to 73.Dv PS_QUERY , 74then the current processor set ID will be returned into 75.Fa psid , 76and no assignment will be performed. 77.Pp 78If 79.Fa psid 80is set to 81.Dv PS_MYID , 82then the processor set ID of the calling process will be used, and 83.Fa psid 84will be ignored. 85.Pp 86If 87.Fa psid 88is set to 89.Dv PS_NONE , 90any assignment to the processor will be cleared. 91.It Fn pset_bind psid type id opsid 92Binds the target specified by 93.Fa id 94to the processor set specified by 95.Fa psid . 96The current processor set ID to which the target is bound or 97.Dv PS_NONE 98will be returned in 99.Fa opsid , 100if the pointer is not 101.Dv NULL . 102.Nx 103supports the following types of targets specified by 104.Fa type : 105.Bl -tag -width P_PID 106.It Dv P_PID 107Process identified by the PID. 108.It Dv P_LWPID 109Thread of the calling process indentified by the LID. 110.El 111.Pp 112If 113.Fa psid 114is set to 115.Dv PS_QUERY , 116then the current processor set ID to which the target is bound or 117.Dv PS_NONE 118will be returned in 119.Fa opsid , 120and no binding will be performed. 121If 122.Fa psid 123is set to 124.Dv PS_MYID , 125then the processor set ID of the calling process will be used. 126.Pp 127If 128.Fa psid 129is set to 130.Dv PS_NONE , 131the specified target will be unbound from the processor set. 132.It Fn pset_destroy psid 133Destroys the processor set specified by 134.Fa psid . 135Before destroying the processor set, all related assignments of the 136processors will be cleared, and all bound threads will be unbound. 137.Pp 138If 139.Fa psid 140is 141.Dv PS_MYID , 142the processor set ID of the caller thread will be used. 143.El 144.Ss NOTES 145The 146.Fa pset_bind 147function can return the current processor set ID to which the 148target is bound, or 149.Dv PS_NONE . 150However, for example, the process may have many threads, which could be 151bound to different processor sets. 152In such a case it is unspecified which thread will be used to return 153the information. 154.Pp 155Processor sets might be used together with the thread affinity, see 156.Xr affinity 3 . 157In such case, the affinity mask takes precedence over the assignment 158to processor sets. 159.Sh RETURN VALUES 160Upon successful completion these functions return 0. 161Otherwise, \-1 is returned and 162.Va errno 163is set to indicate the error. 164.Sh EXAMPLES 165An example of code fragment, which assigns the CPU whose ID is 0, 166for current process: 167.Bd -literal 168 psetid_t psid; 169 cpuid_t ci = 0; 170 171 if (pset_create(\*[Am]psid) \*[Lt] 0) 172 err(EXIT_FAILURE, "pset_create"); 173 174 /* Assign CPU 0 to the processor-set */ 175 if (pset_assign(psid, ci, NULL) \*[Lt] 0) 176 err(EXIT_FAILURE, "pset_assign"); 177 178 /* Bind the current process to the processor-set */ 179 if (pset_bind(psid, P_PID, P_MYID, NULL) \*[Lt] 0) 180 err(EXIT_FAILURE, "pset_bind"); 181 182 /* 183 * At this point, CPU 0 runs only the current process. 184 */ 185 perform_work(); 186 187 if (pset_destroy(psid) \*[Lt] 0) 188 err(EXIT_FAILURE, "pset_destroy") 189.Ed 190.Sh ERRORS 191The 192.Fn pset_create 193function fails if: 194.Bl -tag -width Er 195.It Bq Er ENOMEM 196No memory is available for creation of the processor set, or limit 197of the allowed count of the processor sets was reached. 198.It Bq Er EPERM 199The calling process is not the super-user. 200.El 201.Pp 202The 203.Fn pset_assign 204function fails if: 205.Bl -tag -width Er 206.It Bq Er EBUSY 207Another operation is performing on the processor set. 208.It Bq Er EINVAL 209.Fa psid 210or 211.Fa cpuid 212are invalid. 213.It Bq Er EPERM 214The calling process is not the super-user, and 215.Fa psid 216is not 217.Dv PS_QUERY . 218.El 219.Pp 220The 221.Fn pset_bind 222function fails if: 223.Bl -tag -width Er 224.It Bq Er EBUSY 225Another operation is performing on the processor set. 226.It Bq Er EINVAL 227.Fa psid 228or 229.Fa type 230are invalid. 231.It Bq Er EPERM 232The calling process is not the super-user, and 233.Fa psid 234is not 235.Dv PS_QUERY . 236.It Bq Er ESRCH 237The specified target was not found. 238.El 239.Pp 240The 241.Fn pset_destroy 242function fails if: 243.Bl -tag -width Er 244.It Bq Er EBUSY 245Another operation is performing on the processor set. 246.It Bq Er EPERM 247The calling process is not the super-user. 248.El 249.Sh SEE ALSO 250.Xr affinity 3 , 251.Xr cpuset 3 , 252.Xr sched 3 , 253.Xr schedctl 8 254.Sh STANDARDS 255This API is expected to be compatible with the APIs found in Solaris and 256HP-UX operating systems. 257.Sh HISTORY 258The processor sets appeared in 259.Nx 5.0 . 260