lib/libc/sys/lwp_setaffinity.2

   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/lwp.h
  44 .Ft int
  45 .Fn lwp_setaffinity "pid_t pid" "lwpid_t tid" "const cpumask_t *mask"
  46 .Ft int
  47 .Fn lwp_getaffinity "pid_t pid" "lwpid_t tid" "cpumask_t *mask"
  48 .Sh DESCRIPTION
  49 The
  50 .Fn lwp_setaffinity
  51 system call sets the CPU affinity mask of the LWP,
  52 which is identified by the
  53 .Fa pid
  54 and the
  55 .Fa tid ,
  56 to the value specified by the
  57 .Fa mask .
  58 If the
  59 .Fa pid
  60 is zero,
  61 then the pid of the calling process is used.
  62 If the
  63 .Fa tid
  64 is less than zero,
  65 then all LWPs of the process identified by the
  66 .Fa pid
  67 are affected.
  68 If the LWP specified by the
  69 .Fa pid
  70 and the
  71 .Fa tid
  72 is the current LWP it will be migrated immediately,
  73 if necessary, otherwise it will be migrated by the scheduler later.
  74 .Pp
  75 A process created by
  76 .Xr fork 2 ,
  77 .Xr vfork 2 ,
  78 and
  79 .Xr rfork 2
  80 inherits the calling LWP's CPU affinity mask.
  81 Same applies to the LWPs created by
  82 .Xr lwp_create 2 ,
  83 and the threads created by
  84 .Xr pthread_create 3 .
  85 .Pp
  86 .Fn lwp_getaffinity
  87 writes the affinity mask of the LWP,
  88 which is identified by the
  89 .Fa pid
  90 and the
  91 .Fa tid ,
  92 to the cpumask_t structure pointed to by
  93 .Fa mask .
  94 If the
  95 .Fa pid
  96 is zero,
  97 then the pid of the calling process is used.
  98 If the
  99 .Fa tid
 100 is less than zero,
 101 then the first LWP of specified process is used.
 102 .Sh RETURN VALUES
 103 These system calls return \-1 on error and
 104 0 upon successful completion.
 105 .Sh ERRORS
 106 The
 107 .Fn lwp_setaffinity
 108 and
 109 .Fn lwp_getaffinity
 110 system calls will fail if:
 111 .Bl -tag -width Er
 112 .It Bq Er EFAULT
 113 The
 114 .Fa name
 115 parameter is outside the process's allocated address space.
 116 .It Bq Er EINVAL
 117 The
 118 .Fa pid
 119 parameter is negative.
 120 .It Bq Er ESRCH
 121 The LWP identified by the
 122 .Fa pid
 123 and the
 124 .Fa tid
 125 does not exist.
 126 .It Bq Er EPERM
 127 The
 128 .Fa mask
 129 does not contain a valid CPU.
 130 .El
 131 .Sh SEE ALSO
 132 .Xr fork 2
 133 .Xr lwp_create 2
 134 .Xr pthread_create 3
 135 .Xr pthread_getaffinity_np 3
 136 .Xr pthread_setaffinity_np 3
 137 .Xr rfork 2
 138 .Xr sched_getaffinity 2
 139 .Xr sched_setaffinity 2
 140 .Xr vfork 2
 141 .Sh HISTORY
 142 The
 143 .Fn lwp_setaffinity
 144 and
 145 .Fn lwp_getaffinity
 146 functions first appeared in
 147 .Dx 4.7 .