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