1.\" $NetBSD: pset.3,v 1.7 2008/10/18 03:37:41 rmind 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 October 18, 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.Sh 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 155If processor sets are used together with the thread affinity, see 156.Xr affinity 3 , 157then affinity mask takes precedence over the assignment to processor 158set. 159However, it is not recomended to combine these interfaces together. 160.Sh RETURN VALUES 161Upon successful completion these functions return 0. 162Otherwise, \-1 is returned and 163.Va errno 164is set to indicate the error. 165.Sh EXAMPLES 166An example of code fragment, which assigns the CPU whose ID is 0, 167for current process: 168.Bd -literal 169 psetid_t psid; 170 cpuid_t ci = 0; 171 172 if (pset_create(\*[Am]psid) \*[Lt] 0) 173 err(EXIT_FAILURE, "pset_create"); 174 175 /* Assign CPU 0 to the processor-set */ 176 if (pset_assign(psid, ci, NULL) \*[Lt] 0) 177 err(EXIT_FAILURE, "pset_assign"); 178 179 /* Bind the current process to the processor-set */ 180 if (pset_bind(psid, P_PID, P_MYID, NULL) \*[Lt] 0) 181 err(EXIT_FAILURE, "pset_bind"); 182 183 /* 184 * At this point, CPU 0 runs only the current process. 185 */ 186 perform_work(); 187 188 if (pset_destroy(psid) \*[Lt] 0) 189 err(EXIT_FAILURE, "pset_destroy"); 190.Ed 191.Sh ERRORS 192The 193.Fn pset_create 194function fails if: 195.Bl -tag -width Er 196.It Bq Er ENOMEM 197No memory is available for creation of the processor set, or limit 198of the allowed count of the processor sets was reached. 199.It Bq Er EPERM 200The calling process is not the super-user. 201.El 202.Pp 203The 204.Fn pset_assign 205function fails if: 206.Bl -tag -width Er 207.It Bq Er EBUSY 208Another operation is performing on the processor set. 209.It Bq Er EINVAL 210.Fa psid 211or 212.Fa cpuid 213are invalid. 214.It Bq Er EPERM 215The calling process is not the super-user, and 216.Fa psid 217is not 218.Dv PS_QUERY . 219.El 220.Pp 221The 222.Fn pset_bind 223function fails if: 224.Bl -tag -width Er 225.It Bq Er EBUSY 226Another operation is performing on the processor set. 227.It Bq Er EINVAL 228.Fa psid 229or 230.Fa type 231are invalid. 232.It Bq Er EPERM 233The calling process is not the super-user, and 234.Fa psid 235is not 236.Dv PS_QUERY . 237.It Bq Er ESRCH 238The specified target was not found. 239.El 240.Pp 241The 242.Fn pset_destroy 243function fails if: 244.Bl -tag -width Er 245.It Bq Er EBUSY 246Another operation is performing on the processor set. 247.It Bq Er EPERM 248The calling process is not the super-user. 249.El 250.Sh SEE ALSO 251.Xr affinity 3 , 252.Xr cpuset 3 , 253.Xr sched 3 , 254.Xr schedctl 8 255.Sh STANDARDS 256This API is expected to be compatible with the APIs found in Solaris and 257HP-UX operating systems. 258.Sh HISTORY 259The processor sets appeared in 260.Nx 5.0 . 261