man3/pthread_attr_setaffinity_np.3

   1 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .TH PTHREAD_ATTR_SETAFFINITY_NP 3 2021-03-22 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 pthread_attr_setaffinity_np, pthread_attr_getaffinity_np \- set/get
  29 CPU affinity attribute in thread attributes object
  30 .SH SYNOPSIS
  31 .nf
  32 .BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
  33 .B #include <pthread.h>
  34 .PP
  35 .BI "int pthread_attr_setaffinity_np(pthread_attr_t *" attr ,
  36 .BI "                   size_t " cpusetsize ", const cpu_set_t *" cpuset );
  37 .BI "int pthread_attr_getaffinity_np(const pthread_attr_t *" attr ,
  38 .BI "                   size_t " cpusetsize ", cpu_set_t *" cpuset );
  39 .PP
  40 Compile and link with \fI\-pthread\fP.
  41 .fi
  42 .SH DESCRIPTION
  43 The
  44 .BR pthread_attr_setaffinity_np ()
  45 function
  46 sets the CPU affinity mask attribute of the
  47 thread attributes object referred to by
  48 .I attr
  49 to the value specified in
  50 .IR cpuset .
  51 This attribute determines the CPU affinity mask
  52 of a thread created using the thread attributes object
  53 .IR attr .
  54 .PP
  55 The
  56 .BR pthread_attr_getaffinity_np ()
  57 function
  58 returns the CPU affinity mask attribute of the thread attributes object
  59 referred to by
  60 .IR attr
  61 in the buffer pointed to by
  62 .IR cpuset .
  63 .PP
  64 The argument
  65 .I cpusetsize
  66 is the length (in bytes) of the buffer pointed to by
  67 .IR cpuset .
  68 Typically, this argument would be specified as
  69 .IR sizeof(cpu_set_t) .
  70 .PP
  71 For more details on CPU affinity masks, see
  72 .BR sched_setaffinity (2).
  73 For a description of a set of macros
  74 that can be used to manipulate and inspect CPU sets, see
  75 .BR CPU_SET (3).
  76 .SH RETURN VALUE
  77 On success, these functions return 0;
  78 on error, they return a nonzero error number.
  79 .SH ERRORS
  80 .TP
  81 .BR EINVAL
  82 .RB ( pthread_attr_setaffinity_np ())
  83 .I cpuset
  84 specified a CPU that was outside the set supported by the kernel.
  85 (The kernel configuration option
  86 .BR CONFIG_NR_CPUS
  87 defines the range of the set supported by the kernel data type
  88 .\" cpumask_t
  89 used to represent CPU sets.)
  90 .\" The raw sched_getaffinity() system call returns the size (in bytes)
  91 .\" of the cpumask_t type.
  92 .TP
  93 .B EINVAL
  94 .RB ( pthread_attr_getaffinity_np ())
  95 A CPU in the affinity mask of the thread attributes object referred to by
  96 .I attr
  97 lies outside the range specified by
  98 .IR cpusetsize
  99 (i.e.,
 100 .IR cpuset / cpusetsize
 101 is too small).
 102 .TP
 103 .B ENOMEM
 104 .RB ( pthread_attr_setaffinity_np ())
 105 Could not allocate memory.
 106 .SH VERSIONS
 107 These functions are provided by glibc since version 2.3.4.
 108 .SH ATTRIBUTES
 109 For an explanation of the terms used in this section, see
 110 .BR attributes (7).
 111 .ad l
 112 .nh
 113 .TS
 114 allbox;
 115 lbx lb lb
 116 l l l.
 117 Interface       Attribute       Value
 118 T{
 119 .BR pthread_attr_setaffinity_np (),
 120 .BR pthread_attr_getaffinity_np ()
 121 T}      Thread safety   MT-Safe
 122 .TE
 123 .hy
 124 .ad
 125 .sp 1
 126 .SH CONFORMING TO
 127 These functions are nonstandard GNU extensions;
 128 hence the suffix "_np" (nonportable) in the names.
 129 .SH NOTES
 130 In glibc 2.3.3 only,
 131 versions of these functions were provided that did not have a
 132 .I cpusetsize
 133 argument.
 134 Instead the CPU set size given to the underlying system calls was always
 135 .IR sizeof(cpu_set_t) .
 136 .SH SEE ALSO
 137 .BR sched_setaffinity (2),
 138 .BR pthread_attr_init (3),
 139 .BR pthread_setaffinity_np (3),
 140 .BR cpuset (7),
 141 .BR pthreads (7)