release/man2/getpriority.2

   1 .\" Copyright (c) 1980, 1991 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)getpriority.2       6.9 (Berkeley) 3/10/91
  33 .\"
  34 .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
  35 .\" Modified 1996-07-01 by Andries Brouwer <aeb@cwi.nl>
  36 .\" Modified 1996-11-06 by Eric S. Raymond <esr@thyrsus.com>
  37 .\" Modified 2001-10-21 by Michael Kerrisk <mtk.manpages@gmail.com>
  38 .\"    Corrected statement under EPERM to clarify privileges required
  39 .\" Modified 2002-06-21 by Michael Kerrisk <mtk.manpages@gmail.com>
  40 .\"    Clarified meaning of 0 value for 'who' argument
  41 .\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com>
  42 .\"
  43 .\" FIXME Oct 2008: Denys Vlasenko is working on a PRIO_THREAD feature that
  44 .\" is likely to get included in mainline; this will need to be documented.
  45 .\"
  46 .\" Japanese Version Copyright (c) 1997 HANATAKA Shinya
  47 .\"         all rights reserved.
  48 .\" Translated 1997-02-22, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  49 .\" Modified 2001-08-17, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  50 .\" Modified 2001-10-18, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  51 .\" Updated 2001-12-13, Kentaro Shirakata <argrath@ub32.org>
  52 .\" Updated 2002-10-16, Kentaro Shirakata <argrath@ub32.org>
  53 .\" Updated 2005-02-24, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  54 .\" Updated 2005-10-07, Akihiro MOTOKI
  55 .\" Updated 2008-08-04, Akihiro MOTOKI, LDP v3.05
  56 .\"
  57 .\"WORD:        scheduling              スケジューリング
  58 .\"WORD:        piority                 優先度
  59 .\"WORD:        call                    コール
  60 .\"WORD:        user-ID                 UID
  61 .\"WORD:        process                 プロセス
  62 .\"WORD:        user                    ユーザー
  63 .\"WORD:        super user              スーパー・ユーザー
  64 .\"WORD:        effective user-ID       実効UID
  65 .\"WORD:        real user-ID            実UID
  66 .\"
  67 .TH GETPRIORITY 2 2008-05-29 "Linux" "Linux Programmer's Manual"
  68 .SH 名前
  69 getpriority, setpriority \- プログラムのスケジューリングの優先度を取得/設定する
  70 .SH 書式
  71 .B #include <sys/time.h>
  72 .br
  73 .B #include <sys/resource.h>
  74 .sp
  75 .BI "int getpriority(int " which ", int " who );
  76 .br
  77 .BI "int setpriority(int " which ", int " who ", int " prio );
  78 .SH 説明
  79 システムコール
  80 .BR getpriority ()
  81 や
  82 .BR setpriority ()
  83 は、
  84 .I which
  85 と
  86 .I who
  87 で指定されたプロセス、プロセス・グループ、ユーザーの
  88 スケジューリング優先度 (scheduling priority) の
  89 取得や設定をそれぞれ行う。
  90
  91 .I which
  92 の値は
  93 .BR PRIO_PROCESS ,
  94 .BR PRIO_PGRP ,
  95 .BR PRIO_USER ,
  96 のどれか一つで、
  97 .I who
  98 は
  99 .I which
 100 に応じて解釈される
 101 .RB ( PRIO_PROCESS
 102 だとプロセス識別子、
 103 .B PRIO_PGRP
 104 だとプロセス・グループ識別子、
 105 .B PRIO_USER
 106 だと UID (ユーザID) と解釈される)。
 107 .I who
 108 がゼロならば、(それぞれ)呼び出したプロセス、
 109 呼び出したプロセスのプロセス・グループ、
 110 呼び出したプロセスの実UID を意味する。
 111 .I prio
 112 は \-20 から 19 の範囲の値で (但し以下の注意の項を参照のこと)、
 113 デフォルトの優先度は 0 である;
 114 小さな数字ほど、有利なスケジューリングとなる。
 115
 116 .BR getpriority ()
 117 コールは指定したプロセスの中の最も高い優先度 (数値的には最小の値) を返す。
 118 .BR setpriority ()
 119 コールは指定したプロセス全ての優先度を指定した値に設定する。
 120 優先度を今より小さい値に設定できるのはスーパー・ユーザーだけである。
 121 .SH 返り値
 122 .BR getpriority ()
 123 は成功した場合にも \-1 の値を返す可能性があるので、
 124 呼び出しの前に外部変数の
 125 .I errno
 126 をクリアし、呼び出しの後に返り値の \-1 が正当な値か
 127 エラーかを判別する必要がある。
 128 .BR setpriority ()
 129 コールはエラーがなければ 0 を返し、エラーがあれば \-1 を返す。
 130
 131 .SH エラー
 132 .TP
 133 .B EINVAL
 134 .I which
 135 が
 136 .BR PRIO_PROCESS ,
 137 .BR PRIO_PGRP ,
 138 .B PRIO_USER
 139 のいずれでもない。
 140 .TP
 141 .B ESRCH
 142 .I which
 143 と
 144 .I who
 145 で指定されたプロセスが存在しない。
 146 .PP
 147 上記のものに加えて
 148 .BR setpriority ()
 149 では以下のエラーがある:
 150 .TP
 151 .B EACCES
 152 呼び出し元がプロセスの優先度を下げようとしたが、必要な特権を
 153 持っていなかった (Linux の場合、
 154 .B CAP_SYS_NICE
 155 ケーパビリティがなかった)。
 156 Linux 2.6.12 以降では、呼び出し元が、あるプロセスの優先度を、
 157 変更対象のプロセスのリソース
 158 .B RLIMIT_NICE
 159 のソフト・リミットの範囲外に設定しようとした場合にのみ、
 160 このエラーが発生する。詳細は
 161 .BR getrlimit (2)
 162 を参照。
 163 .TP
 164 .B EPERM
 165 プロセスは見つかったが、そのプロセスの実効 (effective) UID が
 166 呼び出し元の実効UID にも実 (real) UID にも一致せず、
 167 呼び出し元が特権も持っていなかった (Linux の場合、
 168 .B CAP_SYS_NICE
 169 ケーパビリティがなかった)。
 170 以下の「注意」も参照のこと。
 171 .SH 準拠
 172 SVr4, 4.4BSD (これらの関数は 4.2BSD で最初に登場した),
 173 POSIX.1-2001.
 174 .SH 注意
 175 .BR fork (2)
 176 で作成された子プロセスは、
 177 親プロセスの nice 値を継承する。
 178 .BR execve (2)
 179 の前後で nice 値は保存される。
 180
 181 相対的な nice 値の違いがプロセス間のスケジューリングにどの程度影響を与えるか
 182 は、UNIX システム間で異なり、Linux ではカーネルバージョンにより異なる。
 183 Linux は、カーネル 2.6.23 以降で、nice 値の相対的な違いが、非常に強い影響を
 184 与えるアルゴリズムを採用した。このアルゴリズムでは、
 185 他に優先度の高いものがシステムに存在する時には、
 186 非常に低い nice 値 (+19) ではプロセスに本当にほとんど CPU が割り当てられない。
 187 また、高い nice 値 (\-20) では CPU を必要とするアプリケーション (例えば
 188 オーディオ・アプリケーション) に CPU のほとんどが割り当てられる。
 189
 190 .B EPERM
 191 が発生する条件の詳細はシステムに依存する。
 192 上記の説明は POSIX.1-2001 のものであり、全ての System V 風システムは
 193 これに従っているようである。
 194 2.6.12 より前の Linux カーネルでは、呼び出し元の実 UID または
 195 実効 UID がプロセス \fIwho\fP の (実効 UID でなく)
 196 実 UID に一致する必要がある。
 197 Linux 2.6.12 以降では、呼び出し元の実行 UID がプロセス \fIwho\fP
 198 の実 UID か実効 UID のいずれかと一致する必要がある。
 199 全ての BSD 風システム (SunOS 4.1.3, Ultrix 4.2,
 200 4.3BSD, FreeBSD 4.3, OpenBSD-2.5等) は、
 201 Linux 2.6.12 以降と同じ動作をする。
 202 .LP
 203 実際の優先度の値の範囲はカーネルのバージョンによって異なる。
 204 1.3.36 より前の Linux では、優先度の範囲は負の無限大 〜 15 である。
 205 1.3.43 以降の Linux では、優先度の範囲は \-20 〜 19 である。
 206 カーネル内部では、nice 値は実際には 40 〜 1 の範囲を使って
 207 表現されており (負の値はエラーコードとなるため)、こちらの値が
 208 システムコール
 209 .BR setpriority ()
 210 と
 211 .BR getpriority ()
 212 で使用されている。
 213 glibc のこれらのシステムコールのラッパー関数において、nice 値の
 214 ユーザ領域 (user-land) とカーネル表現の間の変換が行われる。
 215 変換式は以下の通り:
 216 .I "unice\ =\ 20\ \-\ knice"
 217 .LP
 218 いくつかのシステムでは、nice 値の範囲は \20 〜 20 である。
 219 .LP
 220 現在では
 221 .I <sys/time.h>
 222 をインクルードする必要はないが、インクルードすれば移植性を高めることができる
 223 (実際には
 224 .I <sys/resource.h>
 225 で
 226 .I rusage
 227 構造体が定義されているが、そのフィールドで使用されている
 228 .I struct timeval
 229 型は
 230 .I <sys/time.h>
 231 で定義されている)。
 232 .SH 関連項目
 233 .BR nice (1),
 234 .BR renice (1),
 235 .BR fork (2),
 236 .BR capabilities (7)
 237 .sp
 238 (Linux 2.6.23 以降の) カーネルのソースツリー内の
 239 .I Documentation/scheduler/sched-nice-design.txt