share/man/man3/pthread_attr_affinity_np.3

   1 .\"-
   2 .\" Copyright (c) 2010 Xin LI <delphij@FreeBSD.org>
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .Dd January 29, 2023
  26 .Dt PTHREAD_ATTR_AFFINITY_NP 3
  27 .Os
  28 .Sh NAME
  29 .Nm pthread_attr_getaffinity_np ,
  30 .Nm pthread_attr_setaffinity_np
  31 .Nd manage CPU affinity in thread attribute objects
  32 .Sh LIBRARY
  33 .Lb libpthread
  34 .Sh SYNOPSIS
  35 .In pthread_np.h
  36 .Ft int
  37 .Fn pthread_attr_getaffinity_np "const pthread_attr_t *pattr" "size_t cpusetsize" "cpuset_t *cpusetp"
  38 .Ft int
  39 .Fn pthread_attr_setaffinity_np "pthread_attr_t *pattr" "size_t cpusetsize" "const cpuset_t *cpusetp"
  40 .Sh DESCRIPTION
  41 The
  42 .Fn pthread_attr_getaffinity_np
  43 and
  44 .Fn pthread_attr_setaffinity_np
  45 functions allow the manipulation of sets of CPUs available to the specified thread attribute object.
  46 .Pp
  47 Masks of type
  48 .Ft cpuset_t
  49 are composed using the
  50 .Dv CPU_SET
  51 macros.
  52 If the user-supplied mask is not large enough to fit all of the matching CPUs,
  53 .Fn pthread_attr_getaffinity_np
  54 fails with
  55 .Er ERANGE .
  56 Calls to
  57 .Fn pthread_attr_setaffinity_np
  58 tolerate masks of any size with no restrictions.
  59 .Fn pthread_attr_setaffinity_np
  60 uses the meaningful part of the mask, where the upper bound is
  61 the maximum CPU id present in the system.
  62 If bits for non-existing CPUs are set, calls to
  63 .Fn pthread_attr_setaffinity_np
  64 fail with
  65 .Er EINVAL .
  66 .Pp
  67 The supplied mask should have a size of
  68 .Fa cpusetsize
  69 bytes.
  70 This size is usually provided by calling
  71 .Li sizeof(cpuset_t)
  72 which is ultimately determined by the value of
  73 .Dv CPU_SETSIZE
  74 as defined in
  75 .In sys/cpuset.h .
  76 .Pp
  77 .Fn pthread_attr_getaffinity_np
  78 retrieves the
  79 mask from the thread attribute object specified by
  80 .Fa pattr ,
  81 and stores it in the space provided by
  82 .Fa cpusetp .
  83 .Pp
  84 .Fn pthread_attr_setaffinity_np
  85 sets the mask for the thread attribute object specified by
  86 .Fa pattr
  87 to the value in
  88 .Fa cpusetp .
  89 .Sh RETURN VALUES
  90 If successful, the
  91 .Fn pthread_attr_getaffinity_np
  92 and
  93 .Fn pthread_attr_setaffinity_np
  94 functions will return zero.
  95 Otherwise an error number will be returned
  96 to indicate the error.
  97 .Sh ERRORS
  98 The
  99 .Fn pthread_attr_getaffinity_np
 100 functions will fail if:
 101 .Bl -tag -width Er
 102 .It Bq Er EINVAL
 103 The
 104 .Fa pattr
 105 or the attribute specified by it is
 106 .Dv NULL .
 107 .It Bq Er ERANGE
 108 The
 109 .Fa cpusetsize
 110 is too small.
 111 .El
 112 .Pp
 113 The
 114 .Fn pthread_attr_setaffinity_np
 115 function will fail if:
 116 .Bl -tag -width Er
 117 .It Bq Er EINVAL
 118 The
 119 .Fa pattr
 120 or the attribute specified by it is
 121 .Dv NULL .
 122 .It Bq Er EINVAL
 123 The
 124 .Fa cpusetp
 125 specified a CPU that was outside the set supported by the kernel.
 126 .It Bq Er ENOMEM
 127 Insufficient memory exists to store the cpuset mask.
 128 .El
 129 .Sh SEE ALSO
 130 .Xr cpuset 1 ,
 131 .Xr cpuset 2 ,
 132 .Xr cpuset_getid 2 ,
 133 .Xr cpuset_setid 2 ,
 134 .Xr pthread_getaffinity_np 3 ,
 135 .Xr pthread_np 3 ,
 136 .Xr pthread_setaffinity_np 3
 137 .Sh STANDARDS
 138 The
 139 .Nm pthread_attr_getaffinity_np
 140 and
 141 .Nm pthread_attr_setaffinity_np
 142 functions are non-standard
 143 .Fx
 144 extensions and may be not available on other operating systems.
 145 .Sh HISTORY
 146 The
 147 .Nm pthread_attr_getaffinity_np
 148 and
 149 .Nm pthread_attr_setaffinity_np
 150 functions first appeared in
 151 .Fx 7.2 .
 152 .Sh AUTHORS
 153 .An -nosplit
 154 The
 155 .Nm pthread_attr_getaffinity_np
 156 and
 157 .Nm pthread_attr_setaffinity_np
 158 functions were written by
 159 .An David Xu Aq Mt davidxu@FreeBSD.org ,
 160 and this manpage was written by
 161 .An Xin LI Aq Mt delphij@FreeBSD.org .