release/man2/ioprio_set.2

   1 .\" Copyright (c) International Business Machines orp., 2006
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
   4 .\" This program is free software; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\"
   9 .\" This program is distributed in the hope that it will be useful,
  10 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
  12 .\" the GNU General Public License for more details.
  13 .\"
  14 .\" You should have received a copy of the GNU General Public
  15 .\" License along with this manual; if not, see
  16 .\" <http://www.gnu.org/licenses/>.
  17 .\" %%%LICENSE_END
  18 .\"
  19 .\" HISTORY:
  20 .\" 2006-04-27, created by Eduardo M. Fleury <efleury@br.ibm.com>
  21 .\" with various additions by Michael Kerrisk <mtk.manpages@gmail.com>
  22 .\"
  23 .\"
  24 .\"*******************************************************************
  25 .\"
  26 .\" This file was generated with po4a. Translate the source file.
  27 .\"
  28 .\"*******************************************************************
  29 .TH IOPRIO_SET 2 2013\-02\-12 Linux "Linux Programmer's Manual"
  30 .SH 名前
  31 ioprio_get, ioprio_set \- I/O スケジューリングクラスと優先度の設定/取得
  32 .SH 書式
  33 .nf
  34 \fBint ioprio_get(int \fP\fIwhich\fP\fB, int \fP\fIwho\fP\fB);\fP
  35 \fBint ioprio_set(int \fP\fIwhich\fP\fB, int \fP\fIwho\fP\fB, int \fP\fIioprio\fP\fB);\fP
  36 .fi
  37
  38 \fI注意\fP: これらのシステムコールには glibc ラッパー関数は存在しない。 「注意」の節を参照。
  39 .SH 説明
  40 システムコール \fBioprio_get\fP()  / \fBioprio_set\fP()  は、(1つ以上の) スレッドの I/O スケジューリングクラスと
  41 優先度の取得/設定を行う。
  42
  43 \fIwhich\fP と \fIwho\fP 引き数でシステムコールの操作対象となるスレッドを指示する。 \fIwhich\fP 引き数は、 \fIwho\fP
  44 をどのように解釈するかを決めるもので、以下のいずれか一つを指定する。
  45 .TP
  46 \fBIOPRIO_WHO_PROCESS\fP
  47 \fIwho\fP は特定のプロセスやスレッドを特定するためのプロセス ID かスレッド ID である。 \fIwho\fP が 0
  48 の場合、呼び出し元のスレッドに対して操作が行われる。
  49 .TP
  50 \fBIOPRIO_WHO_PGRP\fP
  51 \fIwho\fP はプロセスグループ ID であり、プロセスグループの全メンバが対象となる。 \fIwho\fP が 0 の場合、
  52 呼び出し元がメンバーとなっているプロセスグループに対して操作が行われる。
  53 .TP
  54 \fBIOPRIO_WHO_USER\fP
  55 .\" FIXME who==0 needs to be documented,
  56 .\" See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=652443
  57 \fIwho\fP はユーザID であり、実 UID に一致する全プロセスが対象となる。
  58 .PP
  59 \fBioprio_get\fP()  の呼び出し時に \fIwhich\fP に \fBIOPRIO_WHO_PGRP\fP か \fBIOPRIO_WHO_USER\fP
  60 が指定され、 \fIwho\fP に一致するプロセスが複数あった場合、 一致するプロセス全体の中で最も高い優先度が返される。
  61 優先度が高いとは、より高い優先度クラスに属している (\fBIOPRIO_CLASS_RT\fP が最も高い優先度クラスで、
  62 \fBIOPRIO_CLASS_IDLE\fP が最も低い)、もしくは 同じ優先度クラスに属しているが優先度レベルが高い
  63 (優先度番号が小さい方が優先度レベルが高いことを意味する)、 ということである。
  64
  65 \fBioprio_set\fP()  に渡す \fIioprio\fP 引き数は、対象となるプロセスに割り当てるスケジューリングクラスと
  66 優先度の両方を指定するビットマスクである。 \fIioprio\fP の値を組み立てたり解釈するのに、以下のマクロが利用できる。
  67 .TP
  68 \fBIOPRIO_PRIO_VALUE(\fP\fIclass\fP\fB, \fP\fIdata\fP\fB)\fP
  69 スケジューリングクラス \fIclass\fP と優先度 (\fIdata\fP)  を与えると、このマクロは 2つの値を組み合わせて、 \fIioprio\fP
  70 値を生成し、マクロの結果として返す。
  71 .TP
  72 \fBIOPRIO_PRIO_CLASS(\fP\fImask\fP\fB)\fP
  73 \fImask\fP (\fIioprio\fP 値) を与えると、このマクロは I/O クラス要素、つまり \fBIOPRIO_CLASS_RT\fP,
  74 \fBIOPRIO_CLASS_BE\fP, \fBIOPRIO_CLASS_IDLE\fP のいずれか一つの値を返す。
  75 .TP
  76 \fBIOPRIO_PRIO_DATA(\fP\fImask\fP\fB)\fP
  77 \fImask\fP (\fIioprio\fP 値) を与えると、このマクロは優先度 (\fIdata\fP)  要素を返す。
  78 .PP
  79 スケジューリングクラスと優先度に関する詳しい情報は、 「備考」の節を参照のこと。
  80
  81 I/O 優先度は読み出しと同期書き込み (\fBO_DIRECT\fP, \fBO_SYNC\fP)  に対応している。 I/O
  82 優先度は非同期書き込みには対応していない。なぜなら、 非同期書き込みはメモリ書き換えを行うプログラムの動作 (context) とは
  83 関係なく発行され、そのためプログラム単位の優先度は適用されないから である。
  84 .SH 返り値
  85 成功すると、 \fBioprio_get\fP()  は、 \fIwhich\fP と \fIwho\fP で指定された基準に合致した全プロセスで最も高い I/O
  86 優先度を持つプロセスの \fIioprio\fP 値を返す。 エラーの場合、\-1 を返し、 \fIerrno\fP にエラーを示す値を設定する。
  87 .PP
  88 成功すると、 \fBioprio_set\fP()  は 0 を返す。 エラーの場合、\-1 を返し、 \fIerrno\fP にエラーを示す値を設定する。
  89 .SH エラー
  90 .TP
  91 \fBEINVAL\fP
  92 \fIwhich\fP か \fIioprio\fP の値が不正である。 \fIioprio\fP 用に指定可能なスケジューラクラスと優先度レベルについては
  93 「備考」を参照のこと。
  94 .TP
  95 \fBEPERM\fP
  96 呼び出し元プロセスが、指定されたプロセスに \fIioprio\fP を割り当てるのに必要な権限を持っていない。 \fBioprio_set\fP()
  97 に必要な権限についての詳しい情報は「備考」の節を参照のこと。
  98 .TP
  99 \fBESRCH\fP
 100 \fIwhich\fP と \fIwho\fP で指定された基準に合致するプロセスが見つからなかった。
 101 .SH バージョン
 102 これらのシステムコールはカーネル 2.6.13 以降の Linux で利用可能である。
 103 .SH 準拠
 104 これらのシステムコールは Linux 独自である。
 105 .SH 注意
 106 glibc はこれらのシステムコールに対するラッパー関数を提供していない。 \fBsyscall\fP(2)  を使って呼び出すこと。
 107
 108 複数のプロセスやスレッドが一つの I/O コンテキストを共有する場合がある。 \fBclone\fP(2) を \fBCLONE_IO\fP
 109 フラグ付きで呼び出した場合にはこの状況となる。 しかしながら、デフォルトでは、一つのプロセスの個々のスレッドは I/O コンテキストを共有「しない」。
 110 したがって、 プロセス内のすべてのスレッドの I/O 優先度を変更したい場合には、 それぞれのスレッドに対して \fBioprio_set\fP()
 111 を呼び出す必要がある。 この操作を行うのに必要となるスレッド ID には \fBgettid\fP(2) か \fBclone\fP(2) が返す値を指定する。
 112
 113 これらのシステムコールは、I/O 優先度に対応した I/O スケジューラと 組み合わせて使用された場合にのみ効果を持つ。 カーネル 2.6.17
 114 では、この条件を満たすスケジューラは Completely Fair Queuing (CFQ) I/O スケジューラだけである。
 115 .SS "I/O スケジューラの選択"
 116 I/O スケジューラの選択はデバイス単位に行われ、その選択は スペシャルファイル
 117 \fI/sys/block/<device>/queue/scheduler\fP 経由で行われる。
 118
 119 現在の I/O スケジューラは \fI/sys\fP ファイルシステム経由で参照できる。例えば、以下のコマンドを実行すると、
 120 現在カーネルでロードされているスケジューラの全リストが表示される。
 121 .sp
 122 .RS
 123 .nf
 124 $\fB cat /sys/block/hda/queue/scheduler\fP
 125 noop anticipatory deadline [cfq]
 126 .fi
 127 .RE
 128 .sp
 129 括弧で囲まれたスケジューラがそのデバイス (上の例では \fIhda\fP)  について実際に使用されているスケジューラである。
 130 別のスケジューラを設定するには、このファイルに新しいスケジューラ名を 書き込めばよい。例えば、以下のコマンドを実行すると、デバイス \fIhda\fP
 131 のスケジューラとして \fIcfq\fP が設定される。
 132 .sp
 133 .RS
 134 .nf
 135 $\fB su\fP
 136 Password:
 137 #\fB echo cfq > /sys/block/hda/queue/scheduler\fP
 138 .fi
 139 .RE
 140 .SS "Completely Fair Queuing (CFQ) I/O スケジューラ"
 141 バージョン 3 (別名 CFQ Time Sliced) 以降、 CPU スケジューリングと同様の I/O nice レベルが CFQ
 142 に実装されている。 これらの nice レベルは 3つのスケジューリングクラスに分類でき、 各スケジューリングクラスにつき
 143 1つ以上の優先度レベルが定義されている。
 144 .TP
 145 \fBIOPRIO_CLASS_RT\fP (1)
 146 これはリアルタイム I/O クラスである。 このスケジューリングクラスには他のクラスよりも高い優先度が与えられる。
 147 このクラスのプロセスには、常にディスクへのアクセスが優先して 割り当てられる。そのため、この I/O クラスを使う際には、 たった一つの リアルタイム
 148 I/O クラスのプロセスにより システム全体のディスクアクセスができなくなってしまうことがある という点に、注意を払う必要がある。 このクラスには、8
 149 段階の class data (優先度レベル) がある。 この値は、そのプロセスが 1回のディスクアクセスにどれだけの
 150 時間が必要かを正確に決めるためのものである。 最高のリアルタイム優先度レベルは 0 で、最低は 7 である。
 151 将来的には、優先度レベルは、希望するデータレートを渡すなど、 より直接的に性能条件を反映できるように変更されるかもしれない。
 152 .TP
 153 \fBIOPRIO_CLASS_BE\fP (2)
 154 これは ベストエフォート・スケジューリングクラスである。 このクラスは、特定の I/O 優先度を設定していないプロセスの デフォルト値である。
 155 class data (優先度レベル) により、そのプロセスがどの程度の I/O 帯域を得られるかが決定される。
 156 ベストエフォート・優先度レベルは、CPU の nice 値 (\fBgetpriority\fP(2)  参照) と同様のものである。
 157 優先度レベルは、ベストエフォート・スケジューリングクラスの中で 他のプロセスとの相対的な優先度を決定する。 優先度レベルの値の範囲は 0 (最高) から
 158 7 (最低) である。
 159 .TP
 160 \fBIOPRIO_CLASS_IDLE\fP (3)
 161 これは idle スケジューリングクラスである。 このレベルで動作するプロセスは他にディスクアクセスをしようとする プロセスがない場合にのみ I/O
 162 時間を取得する。 idle クラスには class data (優先度) は用意されていない。 プロセスにこの優先度を割り当てる際には注意が必要である。
 163 なぜなら、優先度の高いプロセスが常にディスクにアクセスしている場合には ディスクにアクセスできなくなる可能性があるからだ。
 164 .PP
 165 CFQ I/O スケジューラの更なる情報とサンプルプログラムについては \fIDocumentation/block/ioprio.txt\fP
 166 を参照のこと。
 167 .SS "I/O 優先度の設定に必要な許可"
 168 プロセスの優先度を変更する許可が得られるかどうかは 以下の 2つの条件に基いて決定される。
 169 .TP
 170 \fBプロセスの所有権\fP
 171 非特権プロセスは、プロセスの実 UID が呼び出し元プロセスの実 UID もしくは 実効 UID と一致するプロセスの I/O 優先度のみを設定できる。
 172 \fBCAP_SYS_NICE\fP ケーパビリティを持つプロセスは、どのプロセスの優先度でも変更できる。
 173 .TP
 174 \fBどの優先度に設定しようとしているか\fP
 175 非常に高い優先度 (\fBIOPRIO_CLASS_RT\fP)  を設定しようとする場合、 \fBCAP_SYS_ADMIN\fP ケーパビリティが必要である。
 176 カーネル 2.6.24 以前では、非常に低い優先度 (\fBIOPRIO_CLASS_IDLE\fP)  を設定するためにも \fBCAP_SYS_ADMIN\fP
 177 ケーパビリティが必要であったが、 Linux 2.6.25 以降ではもはや必要なくなった。
 178 .PP
 179 \fBioprio_set\fP()  はこの両方のルールに従い、条件を満たさない場合、エラー \fBEPERM\fP で失敗する。
 180 .SH バグ
 181 .\" 6 May 07: Bug report raised:
 182 .\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=4464
 183 .\" Ulrich Drepper replied that he wasn't going to add these
 184 .\" to glibc.
 185 glibc は、このページに記載された関数プロトタイプやマクロを定義する 適切なヘッダファイルをまだ提供していない。 必要な定義については
 186 \fIlinux/ioprio.h\fP を見ればよい。
 187 .SH 関連項目
 188 \fBionice\fP(1), \fBgetpriority\fP(2), \fBopen\fP(2), \fBcapabilities\fP(7)
 189
 190 Linux カーネルソース内の \fIDocumentation/block/ioprio.txt\fP
 191 .SH この文書について
 192 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.52 の一部
 193 である。プロジェクトの説明とバグ報告に関する情報は
 194 http://www.kernel.org/doc/man\-pages/ に書かれている。