/share/man/man3/pthread_affinity_np.3

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 156 lines · 156 code · 0 blank · 0 comment · 0 complexity · 3cdfe46856ad81a026d536e6e9933dfd MD5 · raw file

  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 March 23, 2010
  29. .Dt PTHREAD_AFFINITY_NP 3
  30. .Os
  31. .Sh NAME
  32. .Nm pthread_getaffinity_np ,
  33. .Nm pthread_setaffinity_np
  34. .Nd manage CPU affinity
  35. .Sh LIBRARY
  36. .Lb libpthread
  37. .Sh SYNOPSIS
  38. .In pthread_np.h
  39. .Ft int
  40. .Fn pthread_getaffinity_np "pthread_t td" "size_t cpusetsize" "cpuset_t *cpusetp"
  41. .Ft int
  42. .Fn pthread_setaffinity_np "pthread_t td" "size_t cpusetsize" "const cpuset_t *cpusetp"
  43. .Sh DESCRIPTION
  44. .Fn pthread_getaffinity_np
  45. and
  46. .Fn pthread_setaffinity_np
  47. allow the manipulation of sets of CPUs available to the specified thread.
  48. .Pp
  49. Masks of type
  50. .Ft cpuset_t
  51. are composed using the
  52. .Xr CPU_SET 3
  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_getaffinity_np
  58. even if the result set would fit within the user supplied set.
  59. Calls to
  60. .Fn pthread_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_getaffinity_np
  74. retrieves the
  75. mask from the thread specified by
  76. .Fa td ,
  77. and stores it in the space provided by
  78. .Fa cpusetp .
  79. .Pp
  80. .Fn pthread_setaffinity_np
  81. attempts to set the mask for the thread specified by
  82. .Fa td
  83. to the value in
  84. .Fa cpusetp .
  85. .Sh RETURN VALUES
  86. If successful, the
  87. .Fn pthread_getaffinity_np
  88. and
  89. .Fn pthread_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_getaffinity_np
  96. and
  97. .Fn pthread_setaffinity_np
  98. functions may fail if:
  99. .Bl -tag -width Er
  100. .It Bq Er EDEADLK
  101. The
  102. .Fn pthread_setaffinity_np
  103. call would leave a thread without a valid CPU to run on because the set
  104. does not overlap with the thread's anonymous mask.
  105. .It Bq Er EFAULT
  106. The
  107. .Fa cpusetp
  108. pointer passed was invalid.
  109. .It Bq Er ESRCH
  110. The thread specified by the
  111. .Fa td
  112. argument could not be found.
  113. .It Bq Er ERANGE
  114. The
  115. .Fa cpusetsize
  116. was either preposterously large or smaller than the kernel set size.
  117. .It Bq Er EPERM
  118. The calling thread did not have the credentials required to complete the
  119. operation.
  120. .El
  121. .Sh SEE ALSO
  122. .Xr cpuset 1 ,
  123. .Xr cpuset 2 ,
  124. .Xr cpuset_getid 2 ,
  125. .Xr cpuset_setid 2 ,
  126. .Xr CPU_SET 3 ,
  127. .Xr pthread 3 ,
  128. .Xr pthread_attr_getaffinity_np 3 ,
  129. .Xr pthread_attr_setaffinity_np 3
  130. .Sh STANDARDS
  131. The
  132. .Nm pthread_getaffinity_np
  133. and
  134. .Nm pthread_setaffinity_np
  135. functions are non-standard
  136. .Fx
  137. extensions and may be not available on other operating systems.
  138. .Sh HISTORY
  139. The
  140. .Nm pthread_getaffinity_np
  141. and
  142. .Nm pthread_setaffinity_np
  143. function first appeared in
  144. .Fx 7.2 .
  145. .Sh AUTHORS
  146. .An -nosplit
  147. The
  148. .Nm pthread_getaffinity_np
  149. and
  150. .Nm pthread_setaffinity_np
  151. functions were written by
  152. .An David Xu
  153. .Aq davidxu@FreeBSD.org ,
  154. and this manpage was written by
  155. .An Xin LI
  156. .Aq delphij@FreeBSD.org .