[linuxjm/LDP_man-pages.git] / draft / man2 / ioprio_set.2

.\" This is _*_ nroff _*_ source. Emacs, gimme all those colors :)
.\"
.\" Copyright (c) International Business Machines orp., 2006
.\"
.\" This program is free software; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
.\" the GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program; if not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston,
.\" MA 02111-1307 USA
.\"
.\" HISTORY:
.\" 2006-04-27, created by Eduardo M. Fleury <efleury@br.ibm.com>
.\" with various additions by Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" Japanese Version Copyright (c) 2007 Akihiro MOTOKI
.\"         all rights reserved.
.\" Translated 2007-01-09, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.43
.\" Updated 2008-08-06, Akihiro MOTOKI, LDP v3.05
.\"
.TH IOPRIO_SET 2 2008-07-09 "Linux" "Linux Programmer's Manual"
.\"O .SH NAME
.SH 名前
.\"O ioprio_get, ioprio_set \- get/set I/O scheduling class and priority
ioprio_get, ioprio_set \- I/O スケジューリングクラスと優先度の設定/取得
.\"O .SH SYNOPSIS
.SH 書式
.nf
.BI "int ioprio_get(int " which ", int " who );
.BI "int ioprio_set(int " which ", int " who ", int " ioprio );
.fi
.\"O .SH DESCRIPTION
.SH 説明
.\"O The
.\"O .BR ioprio_get ()
.\"O and
.\"O .BR ioprio_set ()
.\"O system calls respectively get and set the I/O scheduling class and
.\"O priority of one or more processes.
システムコール
.BR ioprio_get ()
/
.BR ioprio_set ()
は、(1つ以上の) プロセスの I/O スケジューリングクラスと
優先度の取得/設定を行う。

.\"O The
.\"O .I which
.\"O and
.\"O .I who
.\"O arguments identify the process(es) on which the system
.\"O calls operate.
.\"O The
.\"O .I which
.\"O argument determines how
.\"O .I who
.\"O is interpreted, and has one of the following values:
.I which
と
.I who
引き数でシステムコールの操作対象となるプロセスを指示する。
.I which
引き数は、
.I who
をどのように解釈するかを決めるもので、以下のいずれか一つを指定する。
.TP
.B IOPRIO_WHO_PROCESS
.\"O .I who
.\"O is a process ID identifying a single process.
.I who
はプロセスID であり、指定された 1 プロセスが対象となる。
.TP
.B IOPRIO_WHO_PGRP
.\"O .I who
.\"O is a process group ID identifying all the members of a process group.
.I who
はプロセスグループID であり、プロセスグループの全メンバが対象となる。
.TP
.B IOPRIO_WHO_USER
.\"O .I who
.\"O is a user ID identifying all of the processes that
.\"O have a matching real UID.
.I who
はユーザID であり、実 UID に一致する全プロセスが対象となる。
.PP
.\"O If
.\"O .I which
.\"O is specified as
.\"O .B IOPRIO_WHO_PGRP
.\"O or
.\"O .B IOPRIO_WHO_USER
.\"O when calling
.\"O .BR ioprio_get (),
.\"O and more than one process matches
.\"O .IR who ,
.\"O then the returned priority will be the highest one found among
.\"O all of the matching processes.
.\"O One priority is said to be
.\"O higher than another one if it belongs to a higher priority
.\"O class
.\"O .RB ( IOPRIO_CLASS_RT
.\"O is the highest priority class;
.\"O .B IOPRIO_CLASS_IDLE
.\"O is the lowest)
.\"O or if it belongs to the same priority class as the other process but
.\"O has a higher priority level (a lower priority number means a
.\"O higher priority level).
.BR ioprio_get ()
の呼び出し時に
.I which
に
.B IOPRIO_WHO_PGRP
か
.B IOPRIO_WHO_USER
が指定され、
.I who
に一致するプロセスが複数あった場合、
一致するプロセス全体の中で最も高い優先度が返される。
優先度が高いとは、より高い優先度クラスに属している
.RB ( IOPRIO_CLASS_RT
が最も高い優先度クラスで、
.B IOPRIO_CLASS_IDLE
が最も低い)、もしくは
同じ優先度クラスに属しているが優先度レベルが高い
(優先度番号が小さい方が優先度レベルが高いことを意味する)、
ということである。

