share/man/man3/pthread_attr_affinity_np.3

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