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