man3/pthread_attr_setaffinity_np.3

   1 '\" t
   2 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
   3 .\"     <mtk.manpages@gmail.com>
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .TH pthread_attr_setaffinity_np 3 (date) "Linux man-pages (unreleased)"
   8 .SH NAME
   9 pthread_attr_setaffinity_np, pthread_attr_getaffinity_np \- set/get
  10 CPU affinity attribute in thread attributes object
  11 .SH LIBRARY
  12 POSIX threads library
  13 .RI ( libpthread ", " \-lpthread )
  14 .SH SYNOPSIS
  15 .nf
  16 .BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
  17 .B #include <pthread.h>
  18 .PP
  19 .BI "int pthread_attr_setaffinity_np(pthread_attr_t *" attr ,
  20 .BI "                   size_t " cpusetsize ", const cpu_set_t *" cpuset );
  21 .BI "int pthread_attr_getaffinity_np(const pthread_attr_t *" attr ,
  22 .BI "                   size_t " cpusetsize ", cpu_set_t *" cpuset );
  23 .fi
  24 .SH DESCRIPTION
  25 The
  26 .BR pthread_attr_setaffinity_np ()
  27 function
  28 sets the CPU affinity mask attribute of the
  29 thread attributes object referred to by
  30 .I attr
  31 to the value specified in
  32 .IR cpuset .
  33 This attribute determines the CPU affinity mask
  34 of a thread created using the thread attributes object
  35 .IR attr .
  36 .PP
  37 The
  38 .BR pthread_attr_getaffinity_np ()
  39 function
  40 returns the CPU affinity mask attribute of the thread attributes object
  41 referred to by
  42 .I attr
  43 in the buffer pointed to by
  44 .IR cpuset .
  45 .PP
  46 The argument
  47 .I cpusetsize
  48 is the length (in bytes) of the buffer pointed to by
  49 .IR cpuset .
  50 Typically, this argument would be specified as
  51 .IR sizeof(cpu_set_t) .
  52 .PP
  53 For more details on CPU affinity masks, see
  54 .BR sched_setaffinity (2).
  55 For a description of a set of macros
  56 that can be used to manipulate and inspect CPU sets, see
  57 .BR CPU_SET (3).
  58 .SH RETURN VALUE
  59 On success, these functions return 0;
  60 on error, they return a nonzero error number.
  61 .SH ERRORS
  62 .TP
  63 .B EINVAL
  64 .RB ( pthread_attr_setaffinity_np ())
  65 .I cpuset
  66 specified a CPU that was outside the set supported by the kernel.
  67 (The kernel configuration option
  68 .B CONFIG_NR_CPUS
  69 defines the range of the set supported by the kernel data type
  70 .\" cpumask_t
  71 used to represent CPU sets.)
  72 .\" The raw sched_getaffinity() system call returns the size (in bytes)
  73 .\" of the cpumask_t type.
  74 .TP
  75 .B EINVAL
  76 .RB ( pthread_attr_getaffinity_np ())
  77 A CPU in the affinity mask of the thread attributes object referred to by
  78 .I attr
  79 lies outside the range specified by
  80 .I cpusetsize
  81 (i.e.,
  82 .IR cpuset / cpusetsize
  83 is too small).
  84 .TP
  85 .B ENOMEM
  86 .RB ( pthread_attr_setaffinity_np ())
  87 Could not allocate memory.
  88 .SH VERSIONS
  89 These functions are provided since glibc 2.3.4.
  90 .SH ATTRIBUTES
  91 For an explanation of the terms used in this section, see
  92 .BR attributes (7).
  93 .ad l
  94 .nh
  95 .TS
  96 allbox;
  97 lbx lb lb
  98 l l l.
  99 Interface       Attribute       Value
 100 T{
 101 .BR pthread_attr_setaffinity_np (),
 102 .BR pthread_attr_getaffinity_np ()
 103 T}      Thread safety   MT-Safe
 104 .TE
 105 .hy
 106 .ad
 107 .sp 1
 108 .SH STANDARDS
 109 These functions are nonstandard GNU extensions;
 110 hence the suffix "_np" (nonportable) in the names.
 111 .SH NOTES
 112 In glibc 2.3.3 only,
 113 versions of these functions were provided that did not have a
 114 .I cpusetsize
 115 argument.
 116 Instead the CPU set size given to the underlying system calls was always
 117 .IR sizeof(cpu_set_t) .
 118 .SH SEE ALSO
 119 .BR sched_setaffinity (2),
 120 .BR pthread_attr_init (3),
 121 .BR pthread_setaffinity_np (3),
 122 .BR cpuset (7),
 123 .BR pthreads (7)