.\"O The
.\"O .I ioprio
.\"O argument given to
.\"O .BR ioprio_set ()
.\"O is a bit mask that specifies both the scheduling class and the
.\"O priority to be assigned to the target process(es).
.\"O The following macros are used for assembling and dissecting
.\"O .I ioprio
.\"O values:
.BR ioprio_set ()
に渡す
.I ioprio
引き数は、対象となるプロセスに割り当てるスケジューリングクラスと
優先度の両方を指定するビットマスクである。
.I ioprio
の値を組み立てたり解釈するのに、以下のマクロが利用できる。
.TP
.BI IOPRIO_PRIO_VALUE( class ", " data )
.\"O Given a scheduling
.\"O .I class
.\"O and priority
.\"O .RI ( data ),
.\"O this macro combines the two values to produce an
.\"O .I ioprio
.\"O value, which is returned as the result of the macro.
スケジューリングクラス
.I class
と優先度
.RI ( data )
を与えると、このマクロは 2つの値を組み合わせて、
.I ioprio
値を生成し、マクロの結果として返す。
.TP
.BI IOPRIO_PRIO_CLASS( mask )
.\"O Given
.\"O .I mask
.\"O (an
.\"O .I ioprio
.\"O value), this macro returns its I/O class component, that is,
.\"O one of the values
.\"O .BR IOPRIO_CLASS_RT ,
.\"O .BR IOPRIO_CLASS_BE ,
.\"O or
.\"O .BR IOPRIO_CLASS_IDLE .
.I mask
.RI ( ioprio
値) を与えると、このマクロは I/O クラス要素、つまり
.BR IOPRIO_CLASS_RT ,
.BR IOPRIO_CLASS_BE ,
.B IOPRIO_CLASS_IDLE
のいずれか一つの値を返す。
.TP
.BI IOPRIO_PRIO_DATA( mask )
.\"O Given
.\"O .I mask
.\"O (an
.\"O .I ioprio
.\"O value), this macro returns its priority
.\"O .RI ( data )
.\"O component.
.I mask
.RI ( ioprio
値) を与えると、このマクロは優先度
.RI ( data )
要素を返す。
.PP
.\"O See the NOTES section for more
.\"O information on scheduling classes and priorities.
スケジューリングクラスと優先度に関する詳しい情報は、
「備考」の節を参照のこと。

