release/man2/sched_setattr.2

   1 .\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\" and Copyright (C) 2014 Peter Zijlstra <peterz@infradead.org>
   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 .\"*******************************************************************
  27 .\"
  28 .\" This file was generated with po4a. Translate the source file.
  29 .\"
  30 .\"*******************************************************************
  31 .TH SCHED_SETATTR 2 2014\-10\-02 Linux "Linux Programmer's Manual"
  32 .SH 名前
  33 sched_setattr, sched_getattr \- スケジューリングポリシーと属性の設定と取得を行なう
  34 .SH 書式
  35 .nf
  36 \fB#include <sched.h>\fP
  37
  38 \fBint sched_setattr(pid_t \fP\fIpid\fP\fB, const struct sched_attr *\fP\fIattr\fP\fB,\fP
  39 \fB                  unsigned int \fP\fIflags\fP\fB);\fP
  40
  41 \fBint sched_getattr(pid_t \fP\fIpid\fP\fB, const struct sched_attr *\fP\fIattr\fP\fB,\fP
  42 \fB                  unsigned int \fP\fIsize\fP\fB, unsigned int \fP\fIflags\fP\fB);\fP
  43 .fi
  44 .\" FIXME . Add feature test macro requirements
  45 .SH 説明
  46 .SS sched_setattr()
  47 \fBsched_setattr\fP() システムコールは、 \fIpid\fP で指定された ID
  48 を持つスレッドのスケジューリングポリシーと関連する属性を設定する。 \fIpid\fP が 0
  49 の場合、呼び出したスレッド自身のスケジューリングポリシーと属性が設定される。
  50
  51 現在のところ、 Linux では、 以下の「通常」の (つまり、リアルタイムではない) スケジューリングポリシーが、 \fIpolicy\fP
  52 に指定できる値としてサポートされている。
  53 .TP  14
  54 \fBSCHED_OTHER\fP
  55 .\" In the 2.6 kernel sources, SCHED_OTHER is actually called
  56 .\" SCHED_NORMAL.
  57 標準の、ラウンドロビンによる時分割型のスケジューリングポリシー。
  58 .TP
  59 \fBSCHED_BATCH\fP
  60 「バッチ」形式でのプロセスの実行用。
  61 .TP
  62 \fBSCHED_IDLE\fP
  63 「非常に」低い優先度で動作するバックグラウンドジョブ用。
  64 .PP
  65 どの実行可能スレッドを選択するかについて、より正確な制御を必要とする 時間の制約が厳しい特別なアプリケーション用として、
  66 いろいろな「リアルタイム」ポリシーもサポートされている。 プロセスがこれらのポリシーをいつ使用できるかを決めるルールについては、\fBsched\fP(7)
  67 を参照。 \fIpolicy\fP には以下のリアルタイムポリシーを指定できる。
  68 .TP  14
  69 \fBSCHED_FIFO\fP
  70 ファーストイン、ファーストアウト型のポリシー。
  71 .TP
  72 \fBSCHED_RR\fP
  73 ラウンドロビン型のポリシー。
  74 .PP
  75 Linux では以下のポリシーも提供されている。
  76 .TP  14
  77 \fBSCHED_DEADLINE\fP
  78 デッドライン (応答期限) ベースのスケジューリングポリシー。詳細は \fBsched\fP(7) を参照。
  79 .PP
  80 \fIattr\fP 引き数は、 指定したスレッドの新しいスケジューリングポリシーと属性を定義した構造体へのポインターである。 この構造体は以下の形式である。
  81
  82 .in +4n
  83 .nf
  84 struct sched_attr {
  85     u32 size;              /* この構造体のサイズ */
  86     u32 sched_policy;      /* ポリシー (SCHED_*) */
  87     u64 sched_flags;       /* フラグ */
  88     s32 sched_nice;        /* nice 値 (SCHED_OTHER,
  89                               SCHED_BATCH) */
  90     u32 sched_priority;    /* 静的優先度 (SCHED_FIFO,
  91                               SCHED_RR) */
  92     /* 残りのフィールドは SCHED_DEADLINE 用である */
  93     u64 sched_runtime;
  94     u64 sched_deadline;
  95     u64 sched_period;
  96 };
  97 .fi
  98 .in
  99
 100 この構造体のフィールドは以下の通りである。
 101 .TP
 102 \fBsize\fP
 103 このフィールドには、 構造体のバイト単位のサイズを設定する。 \fIsizeof(struct sched_attr)\fP を指定すればよい。
 104 指定された構造体がカーネル構造体よりも小さい場合、 追加となるフィールドは 0 とみなされる。 指定された構造体がカーネル構造体よりも大きい場合、
 105 カーネルは追加のフィールドが 0 であるかを検査する。 0 でない場合は \fBsched_setattr\fP() はエラー \fBE2BIG\fP
 106 で失敗するので、 \fIsize\fP をカーネル構造体のサイズに更新する必要がある。
 107 .IP
 108 ユーザー空間の \fIsched_attr\fP 構造体のサイズがカーネル構造体のサイズと一致しなかった場合の上記の動作は、
 109 このインタフェースを将来拡張できるようにするためである。 サイズが大きい構造体を渡す行儀の良くないアプリケーションも、 将来カーネルの
 110 \fIsched_attr\fP 構造体のサイズが大きくなったとしてもおかしくならない。 この仕組みにより、 将来的には、 大きなユーザー空間
 111 \fIsched_attr\fP 構造体があることを知っているアプリケーションで、
 112 大きいサイズの構造体に対応していない古いカーネル上で動作しているかを判定することができる。
 113 .TP
 114 \fIsched_policy\fP
 115 このフィールドはスケジューリングポリシーを指定する。 上記のリストにある \fBSCHED_*\fP 値のいずれかを指定する。
 116 .TP
 117 \fIsched_flags\fP
 118 このフィールドはスケジューリング動作の制御を行う。 現在のところ、サポートされているフラグは \fBSCHED_FLAG_RESET_ON_FORK\fP
 119 の一つだけである。 このフラグが指定されると、 \fBfork\fP(2) で作成された子プロセスは特権が必要なスケジューリングポリシーを継承しない。 詳細は
 120 \fBsched\fP(7) を参照。
 121 .TP
 122 \fIsched_nice\fP
 123 このフィールドは、 \fIsched_policy\fP に \fBSCHED_OTHER\fP か \fBSCHED_BATCH\fP が指定された場合に設定される
 124 nice 値を指定する。 nice 値は \-20 (高優先度) から +19 (低優先度) の範囲の数値である。 \fBsetpriority\fP(2)
 125 を参照。
 126 .TP
 127 \fIsched_priority\fP
 128 このフィールドは、 \fIsched_policy\fP に \fBSCHED_FIFO\fP か \fBSCHED_RR\fP
 129 が指定された場合に設定される静的優先度を指定する。 これらのポリシーで指定できる優先度の範囲は、
 130 \fBsched_get_priority_min\fP(2) と \fBsched_get_priority_max\fP(2) を使って判定できる。
 131 他のポリシーでは、 このフィールドには 0 を指定しなければならない。
 132 .TP
 133 \fIsched_runtime\fP
 134 このフィールドは、 デッドラインスケジューリングの "Runtime" パラメーターを指定する。 この値はナノ秒単位で表現される。 このフィールドと次の
 135 2 つのフィールドは \fBSCHED_DEADLINE\fP スケジューリングにおいてのみ使用される。 詳細は \fBsched\fP(7) を参照。
 136 .TP
 137 \fIsched_deadline\fP
 138 このフィールドは、 デッドラインスケジューリングの "Deadline" パラメーターを指定する。 この値はナノ秒単位で表現される。
 139 .TP
 140 \fIsched_period\fP
 141 このフィールドは、 デッドラインスケジューリングの "Period" パラメーターを指定する。 この値はナノ秒単位で表現される。
 142 .PP
 143 .\"
 144 .\"
 145 \fIflags\fP 引き数は、このインタフェースの将来の拡張のために用意されている。 現在の実装では 0 を指定しなければならない。
 146 .SS sched_getattr()
 147 \fBsched_getattr\fP() システムコールは、 \fIpid\fP で指定された ID
 148 を持つスレッドのスケジューリングポリシーと関連する属性を取得する。 \fIpid\fP が 0
 149 の場合、呼び出したスレッド自身のスケジューリングポリシーと関連する属性を取得する。
 150
 151 \fIsize\fP 引き数には、 ユーザー空間での \fIsched_attr\fP 構造体の大きさを設定する。 この値は、 少なくとも初期バージョンの
 152 \fIsched_attr\fP 構造体のサイズでなければならない。 そうでなかった場合、 エラー \fBEINVAL\fP で呼び出しが失敗する。
 153
 154 取得したスケジューリング属性は、 \fIattr\fP が指す \fIsched_attr\fP 構造体の各フィールドに格納される。 カーネルは
 155 \fIattr.size\fP に \fIsched_attr\fP 構造体のサイズを設定する。
 156
 157 呼び出し側が提供した \fIattr\fP バッファがカーネルの \fIsched_attr\fP 構造体よりも大きい場合、
 158 ユーザー空間構造体の残りのバイトは変更されない。 呼び出し側が提供した構造体がカーネルの \fIsched_attr\fP 構造体よりも小さく、
 159 カーネルが値を返すのにもっと大きな空間が必要な場合、 \fBsched_getattr\fP() はエラー \fBE2BIG\fP で失敗する。
 160 \fBsched_setattr\fP() と同様、 この動作はこのインタフェースの将来の拡張性を考慮してのものである。
 161
 162 \fIflags\fP 引き数は、このインタフェースの将来の拡張のために用意されている。 現在の実装では 0 を指定しなければならない。
 163 .SH 返り値
 164 成功した場合は \fBsched_setattr\fP()  と \fBsched_getattr\fP()  は 0 を返す。 エラーの場合は \-1 が返され、
 165 エラーの原因を示す値が \fIerrno\fP に設定される。
 166 .SH エラー
 167 \fBsched_getattr\fP() と \fBsched_setattr\fP() の両方が以下の理由で失敗する。
 168 .TP
 169 \fBEINVAL\fP
 170 \fIattr\fP が NULL である。 \fIpid\fP が負である。 \fIflags\fP が 0 以外である。
 171 .TP
 172 \fBESRCH\fP
 173 ID が \fIpid\fP のスレッドが見つからなかった。
 174 .PP
 175 さらに、 \fBsched_getattr\fP() は以下の理由でも失敗する。
 176 .TP
 177 \fBE2BIG\fP
 178 \fIsize\fP と \fIattr\fP で指定されたバッファーが小さすぎる。
 179 .TP
 180 \fBEINVAL\fP
 181 \fIsize\fP が無効である。つまり、 最初のバージョンの \fIsched_attr\fP 構造体 (48 バイト) よりも小さいか、
 182 システムのページサイズよりも大きい。
 183 .PP
 184 さらに、 \fBsched_setattr\fP() は以下の理由でも失敗する。
 185 .TP
 186 \fBE2BIG\fP
 187 \fIsize\fP と \fIattr\fP で指定されたバッファがカーネル構造体よりも大きく、 一つ以上の超過バイトが 0 でなかった。
 188 .TP
 189 \fBEBUSY\fP
 190 \fBSCHED_DEADLINE\fP の流入制御の失敗については \fBsched\fP(7) を参照。
 191 .TP
 192 \fBEINVAL\fP
 193 \fIattr.sched_policy\fP が認識できるポリシーではない。 \fIattr.sched_flags\fP に
 194 \fBSCHED_FLAG_RESET_ON_FORK\fP 以外のフラグが含まれている。 \fIattr.sched_priority\fP が無効である。
 195 \fIattr.sched_policy\fP が \fBSCHED_DEADLINE\fP で、 \fIattr\fP
 196 に指定されたデッドラインスケジューリングパラメーターが無効である。
 197 .TP
 198 \fBEPERM\fP
 199 呼び出した元が適切な特権を持っていない。
 200 .TP
 201 \fBEPERM\fP
 202 呼び出し元の CPU affinity マスクにシステムの全ての CPU のうち含まれていないものがある
 203 (\fBsched_setaffinity\fP(2) を参照)。
 204 .SH バージョン
 205 .\" FIXME . Add glibc version
 206 これらのシステムコールは Linux 3.14 で初めて登場した。
 207 .SH 準拠
 208 これらのシステムコールは非標準の Linux による拡張である。
 209 .SH 注意
 210 \fBsched_setattr\fP() は、\fBsched_setscheduler\fP(2), \fBsched_setparam\fP(2),
 211 \fBnice\fP(2) の機能および \fBsetpriority\fP の一部機能を持つ (ただし、\fBsetpriority\fP(2)
 212 の、指定されたユーザーに所属するすべてのプロセスまたは指定されたグループのすべてのプロセスの優先度を設定する機能は除く)。 同様に、
 213 \fBsched_getattr\fP() は \fBsched_getscheduler\fP(2), \fBsched_getparam\fP(2) の機能および
 214 \fBgetpriority\fP(2) の一部機能を持つ。
 215 .SH バグ
 216 .\" FIXME . patch sent to Peter Zijlstra
 217 .\" In Linux versions up to up 3.15,
 218 .\" FIXME . patch from Peter Zijlstra pending
 219 .\" .BR sched_setattr ()
 220 .\" allowed a negative
 221 .\" .I attr.sched_policy
 222 .\" value.
 223 バージョン 3.15 までの Linux では、 \fBsched_settattr\fP() は、 エラーの節に書かれている \fBE2BIG\fP
 224 の場合にエラー\fBEFAULT\fP で失敗していた。
 225 .SH 関連項目
 226 .ad l
 227 .nh
 228 \fBchrt\fP(1), \fBnice\fP(2), \fBsched_get_priority_max\fP(2),
 229 \fBsched_get_priority_min\fP(2), \fBsched_getaffinity\fP(2),
 230 \fBsched_getscheduler\fP(2), \fBsched_getparam\fP(2), \fBsched_rr_get_interval\fP(2),
 231 \fBsched_setaffinity\fP(2), \fBsched_setscheduler\fP(2), \fBsched_setparam\fP(2),
 232 \fBsched_yield\fP(2), \fBsetpriority\fP(2), \fBpthread_getschedparam\fP(3),
 233 \fBpthread_setschedparam\fP(3), \fBpthread_setschedprio\fP(3), \fBcapabilities\fP(7),
 234 \fBcpuset\fP(7), \fBsched\fP(7)
 235 .ad
 236 .SH この文書について
 237 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.78 の一部
 238 である。プロジェクトの説明とバグ報告に関する情報は
 239 http://www.kernel.org/doc/man\-pages/ に書かれている。