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