.\"O I/O priorities are supported for reads and for synchronous
.\"O .RB ( O_DIRECT ,
.\"O .BR O_SYNC )
.\"O writes.
.\"O I/O priorities are not supported for asynchronous
.\"O writes because they are issued outside the context of the program
.\"O dirtying the memory, and thus program-specific priorities do not apply.
I/O 優先度は読み出しと同期書き込み
.RB ( O_DIRECT ,
.BR O_SYNC )
に対応している。
I/O 優先度は非同期書き込みには対応していない。なぜなら、
非同期書き込みはメモリ書き換えを行うプログラムの動作 (context) とは
関係なく発行され、そのためプログラム単位の優先度は適用されないから
である。
.\"O .SH "RETURN VALUE"
.SH 返り値
.\"O On success,
.\"O .BR ioprio_get ()
.\"O returns the
.\"O .I ioprio
.\"O value of the process with highest I/O priority of any of the processes
.\"O that match the criteria specified in
.\"O .I which
.\"O and
.\"O .IR who .
.\"O On error, \-1 is returned, and
.\"O .I errno
.\"O is set to indicate the error.
成功すると、
.BR ioprio_get ()
は、
.I which
と
.I who
で指定された基準に合致した全プロセスで最も高い I/O 優先度を持つプロセスの
.I ioprio
値を返す。
エラーの場合、\-1 を返し、
.I errno
にエラーを示す値を設定する。
.PP
.\"O On success,
.\"O .BR ioprio_set ()
.\"O returns 0.
.\"O On error, \-1 is returned, and
.\"O .I errno
.\"O is set to indicate the error.
成功すると、
.BR ioprio_set ()
は 0 を返す。
エラーの場合、\-1 を返し、
.I errno
にエラーを示す値を設定する。
.\"O .SH ERRORS
.SH エラー
.TP
.B EINVAL
.\"O Invalid value for
.\"O .I which
.\"O or
.\"O .IR ioprio .
.\"O Refer to the NOTES section for available scheduler
.\"O classes and priority levels for
.\"O .IR ioprio .
.I which
か
.I ioprio
の値が不正である。
.I ioprio
用に指定可能なスケジューラクラスと優先度レベルについては
「備考」を参照のこと。
.TP
.B EPERM
.\"O The calling process does not have the privilege needed to assign this
.\"O .I ioprio
.\"O to the specified process(es).
.\"O See the NOTES section for more information on required
.\"O privileges for
.\"O .BR ioprio_set ().
呼び出し元プロセスが、指定されたプロセスに
.I ioprio
を割り当てるのに必要な権限を持っていない。
.BR ioprio_set ()
に必要な権限についての詳しい情報は「備考」の節を参照のこと。
.TP
.B ESRCH
.\"O No process(es) could be found that matched the specification in
.\"O .I which
.\"O and
.\"O .IR who .
.I which
と
.I who
で指定された基準に合致するプロセスが見つからなかった。
.\"O .SH VERSIONS
.SH バージョン
.\"O These system calls have been available on Linux since
.\"O kernel 2.6.13.
これらのシステムコールはカーネル 2.6.13 以降の Linux で利用可能である。
.\"O .SH "CONFORMING TO"
.SH 準拠
.\"O These system calls are Linux-specific.
これらのシステムコールは Linux 独自である。
.\"O .SH NOTES
.SH 備考
.\"O Glibc does not provide wrapper for these system calls; call them using
.\"O .BR syscall (2).
glibc はこれらのシステムコールに対するラッパー関数を提供していない。
.BR syscall (2)
を使って呼び出すこと。

.\"O These system calls only have an effect when used
.\"O in conjunction with an I/O scheduler that supports I/O priorities.
.\"O As at kernel 2.6.17 the only such scheduler is the Completely Fair Queuing
.\"O (CFQ) I/O scheduler.
これらのシステムコールは、I/O 優先度に対応した I/O スケジューラと
組み合わせて使用された場合にのみ効果を持つ。
カーネル 2.6.17 では、この条件を満たすスケジューラは
Completely Fair Queuing (CFQ) I/O スケジューラだけである。
.\"O .SS "Selecting an I/O Scheduler"
.SS I/O スケジューラの選択
.\"O I/O Schedulers are selected on a per-device basis via the special
.\"O file
.\"O .IR /sys/block/<device>/queue/scheduler .
I/O スケジューラの選択はデバイス単位に行われ、その選択は
スペシャルファイル
.I /sys/block/<device>/queue/scheduler
経由で行われる。

