share/man/man3/pthread_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 March 23, 2010
  28 .Dt PTHREAD_AFFINITY_NP 3
  29 .Os
  30 .Sh NAME
  31 .Nm pthread_getaffinity_np ,
  32 .Nm pthread_setaffinity_np
  33 .Nd manage CPU affinity
  34 .Sh LIBRARY
  35 .Lb libpthread
  36 .Sh SYNOPSIS
  37 .In pthread_np.h
  38 .Ft int
  39 .Fn pthread_getaffinity_np "pthread_t td" "size_t cpusetsize" "cpuset_t *cpusetp"
  40 .Ft int
  41 .Fn pthread_setaffinity_np "pthread_t td" "size_t cpusetsize" "const cpuset_t *cpusetp"
  42 .Sh DESCRIPTION
  43 .Fn pthread_getaffinity_np
  44 and
  45 .Fn pthread_setaffinity_np
  46 allow the manipulation of sets of CPUs available to the specified thread.
  47 .Pp
  48 Masks of type
  49 .Ft cpuset_t
  50 are composed using the
  51 .Dv CPU_SET
  52 macros.
  53 The kernel tolerates large sets as long as all CPUs specified
  54 in the set exist.
  55 Sets smaller than the kernel uses generate an error on calls to
  56 .Fn pthread_getaffinity_np
  57 even if the result set would fit within the user supplied set.
  58 Calls to
  59 .Fn pthread_setaffinity_np
  60 tolerate small sets with no restrictions.
  61 .Pp
  62 The supplied mask should have a size of
  63 .Fa cpusetsize
  64 bytes.
  65 This size is usually provided by calling
  66 .Li sizeof(cpuset_t)
  67 which is ultimately determined by the value of
  68 .Dv CPU_SETSIZE
  69 as defined in
  70 .In sys/cpuset.h .
  71 .Pp
  72 .Fn pthread_getaffinity_np
  73 retrieves the
  74 mask from the thread specified by
  75 .Fa td ,
  76 and stores it in the space provided by
  77 .Fa cpusetp .
  78 .Pp
  79 .Fn pthread_setaffinity_np
  80 attempts to set the mask for the thread specified by
  81 .Fa td
  82 to the value in
  83 .Fa cpusetp .
  84 .Sh RETURN VALUES
  85 If successful, the
  86 .Fn pthread_getaffinity_np
  87 and
  88 .Fn pthread_setaffinity_np
  89 functions will return zero.
  90 Otherwise an error number will be returned
  91 to indicate the error.
  92 .Sh ERRORS
  93 The
  94 .Fn pthread_getaffinity_np
  95 and
  96 .Fn pthread_setaffinity_np
  97 functions may fail if:
  98 .Bl -tag -width Er
  99 .It Bq Er EDEADLK
 100 The
 101 .Fn pthread_setaffinity_np
 102 call would leave a thread without a valid CPU to run on because the set
 103 does not overlap with the thread's anonymous mask.
 104 .It Bq Er EFAULT
 105 The
 106 .Fa cpusetp
 107 pointer passed was invalid.
 108 .It Bq Er ESRCH
 109 The thread specified by the
 110 .Fa td
 111 argument could not be found.
 112 .It Bq Er ERANGE
 113 The
 114 .Fa cpusetsize
 115 was either preposterously large or smaller than the kernel set size.
 116 .It Bq Er EPERM
 117 The calling thread did not have the credentials required to complete the
 118 operation.
 119 .El
 120 .Sh SEE ALSO
 121 .Xr cpuset 1 ,
 122 .Xr cpuset 2 ,
 123 .Xr cpuset_getid 2 ,
 124 .Xr cpuset_setid 2 ,
 125 .Xr pthread 3 ,
 126 .Xr pthread_attr_getaffinity_np 3 ,
 127 .Xr pthread_attr_setaffinity_np 3
 128 .Sh STANDARDS
 129 The
 130 .Nm pthread_getaffinity_np
 131 and
 132 .Nm pthread_setaffinity_np
 133 functions are non-standard
 134 .Fx
 135 extensions and may be not available on other operating systems.
 136 .Sh HISTORY
 137 The
 138 .Nm pthread_getaffinity_np
 139 and
 140 .Nm pthread_setaffinity_np
 141 function first appeared in
 142 .Fx 7.2 .
 143 .Sh AUTHORS
 144 .An -nosplit
 145 The
 146 .Nm pthread_getaffinity_np
 147 and
 148 .Nm pthread_setaffinity_np
 149 functions were written by
 150 .An David Xu Aq Mt davidxu@FreeBSD.org ,
 151 and this manpage was written by
 152 .An Xin LI Aq Mt delphij@FreeBSD.org .