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 .\" $FreeBSD$
  26 .\"
  27 .Dd June 2, 2016
  28 .Dt PTHREAD_ATTR_AFFINITY_NP 3
  29 .Os
  30 .Sh NAME
  31 .Nm pthread_attr_getaffinity_np ,
  32 .Nm pthread_attr_setaffinity_np
  33 .Nd manage CPU affinity in thread attribute objects
  34 .Sh LIBRARY
  35 .Lb libpthread
  36 .Sh SYNOPSIS
  37 .In pthread_np.h
  38 .Ft int
  39 .Fn pthread_attr_getaffinity_np "const pthread_attr_t *pattr" "size_t cpusetsize" "cpuset_t *cpusetp"
  40 .Ft int
  41 .Fn pthread_attr_setaffinity_np "pthread_attr_t *pattr" "size_t cpusetsize" "const cpuset_t *cpusetp"
  42 .Sh DESCRIPTION
  43 The
  44 .Fn pthread_attr_getaffinity_np
  45 and
  46 .Fn pthread_attr_setaffinity_np
  47 functions allow the manipulation of sets of CPUs available to the specified thread attribute object.
  48 .Pp
  49 Masks of type
  50 .Ft cpuset_t
  51 are composed using the
  52 .Dv CPU_SET
  53 macros.
  54 The kernel tolerates large sets as long as all CPUs specified
  55 in the set exist.
  56 Sets smaller than the kernel uses generate an error on calls to
  57 .Fn pthread_attr_getaffinity_np
  58 even if the result set would fit within the user supplied set.
  59 Calls to
  60 .Fn pthread_attr_setaffinity_np
  61 tolerate small sets with no restrictions.
  62 .Pp
  63 The supplied mask should have a size of
  64 .Fa cpusetsize
  65 bytes.
  66 This size is usually provided by calling
  67 .Li sizeof(cpuset_t)
  68 which is ultimately determined by the value of
  69 .Dv CPU_SETSIZE
  70 as defined in
  71 .In sys/cpuset.h .
  72 .Pp
  73 .Fn pthread_attr_getaffinity_np
  74 retrieves the
  75 mask from the thread attribute object specified by
  76 .Fa pattr ,
  77 and stores it in the space provided by
  78 .Fa cpusetp .
  79 .Pp
  80 .Fn pthread_attr_setaffinity_np
  81 sets the mask for the thread attribute object specified by
  82 .Fa pattr
  83 to the value in
  84 .Fa cpusetp .
  85 .Sh RETURN VALUES
  86 If successful, the
  87 .Fn pthread_attr_getaffinity_np
  88 and
  89 .Fn pthread_attr_setaffinity_np
  90 functions will return zero.
  91 Otherwise an error number will be returned
  92 to indicate the error.
  93 .Sh ERRORS
  94 The
  95 .Fn pthread_attr_getaffinity_np
  96 functions will fail if:
  97 .Bl -tag -width Er
  98 .It Bq Er EINVAL
  99 The
 100 .Fa pattr
 101 or the attribute specified by it is
 102 .Dv NULL .
 103 .It Bq Er ERANGE
 104 The
 105 .Fa cpusetsize
 106 is too small.
 107 .El
 108 .Pp
 109 The
 110 .Fn pthread_attr_setaffinity_np
 111 function will fail if:
 112 .Bl -tag -width Er
 113 .It Bq Er EINVAL
 114 The
 115 .Fa pattr
 116 or the attribute specified by it is
 117 .Dv NULL .
 118 .It Bq Er EINVAL
 119 The
 120 .Fa cpusetp
 121 specified a CPU that was outside the set supported by the kernel.
 122 .It Bq Er ERANGE
 123 The
 124 .Fa cpusetsize
 125 is too small.
 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_setaffinity_np 3
 136 .Sh STANDARDS
 137 The
 138 .Nm pthread_attr_getaffinity_np
 139 and
 140 .Nm pthread_attr_setaffinity_np
 141 functions are non-standard
 142 .Fx
 143 extensions and may be not available on other operating systems.
 144 .Sh HISTORY
 145 The
 146 .Nm pthread_attr_getaffinity_np
 147 and
 148 .Nm pthread_attr_setaffinity_np
 149 functions first appeared in
 150 .Fx 7.2 .
 151 .Sh AUTHORS
 152 .An -nosplit
 153 The
 154 .Nm pthread_attr_getaffinity_np
 155 and
 156 .Nm pthread_attr_setaffinity_np
 157 functions were written by
 158 .An David Xu Aq Mt davidxu@FreeBSD.org ,
 159 and this manpage was written by
 160 .An Xin LI Aq Mt delphij@FreeBSD.org .