.\"O One can view the current I/O scheduler via the
.\"O .I /sys
.\"O file system.
.\"O For example, the following command
.\"O displays a list of all schedulers currently loaded in the kernel:
現在の I/O スケジューラは
.I /sys
ファイルシステム経由で参照できる。例えば、以下のコマンドを実行すると、
現在カーネルでロードされているスケジューラの全リストが表示される。
.sp
.RS
.nf
.RB "$" " cat /sys/block/hda/queue/scheduler"
noop anticipatory deadline [cfq]
.fi
.RE
.sp
.\"O The scheduler surrounded by brackets is the one actually
.\"O in use for the device
.\"O .RI ( hda
.\"O in the example).
括弧で囲まれたスケジューラがそのデバイス (上の例では
.IR hda )
について実際に使用されているスケジューラである。
.\"O Setting another scheduler is done by writing the name of the
.\"O new scheduler to this file.
.\"O For example, the following command will set the
.\"O scheduler for the
.\"O .I hda
.\"O device to
.\"O .IR cfq :
別のスケジューラを設定するには、このファイルに新しいスケジューラ名を
書き込めばよい。例えば、以下のコマンドを実行すると、デバイス
.I hda
のスケジューラとして
.I cfq
が設定される。
.sp
.RS
.nf
.RB "$" " su"
Password:
.RB "#" " echo cfq > /sys/block/hda/queue/scheduler"
.fi
.RE
.\"O .SS "The Completely Fair Queuing (CFQ) I/O Scheduler"
.SS "Completely Fair Queuing (CFQ) I/O スケジューラ"
.\"O Since v3 (aka CFQ Time Sliced) CFQ implements
.\"O I/O nice levels similar to those
.\"O of CPU scheduling.
.\"O These nice levels are grouped in three scheduling classes
.\"O each one containing one or more priority levels:
バージョン 3 (別名 CFQ Time Sliced) 以降、
CPU スケジューリングと同様の I/O nice レベルが CFQ に実装されている。
これらの nice レベルは 3つのスケジューリングクラスに分類でき、
各スケジューリングクラスにつき 1つ以上の優先度レベルが定義されている。
.TP
.BR IOPRIO_CLASS_RT " (1)"
.\"O This is the real-time I/O class.
.\"O This scheduling class is given
.\"O higher priority than any other class:
.\"O processes from this class are
.\"O given first access to the disk every time.
.\"O Thus this I/O class needs to be used with some
.\"O care: one I/O real-time process can starve the entire system.
.\"O Within the real-time class,
.\"O there are 8 levels of class data (priority) that determine exactly
.\"O how much time this process needs the disk for on each service.
.\"O The highest real-time priority level is 0; the lowest is 7.
.\"O In the future this might change to be more directly mappable to
.\"O performance, by passing in a desired data rate instead.
これはリアルタイム I/O クラスである。
このスケジューリングクラスには他のクラスよりも高い優先度が与えられる。
このクラスのプロセスには、常にディスクへのアクセスが優先して
割り当てられる。そのため、この I/O クラスを使う際には、
たった一つの リアルタイム I/O クラスのプロセスにより
システム全体のディスクアクセスができなくなってしまうことがある
という点に、注意を払う必要がある。
このクラスには、8 段階の class data (優先度レベル) がある。
この値は、そのプロセスが 1回のディスクアクセスにどれだけの
時間が必要かを正確に決めるためのものである。
最高のリアルタイム優先度レベルは 0 で、最低は 7 である。
将来的には、優先度レベルは、希望するデータレートを渡すなど、
より直接的に性能条件を反映できるように変更されるかもしれない。
.TP
.BR IOPRIO_CLASS_BE " (2)"
.\"O This is the best-effort scheduling class,
.\"O which is the default for any process
.\"O that hasn't set a specific I/O priority.
.\"O The class data (priority) determines how much
.\"O I/O bandwidth the process will get.
.\"O Best-effort priority levels are analogous to CPU nice values
.\"O (see
.\"O .BR getpriority (2)).
.\"O The priority level determines a priority relative
.\"O to other processes in the best-effort scheduling class.
.\"O Priority levels range from 0 (highest) to 7 (lowest).
これは ベストエフォート・スケジューリングクラスである。
このクラスは、特定の I/O 優先度を設定していないプロセスの
デフォルト値である。
class data (優先度レベル) により、そのプロセスがどの程度の
I/O 帯域を得られるかが決定される。
ベストエフォート・優先度レベルは、CPU の nice 値
.RB ( getpriority (2)
参照) と同様のものである。
優先度レベルは、ベストエフォート・スケジューリングクラスの中で
他のプロセスとの相対的な優先度を決定する。
優先度レベルの値の範囲は 0 (最高) から 7 (最低) である。
.TP
.BR IOPRIO_CLASS_IDLE " (3)"
.\"O This is the idle scheduling class.
.\"O Processes running at this level only get I/O
.\"O time when no-one else needs the disk.
.\"O The idle class has no class data.
.\"O Attention is required when assigning this priority class to a process,
.\"O since it may become starved if higher priority processes are
.\"O constantly accessing the disk.
これは idle スケジューリングクラスである。
このレベルで動作するプロセスは他にディスクアクセスをしようとする
プロセスがない場合にのみ I/O 時間を取得する。
idle クラスには class data (優先度) は用意されていない。
プロセスにこの優先度を割り当てる際には注意が必要である。
なぜなら、優先度の高いプロセスが常にディスクにアクセスしている場合には
ディスクにアクセスできなくなる可能性があるからだ。
.PP
.\"O Refer to
.\"O .I Documentation/block/ioprio.txt
.\"O for more information on the CFQ I/O Scheduler and an example program.
CFQ I/O スケジューラの更なる情報とサンプルプログラムについては
.I Documentation/block/ioprio.txt
を参照のこと。
.\"O .SS "Required permissions to set I/O priorities"
.SS "I/O 優先度の設定に必要な許可"
.\"O Permission to change a process's priority is granted or denied based
.\"O on two assertions:
プロセスの優先度を変更する許可が得られるかどうかは
以下の 2つの条件に基いて決定される。
.TP
.\"O .B "Process ownership"
.B "プロセスの所有権"
.\"O An unprivileged process may only set the I/O priority of a process
.\"O whose real UID
.\"O matches the real or effective UID of the calling process.
.\"O A process which has the
.\"O .B CAP_SYS_NICE
.\"O capability can change the priority of any process.
非特権プロセスは、プロセスの実 UID が呼び出し元プロセスの実 UID もしくは
実効 UID と一致するプロセスの I/O 優先度のみを設定できる。
.B CAP_SYS_NICE
ケーパビリティを持つプロセスは、どのプロセスの優先度でも変更できる。
.TP
.\"O .B "What is the desired priority"
.B "どの優先度に設定しようとしているか"
.\"O Attempts to set very high priorities
.\"O .RB ( IOPRIO_CLASS_RT )
.\"O require the
.\"O .B CAP_SYS_ADMIN
.\"O capability.
非常に高い優先度
.RB ( IOPRIO_CLASS_RT )
を設定しようとする場合、
.B CAP_SYS_ADMIN
ケーパビリティが必要である。
.\"O Kernel versions up to 2.6.24 also required
.\"O .B CAP_SYS_ADMIN
.\"O to set a very low priority
.\"O .RB ( IOPRIO_CLASS_IDLE ),
.\"O but since Linux 2.6.25, this is no longer required.
カーネル 2.6.24 以前では、非常に低い優先度
.RB ( IOPRIO_CLASS_IDLE )
を設定するためにも
.B CAP_SYS_ADMIN
ケーパビリティが必要であったが、
Linux 2.6.25 以降ではもはや必要なくなった。
.PP
.\"O A call to
.\"O .BR ioprio_set ()
.\"O must follow both rules, or the call will fail with the error
.\"O .BR EPERM .
.BR ioprio_set ()
はこの両方のルールに従い、条件を満たさない場合、エラー
.B EPERM
で失敗する。
.\"O .SH BUGS
.SH バグ
.\" 6 May 07: Bug report raised:
.\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=4464
.\" Ulrich Drepper replied that he wasn't going to add these
.\" to glibc.
.\"O Glibc does not yet provide a suitable header file defining
.\"O the function prototypes and macros described on this page.
.\"O Suitable definitions can be found in
.\"O .IR linux/ioprio.h .
glibc は、このページに記載された関数プロトタイプやマクロを定義する
適切なヘッダファイルをまだ提供していない。
必要な定義については
.I linux/ioprio.h
を見ればよい。
.\"O .SH "SEE ALSO"
.SH 関連項目
.BR getpriority (2),
.BR open (2),
.BR capabilities (7)
.sp
.\"O Documentation/block/ioprio.txt in the kernel source tree.
カーネル・ソース内の Documentation/block/ioprio.txt