draft/man2/sched_setaffinity.2

   1 .\" Copyright (C) 2002 Robert Love
   2 .\" and Copyright (C) 2006 Michael Kerrisk
   3 .\"
   4 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   5 .\" This is free documentation; you can redistribute it and/or
   6 .\" modify it under the terms of the GNU General Public License as
   7 .\" published by the Free Software Foundation; either version 2 of
   8 .\" the License, or (at your option) any later version.
   9 .\"
  10 .\" The GNU General Public License's references to "object code"
  11 .\" and "executables" are to be interpreted as the output of any
  12 .\" document formatting or typesetting system, including
  13 .\" intermediate and printed output.
  14 .\"
  15 .\" This manual is distributed in the hope that it will be useful,
  16 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 .\" GNU General Public License for more details.
  19 .\"
  20 .\" You should have received a copy of the GNU General Public
  21 .\" License along with this manual; if not, see
  22 .\" <http://www.gnu.org/licenses/>.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" 2002-11-19 Robert Love <rml@tech9.net> - initial version
  26 .\" 2004-04-20 mtk - fixed description of return value
  27 .\" 2004-04-22 aeb - added glibc prototype history
  28 .\" 2005-05-03 mtk - noted that sched_setaffinity may cause thread
  29 .\"     migration and that CPU affinity is a per-thread attribute.
  30 .\" 2006-02-03 mtk -- Major rewrite
  31 .\" 2008-11-12, mtk, removed CPU_*() macro descriptions to a
  32 .\" separate CPU_SET(3) page.
  33 .\"
  34 .\"*******************************************************************
  35 .\"
  36 .\" This file was generated with po4a. Translate the source file.
  37 .\"
  38 .\"*******************************************************************
  39 .\"
  40 .\" Japanese Version Copyright (c) 2003, 2005 Yuichi SATO
  41 .\"         all rights reserved.
  42 .\" Translated 2003-01-23, Yuichi SATO <ysato444@yahoo.co.jp>
  43 .\" Updated & Modified 2003-09-23, Yuichi SATO
  44 .\" Updated & Modified 2005-01-03, Yuichi SATO
  45 .\" Updated & Modified 2005-09-13, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  46 .\" Updated & Modified 2006-07-14, Akihiro MOTOKI, LDP v2.34
  47 .\" Updated & Modified 2008-12-24, Akihiro MOTOKI, LDP v3.14
  48 .\"
  49 .TH SCHED_SETAFFINITY 2 2014\-12\-31 Linux "Linux Programmer's Manual"
  50 .SH 名前
  51 sched_setaffinity, sched_getaffinity \- スレッドの CPU affinity マスクを設定・取得する
  52 .SH 書式
  53 .nf
  54 \fB#define _GNU_SOURCE\fP             /* feature_test_macros(7) 参照 */
  55 \fB#include <sched.h>\fP
  56 .sp
  57 \fBint sched_setaffinity(pid_t \fP\fIpid\fP\fB, size_t \fP\fIcpusetsize\fP\fB,\fP
  58 \fB                      const cpu_set_t *\fP\fImask\fP\fB);\fP
  59 .sp
  60 \fBint sched_getaffinity(pid_t \fP\fIpid\fP\fB, size_t \fP\fIcpusetsize\fP\fB,\fP
  61 \fB                      cpu_set_t *\fP\fImask\fP\fB);\fP
  62 .fi
  63 .SH 説明
  64 スレッドの CPU affinity (親和度) マスクは、そのスレッドが 実行を許可されている CPU の集合を決定する。
  65 マルチプロセッサシステムでは、CPU affinity マスクを設定することで 性能上のメリットを得られる可能性がある。 例えば、特定のスレッドを一つの
  66 CPU に括り付け (すなわち、そのスレッドの affinity マスクを一つの CPU に設定し)、 他の全てのスレッドの affinity
  67 マスクからその CPU を除外することで、 確実にそのスレッドの実行速度を最大にすることができる。 また、あるスレッドの実行を一つの CPU
  68 に限定することで、 一つの CPU での実行を停止してから別の CPU で実行を再開するときに発生する キャッシュ無効化 (cache
  69 invalidation) による性能面の劣化を避けることもできる。
  70
  71 CPU affinity マスクは「CPU の集合」を表す \fIcpu_set_t\fP 構造体で表現され、 \fIcpu_set_t\fP へのポインター
  72 \fImask\fP で指定される。 CPU 集合を操作するためのマクロ群については \fBCPU_SET\fP(3)  で記載されている。
  73
  74 \fBsched_setaffinity\fP()  は、スレッド ID が \fIpid\fP のスレッドの CPU affinity マスクを \fImask\fP
  75 で指定された値に設定する。 \fIpid\fP が 0 の場合、呼び出し元スレッドが使われる。 \fIcpusetsize\fP 引き数には \fImask\fP
  76 が指すデータの長さ (バイト単位) である。 通常は、この引き数には \fIsizeof(cpu_set_t)\fP を指定すればよい。
  77
  78 \fIpid\fP で指定されたスレッドが \fImask\fP で指定された CPU のいずれかで現在実行されていない場合、 そのスレッドは \fImask\fP
  79 で指定された CPU のいずれかに移動される。
  80
  81 \fBsched_getaffinity\fP()  は、 スレッド ID が \fIpid\fP のスレッドの affinity マスクを \fImask\fP が指す
  82 \fIcpu_set_t\fP 構造体に書き込む。 \fIcpusetsize\fP 引き数には \fImask\fP の (バイト単位の) 大きさを指定する。
  83 .SH 返り値
  84 成功した場合、 \fBsched_setaffinity\fP()  と \fBsched_getaffinity\fP()  は 0 を返す。 エラーの場合は
  85 \-1 を返し、 \fIerrno\fP を適切に設定する。
  86 .SH エラー
  87 .TP
  88 \fBEFAULT\fP
  89 指定されたメモリー番地が不正である。
  90 .TP
  91 \fBEINVAL\fP
  92 システム上に現在実際に存在し、かつ "cpuset" 機構が課す制限においてそのスレッドに対して許可されている プロセッサが、 affinity
  93 ビットマスク \fImask\fP に含まれていない。 "cpuset" 機構については \fBcpuset\fP(7)  を参照。
  94 .TP
  95 \fBEINVAL\fP
  96 (\fBsched_getaffinity\fP()  と、カーネル 2.6.9 以前の \fBsched_setaffinity\fP())
  97 \fIcpusetsize\fP がカーネルで使われている affinity マスクのサイズより小さい。
  98 .TP
  99 \fBEPERM\fP
 100 (\fBsched_setaffinity\fP())  呼び出し元のスレッドに適切な特権がなかった。 呼び出し元は、実効ユーザー ID が \fIpid\fP
 101 で識別されるスレッドの実ユーザー ID または実効ユーザー ID と同じであるか、 \fBCAP_SYS_NICE\fP ケーパビリティ
 102 (capability) を持たなければならない。
 103 .TP
 104 \fBESRCH\fP
 105 ID が \fIpid\fP のスレッドが見つからなかった。
 106 .SH バージョン
 107 CPU affinity システムコールは Linux kernel 2.5.8 で導入された。 これらのシステムコールのラッパー関数は glibc
 108 2.3 で導入された。 最初は、glibc のインターフェースには \fIunsigned int\fP 型の \fIcpusetsize\fP
 109 引き数が入っていた。 glibc 2.3.3 では \fIcpusetsize\fP 引き数が削除されたが、glibc 2.3.4 で \fIsize_t\fP
 110 型で復活した。
 111 .SH 準拠
 112 これらのシステムコールは Linux 固有である。
 113 .SH 注意
 114 \fBsched_setaffinity\fP()  を呼び出した後は、スレッドが実際に実行される CPU の集合は、 \fImask\fP
 115 引き数で指定された集合と、システム上に実際に存在する CPU の集合の 共通集合 (AND) となる。 "cpuset"
 116 機構が使用されている場合には、スレッドが動作する CPU 集合 に対してシステムはさらに制限を加えるかもしれない ("cpuset" 機構については
 117 \fBcpuset\fP(7)  を参照)。 スレッドが動作する実際の CPU 集合に対する制限はカーネルにより 暗黙のうちに適用される。
 118
 119 システムで利用可能な CPU 数を判定する方法はいくつかある。 \fI/proc/cpuinfo\fP の内容を調べる、 \fBsysconf\fP(3) を使って
 120 \fB_SC_NPROCESSORS_CONF\fP と \fB_SC_NPROCESSORS_ONLN\fP の値を取得する、
 121 \fI/sys/devices/system/cpu/\fP の CPU ディレクトリの一覧を調べる、などがある。
 122
 123 \fBsched\fP(7) に Linux のスケジューリング方式についての説明がある。
 124 .PP
 125 affinity マスクはスレッド単位の属性で、スレッドグループの 各スレッド単位に独立して調整することができる。 \fBgettid\fP(2)
 126 コールからの返り値をこのコールの \fIpid\fP 引き数として渡すことができる。 \fIpid\fP に 0 を指定すると呼び出し元のスレッドの属性が設定され、
 127 \fBgetpid\fP(2)  コールからの返り値を \fIpid\fP に指定するとスレッドグループのメインスレッドの属性が設定される (POSIX スレッド
 128 API を使用している場合、 \fBsched_setaffinity\fP()  の代わりに \fBpthread_setaffinity_np\fP(3)
 129 を使用すること)。
 130
 131 \fBfork\fP(2)  経由で生成された子プロセスは親プロセスの CPU affinity マスクを継承する。 affinity マスクは
 132 \fBexecve\fP(2)  の前後で保存される。
 133 .SS "C ライブラリとカーネル ABI の違い"
 134 このマニュアルページでは CPU affinity コールの glibc インターフェースを
 135 説明している。実際のシステムコールインターフェースは少し違っており、 実際の実装では CPU 集合は簡単なビットマスクであるという実状を反映し、
 136 \fImask\fP の型が \fIunsigned long\ *\fP となっている。 成功時には、生の \fBsched_getaffinity\fP()
 137 システムコール自身は \fIcpumask_t\fP データ型の (バイト単位の) 大きさを返す。 \fIcpumask_t\fP はカーネル内部で CPU
 138 集合のビットマスクを表現するのに 使われているデータ型である。
 139 .SH 関連項目
 140 .ad l
 141 .nh
 142 \fBlscpu\fP(1), \fBnproc\fP(1), \fBtaskset\fP(1), \fBclone\fP(2), \fBgetcpu\fP(2),
 143 \fBgetpriority\fP(2), \fBgettid\fP(2), \fBnice\fP(2), \fBsched_get_priority_max\fP(2),
 144 \fBsched_get_priority_min\fP(2), \fBsched_getscheduler\fP(2),
 145 \fBsched_setscheduler\fP(2), \fBsetpriority\fP(2), \fBCPU_SET\fP(3),
 146 \fBpthread_setaffinity_np\fP(3), \fBsched_getcpu\fP(3), \fBcapabilities\fP(7),
 147 \fBcpuset\fP(7), \fBsched\fP(7)
 148 .SH この文書について
 149 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.79 の一部
 150 である。プロジェクトの説明とバグ報告に関する情報は
 151 http://www.kernel.org/doc/man\-pages/ に書かれている。