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 \fINote\fP: There are no glibc wrappers for these system calls; see NOTES.
  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 is a process ID or thread ID identifying a single process or thread.
  48 If \fIwho\fP is 0, then operate on the calling thread.
  49 .TP
  50 \fBIOPRIO_WHO_PGRP\fP
  51 \fIwho\fP is a process group ID identifying all the members of a process
  52 group.  If \fIwho\fP is 0, then operate on the process group of which the
  53 caller is a member.
  54 .TP
  55 \fBIOPRIO_WHO_USER\fP
  56 .\" FIXME who==0 needs to be documented,
  57 .\" See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=652443
  58 \fIwho\fP はユーザID であり、実 UID に一致する全プロセスが対象となる。
  59 .PP
  60 \fBioprio_get\fP()  の呼び出し時に \fIwhich\fP に \fBIOPRIO_WHO_PGRP\fP か \fBIOPRIO_WHO_USER\fP
  61 が指定され、 \fIwho\fP に一致するプロセスが複数あった場合、 一致するプロセス全体の中で最も高い優先度が返される。
  62 優先度が高いとは、より高い優先度クラスに属している (\fBIOPRIO_CLASS_RT\fP が最も高い優先度クラスで、
  63 \fBIOPRIO_CLASS_IDLE\fP が最も低い)、もしくは 同じ優先度クラスに属しているが優先度レベルが高い
  64 (優先度番号が小さい方が優先度レベルが高いことを意味する)、 ということである。
  65
  66 \fBioprio_set\fP()  に渡す \fIioprio\fP 引き数は、対象となるプロセスに割り当てるスケジューリングクラスと
  67 優先度の両方を指定するビットマスクである。 \fIioprio\fP の値を組み立てたり解釈するのに、以下のマクロが利用できる。
  68 .TP
  69 \fBIOPRIO_PRIO_VALUE(\fP\fIclass\fP\fB, \fP\fIdata\fP\fB)\fP
  70 スケジューリングクラス \fIclass\fP と優先度 (\fIdata\fP)  を与えると、このマクロは 2つの値を組み合わせて、 \fIioprio\fP
  71 値を生成し、マクロの結果として返す。
  72 .TP
  73 \fBIOPRIO_PRIO_CLASS(\fP\fImask\fP\fB)\fP
  74 \fImask\fP (\fIioprio\fP 値) を与えると、このマクロは I/O クラス要素、つまり \fBIOPRIO_CLASS_RT\fP,
  75 \fBIOPRIO_CLASS_BE\fP, \fBIOPRIO_CLASS_IDLE\fP のいずれか一つの値を返す。
  76 .TP
  77 \fBIOPRIO_PRIO_DATA(\fP\fImask\fP\fB)\fP
  78 \fImask\fP (\fIioprio\fP 値) を与えると、このマクロは優先度 (\fIdata\fP)  要素を返す。
  79 .PP
  80 スケジューリングクラスと優先度に関する詳しい情報は、 「備考」の節を参照のこと。
  81
  82 I/O 優先度は読み出しと同期書き込み (\fBO_DIRECT\fP, \fBO_SYNC\fP)  に対応している。 I/O
  83 優先度は非同期書き込みには対応していない。なぜなら、 非同期書き込みはメモリ書き換えを行うプログラムの動作 (context) とは
  84 関係なく発行され、そのためプログラム単位の優先度は適用されないから である。
  85 .SH 返り値
  86 成功すると、 \fBioprio_get\fP()  は、 \fIwhich\fP と \fIwho\fP で指定された基準に合致した全プロセスで最も高い I/O
  87 優先度を持つプロセスの \fIioprio\fP 値を返す。 エラーの場合、\-1 を返し、 \fIerrno\fP にエラーを示す値を設定する。
  88 .PP
  89 成功すると、 \fBioprio_set\fP()  は 0 を返す。 エラーの場合、\-1 を返し、 \fIerrno\fP にエラーを示す値を設定する。
  90 .SH エラー
  91 .TP
  92 \fBEINVAL\fP
  93 \fIwhich\fP か \fIioprio\fP の値が不正である。 \fIioprio\fP 用に指定可能なスケジューラクラスと優先度レベルについては
  94 「備考」を参照のこと。
  95 .TP
  96 \fBEPERM\fP
  97 呼び出し元プロセスが、指定されたプロセスに \fIioprio\fP を割り当てるのに必要な権限を持っていない。 \fBioprio_set\fP()
  98 に必要な権限についての詳しい情報は「備考」の節を参照のこと。
  99 .TP
 100 \fBESRCH\fP
 101 \fIwhich\fP と \fIwho\fP で指定された基準に合致するプロセスが見つからなかった。
 102 .SH バージョン
 103 これらのシステムコールはカーネル 2.6.13 以降の Linux で利用可能である。
 104 .SH 準拠
 105 これらのシステムコールは Linux 独自である。
 106 .SH 注意
 107 glibc はこれらのシステムコールに対するラッパー関数を提供していない。 \fBsyscall\fP(2)  を使って呼び出すこと。
 108
 109 Two or more processes or threads can share an I/O context.  This will be the
 110 case when \fBclone\fP(2)  was called with the \fBCLONE_IO\fP flag.  However, by
 111 default, the distinct threads of a process will \fBnot\fP share the same I/O
 112 context.  This means that if you want to change the I/O priority of all
 113 threads in a process, you may need to call \fBioprio_set\fP()  on each of the
 114 threads.  The thread ID that you would need for this operation is the one
 115 that is returned by \fBgettid\fP(2)  or \fBclone\fP(2).
 116
 117 これらのシステムコールは、I/O 優先度に対応した I/O スケジューラと 組み合わせて使用された場合にのみ効果を持つ。 カーネル 2.6.17
 118 では、この条件を満たすスケジューラは Completely Fair Queuing (CFQ) I/O スケジューラだけである。
 119 .SS "I/O スケジューラの選択"
 120 I/O スケジューラの選択はデバイス単位に行われ、その選択は スペシャルファイル
 121 \fI/sys/block/<device>/queue/scheduler\fP 経由で行われる。
 122
 123 現在の I/O スケジューラは \fI/sys\fP ファイルシステム経由で参照できる。例えば、以下のコマンドを実行すると、
 124 現在カーネルでロードされているスケジューラの全リストが表示される。
 125 .sp
 126 .RS
 127 .nf
 128 $\fB cat /sys/block/hda/queue/scheduler\fP
 129 noop anticipatory deadline [cfq]
 130 .fi
 131 .RE
 132 .sp
 133 括弧で囲まれたスケジューラがそのデバイス (上の例では \fIhda\fP)  について実際に使用されているスケジューラである。
 134 別のスケジューラを設定するには、このファイルに新しいスケジューラ名を 書き込めばよい。例えば、以下のコマンドを実行すると、デバイス \fIhda\fP
 135 のスケジューラとして \fIcfq\fP が設定される。
 136 .sp
 137 .RS
 138 .nf
 139 $\fB su\fP
 140 Password:
 141 #\fB echo cfq > /sys/block/hda/queue/scheduler\fP
 142 .fi
 143 .RE
 144 .SS "Completely Fair Queuing (CFQ) I/O スケジューラ"
 145 バージョン 3 (別名 CFQ Time Sliced) 以降、 CPU スケジューリングと同様の I/O nice レベルが CFQ
 146 に実装されている。 これらの nice レベルは 3つのスケジューリングクラスに分類でき、 各スケジューリングクラスにつき
 147 1つ以上の優先度レベルが定義されている。
 148 .TP
 149 \fBIOPRIO_CLASS_RT\fP (1)
 150 これはリアルタイム I/O クラスである。 このスケジューリングクラスには他のクラスよりも高い優先度が与えられる。
 151 このクラスのプロセスには、常にディスクへのアクセスが優先して 割り当てられる。そのため、この I/O クラスを使う際には、 たった一つの リアルタイム
 152 I/O クラスのプロセスにより システム全体のディスクアクセスができなくなってしまうことがある という点に、注意を払う必要がある。 このクラスには、8
 153 段階の class data (優先度レベル) がある。 この値は、そのプロセスが 1回のディスクアクセスにどれだけの
 154 時間が必要かを正確に決めるためのものである。 最高のリアルタイム優先度レベルは 0 で、最低は 7 である。
 155 将来的には、優先度レベルは、希望するデータレートを渡すなど、 より直接的に性能条件を反映できるように変更されるかもしれない。
 156 .TP
 157 \fBIOPRIO_CLASS_BE\fP (2)
 158 これは ベストエフォート・スケジューリングクラスである。 このクラスは、特定の I/O 優先度を設定していないプロセスの デフォルト値である。
 159 class data (優先度レベル) により、そのプロセスがどの程度の I/O 帯域を得られるかが決定される。
 160 ベストエフォート・優先度レベルは、CPU の nice 値 (\fBgetpriority\fP(2)  参照) と同様のものである。
 161 優先度レベルは、ベストエフォート・スケジューリングクラスの中で 他のプロセスとの相対的な優先度を決定する。 優先度レベルの値の範囲は 0 (最高) から
 162 7 (最低) である。
 163 .TP
 164 \fBIOPRIO_CLASS_IDLE\fP (3)
 165 これは idle スケジューリングクラスである。 このレベルで動作するプロセスは他にディスクアクセスをしようとする プロセスがない場合にのみ I/O
 166 時間を取得する。 idle クラスには class data (優先度) は用意されていない。 プロセスにこの優先度を割り当てる際には注意が必要である。
 167 なぜなら、優先度の高いプロセスが常にディスクにアクセスしている場合には ディスクにアクセスできなくなる可能性があるからだ。
 168 .PP
 169 CFQ I/O スケジューラの更なる情報とサンプルプログラムについては \fIDocumentation/block/ioprio.txt\fP
 170 を参照のこと。
 171 .SS "I/O 優先度の設定に必要な許可"
 172 プロセスの優先度を変更する許可が得られるかどうかは 以下の 2つの条件に基いて決定される。
 173 .TP
 174 \fBプロセスの所有権\fP
 175 非特権プロセスは、プロセスの実 UID が呼び出し元プロセスの実 UID もしくは 実効 UID と一致するプロセスの I/O 優先度のみを設定できる。
 176 \fBCAP_SYS_NICE\fP ケーパビリティを持つプロセスは、どのプロセスの優先度でも変更できる。
 177 .TP
 178 \fBどの優先度に設定しようとしているか\fP
 179 非常に高い優先度 (\fBIOPRIO_CLASS_RT\fP)  を設定しようとする場合、 \fBCAP_SYS_ADMIN\fP ケーパビリティが必要である。
 180 カーネル 2.6.24 以前では、非常に低い優先度 (\fBIOPRIO_CLASS_IDLE\fP)  を設定するためにも \fBCAP_SYS_ADMIN\fP
 181 ケーパビリティが必要であったが、 Linux 2.6.25 以降ではもはや必要なくなった。
 182 .PP
 183 \fBioprio_set\fP()  はこの両方のルールに従い、条件を満たさない場合、エラー \fBEPERM\fP で失敗する。
 184 .SH バグ
 185 .\" 6 May 07: Bug report raised:
 186 .\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=4464
 187 .\" Ulrich Drepper replied that he wasn't going to add these
 188 .\" to glibc.
 189 glibc は、このページに記載された関数プロトタイプやマクロを定義する 適切なヘッダファイルをまだ提供していない。 必要な定義については
 190 \fIlinux/ioprio.h\fP を見ればよい。
 191 .SH 関連項目
 192 \fBionice\fP(1), \fBgetpriority\fP(2), \fBopen\fP(2), \fBcapabilities\fP(7)
 193
 194 Linux カーネルソース内の \fIDocumentation/block/ioprio.txt\fP
 195 .SH この文書について
 196 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.50 の一部
 197 である。プロジェクトの説明とバグ報告に関する情報は
 198 http://www.kernel.org/doc/man\-pages/ に書かれている。