draft/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 .\"O .SH NAME
  69 .SH 名前
  70 .\"O getpriority, setpriority \- get/set program scheduling priority
  71 getpriority, setpriority \- プログラムのスケジューリングの優先度を取得/設定する
  72 .\"O .SH SYNOPSIS
  73 .SH 書式
  74 .B #include <sys/time.h>
  75 .br
  76 .B #include <sys/resource.h>
  77 .sp
  78 .BI "int getpriority(int " which ", int " who );
  79 .br
  80 .BI "int setpriority(int " which ", int " who ", int " prio );
  81 .\"O .SH DESCRIPTION
  82 .SH 説明
  83 .\"O The scheduling priority of the process, process group, or user, as
  84 .\"O indicated by
  85 .\"O .I which
  86 .\"O and
  87 .\"O .I who
  88 .\"O is obtained with the
  89 .\"O .BR getpriority ()
  90 .\"O call and set with the
  91 .\"O .BR setpriority ()
  92 .\"O call.
  93 システムコール
  94 .BR getpriority ()
  95 や
  96 .BR setpriority ()
  97 は、
  98 .I which
  99 と
 100 .I who
 101 で指定されたプロセス、プロセス・グループ、ユーザーの
 102 スケジューリング優先度 (scheduling priority) の
 103 取得や設定をそれぞれ行う。
 104
 105 .\"O The value
 106 .\"O .I which
 107 .\"O is one of
 108 .\"O .BR PRIO_PROCESS ,
 109 .\"O .BR PRIO_PGRP ,
 110 .\"O or
 111 .\"O .BR PRIO_USER ,
 112 .\"O and
 113 .\"O .I who
 114 .\"O is interpreted relative to
 115 .\"O .I which
 116 .\"O (a process identifier for
 117 .\"O .BR PRIO_PROCESS ,
 118 .\"O process group
 119 .\"O identifier for
 120 .\"O .BR PRIO_PGRP ,
 121 .\"O and a user ID for
 122 .\"O .BR PRIO_USER ).
 123 .I which
 124 の値は
 125 .BR PRIO_PROCESS ,
 126 .BR PRIO_PGRP ,
 127 .BR PRIO_USER ,
 128 のどれか一つで、
 129 .I who
 130 は
 131 .I which
 132 に応じて解釈される
 133 .RB ( PRIO_PROCESS
 134 だとプロセス識別子、
 135 .B PRIO_PGRP
 136 だとプロセス・グループ識別子、
 137 .B PRIO_USER
 138 だと UID (ユーザID) と解釈される)。
 139 .\"O A zero value for
 140 .\"O .I who
 141 .\"O denotes (respectively) the calling process, the process group of the
 142 .\"O calling process, or the real user ID of the calling process.
 143 .I who
 144 がゼロならば、(それぞれ)呼び出したプロセス、
 145 呼び出したプロセスのプロセス・グループ、
 146 呼び出したプロセスの実UID を意味する。
 147 .\"O .I Prio
 148 .\"O is a value in the range \-20 to 19 (but see the Notes below).
 149 .\"O The default priority is 0;
 150 .\"O lower priorities cause more favorable scheduling.
 151 .I prio
 152 は \-20 から 19 の範囲の値で (但し以下の注意の項を参照のこと)、
 153 デフォルトの優先度は 0 である;
 154 小さな数字ほど、有利なスケジューリングとなる。
 155
 156 .\"O The
 157 .\"O .BR getpriority ()
 158 .\"O call returns the highest priority (lowest numerical value)
 159 .\"O enjoyed by any of the specified processes.
 160 .\"O The
 161 .\"O .BR setpriority ()
 162 .\"O call sets the priorities of all of the specified processes
 163 .\"O to the specified value.
 164 .\"O Only the superuser may lower priorities.
 165 .BR getpriority ()
 166 コールは指定したプロセスの中の最も高い優先度 (数値的には最小の値) を返す。
 167 .BR setpriority ()
 168 コールは指定したプロセス全ての優先度を指定した値に設定する。
 169 優先度を今より小さい値に設定できるのはスーパー・ユーザーだけである。
 170 .\"O .SH "RETURN VALUE"
 171 .SH 返り値
 172 .\"O Since
 173 .\"O .BR getpriority ()
 174 .\"O can legitimately return the value \-1, it is necessary
 175 .\"O to clear the external variable
 176 .\"O .I errno
 177 .\"O prior to the
 178 .\"O call, then check it afterward to determine
 179 .\"O if \-1 is an error or a legitimate value.
 180 .\"O The
 181 .\"O .BR setpriority ()
 182 .\"O call returns 0 if there is no error, or
 183 .\"O \-1 if there is.
 184 .BR getpriority ()
 185 は成功した場合にも \-1 の値を返す可能性があるので、
 186 呼び出しの前に外部変数の
 187 .I errno
 188 をクリアし、呼び出しの後に返り値の \-1 が正当な値か
 189 エラーかを判別する必要がある。
 190 .BR setpriority ()
 191 コールはエラーがなければ 0 を返し、エラーがあれば \-1 を返す。
 192
 193 .\"O .SH ERRORS
 194 .SH エラー
 195 .TP
 196 .B EINVAL
 197 .\"O .I which
 198 .\"O was not one of
 199 .\"O .BR PRIO_PROCESS ,
 200 .\"O .BR PRIO_PGRP ,
 201 .\"O or
 202 .\"O .BR PRIO_USER .
 203 .I which
 204 が
 205 .BR PRIO_PROCESS ,
 206 .BR PRIO_PGRP ,
 207 .B PRIO_USER
 208 のいずれでもない。
 209 .TP
 210 .B ESRCH
 211 .\"O No process was located using the
 212 .\"O .I which
 213 .\"O and
 214 .\"O .I who
 215 .\"O values specified.
 216 .I which
 217 と
 218 .I who
 219 で指定されたプロセスが存在しない。
 220 .PP
 221 .\"O In addition to the errors indicated above,
 222 .\"O .BR setpriority ()
 223 .\"O may fail if:
 224 上記のものに加えて
 225 .BR setpriority ()
 226 では以下のエラーがある:
 227 .TP
 228 .B EACCES
 229 .\"O The caller attempted to lower a process priority, but did not
 230 .\"O have the required privilege (on Linux: did not have the
 231 .\"O .B CAP_SYS_NICE
 232 .\"O capability).
 233 .\"O Since Linux 2.6.12, this error only occurs if the caller attempts
 234 .\"O to set a process priority outside the range of the
 235 .\"O .B RLIMIT_NICE
 236 .\"O soft resource limit of the target process; see
 237 .\"O .BR getrlimit (2)
 238 .\"O for details.
 239 呼び出し元がプロセスの優先度を下げようとしたが、必要な特権を
 240 持っていなかった (Linux の場合、
 241 .B CAP_SYS_NICE
 242 ケーパビリティがなかった)。
 243 Linux 2.6.12 以降では、呼び出し元が、あるプロセスの優先度を、
 244 変更対象のプロセスのリソース
 245 .B RLIMIT_NICE
 246 のソフト・リミットの範囲外に設定しようとした場合にのみ、
 247 このエラーが発生する。詳細は
 248 .BR getrlimit (2)
 249 を参照。
 250 .TP
 251 .B EPERM
 252 .\"O A process was located, but its effective user ID did not match
 253 .\"O either the effective or the real user ID of the caller,
 254 .\"O and was not privileged (on Linux: did not have the
 255 .\"O .B CAP_SYS_NICE
 256 .\"O capability).
 257 .\"O But see NOTES below.
 258 プロセスは見つかったが、そのプロセスの実効 (effective) UID が
 259 呼び出し元の実効UID にも実 (real) UID にも一致せず、
 260 呼び出し元が特権も持っていなかった (Linux の場合、
 261 .B CAP_SYS_NICE
 262 ケーパビリティがなかった)。
 263 以下の「注意」も参照のこと。
 264 .\"O .SH "CONFORMING TO"
 265 .SH 準拠
 266 .\"O SVr4, 4.4BSD (these function calls first appeared in 4.2BSD),
 267 .\"O POSIX.1-2001.
 268 SVr4, 4.4BSD (これらの関数は 4.2BSD で最初に登場した),
 269 POSIX.1-2001.
 270 .\"O .SH NOTES
 271 .SH 注意
 272 .\"O A child created by
 273 .\"O .BR fork (2)
 274 .\"O inherits its parent's nice value.
 275 .\"O The nice value is preserved across
 276 .\"O .BR execve (2).
 277 .BR fork (2)
 278 で作成された子プロセスは、
 279 親プロセスの nice 値を継承する。
 280 .BR execve (2)
 281 の前後で nice 値は保存される。
 282
 283 .\"O The degree to which their relative nice value affects the scheduling of
 284 .\"O processes varies across UNIX systems, and,
 285 .\"O on Linux, across kernel versions.
 286 .\"O Starting with kernel 2.6.23, Linux adopted an algorithm that causes
 287 .\"O relative differences in nice values to have a much stronger effect.
 288 .\"O This causes very low nice values (+19) to truly provide little CPU
 289 .\"O to a process whenever there is any other
 290 .\"O higher priority load on the system,
 291 .\"O and makes high nice values (\-20) deliver most of the CPU to applications
 292 .\"O that require it (e.g., some audio applications).
 293 相対的な nice 値の違いがプロセス間のスケジューリングにどの程度影響を与えるか
 294 は、UNIX システム間で異なり、Linux ではカーネルバージョンにより異なる。
 295 Linux は、カーネル 2.6.23 以降で、nice 値の相対的な違いが、非常に強い影響を
 296 与えるアルゴリズムを採用した。このアルゴリズムでは、
 297 他に優先度の高いものがシステムに存在する時には、
 298 非常に低い nice 値 (+19) ではプロセスに本当にほとんど CPU が割り当てられない。
 299 また、高い nice 値 (\-20) では CPU を必要とするアプリケーション (例えば
 300 オーディオ・アプリケーション) に CPU のほとんどが割り当てられる。
 301
 302 .\"O The details on the condition for
 303 .\"O .B EPERM
 304 .\"O depend on the system.
 305 .B EPERM
 306 が発生する条件の詳細はシステムに依存する。
 307 .\"O The above description is what POSIX.1-2001 says, and seems to be followed on
 308 .\"O all System V-like systems.
 309 上記の説明は POSIX.1-2001 のものであり、全ての System V 風システムは
 310 これに従っているようである。
 311 .\"O Linux kernels before 2.6.12 required the real or
 312 .\"O effective user ID of the caller to match
 313 .\"O the real user of the process \fIwho\fP (instead of its effective user ID).
 314 2.6.12 より前の Linux カーネルでは、呼び出し元の実 UID または
 315 実効 UID がプロセス \fIwho\fP の (実効 UID でなく)
 316 実 UID に一致する必要がある。
 317 .\"O Linux 2.6.12 and later require
 318 .\"O the effective user ID of the caller to match
 319 .\"O the real or effective user ID of the process \fIwho\fP.
 320 .\"O All BSD-like systems (SunOS 4.1.3, Ultrix 4.2,
 321 .\"O 4.3BSD, FreeBSD 4.3, OpenBSD-2.5, ...) behave in the same
 322 .\"O manner as Linux 2.6.12 and later.
 323 Linux 2.6.12 以降では、呼び出し元の実行 UID がプロセス \fIwho\fP
 324 の実 UID か実効 UID のいずれかと一致する必要がある。
 325 全ての BSD 風システム (SunOS 4.1.3, Ultrix 4.2,
 326 4.3BSD, FreeBSD 4.3, OpenBSD-2.5等) は、
 327 Linux 2.6.12 以降と同じ動作をする。
 328 .LP
 329 .\"O The actual priority range varies between kernel versions.
 330 .\"O Linux before 1.3.36 had \-infinity..15.
 331 .\"O Since kernel 1.3.43 Linux has the range \-20..19.
 332 .\"O Within the kernel, nice values are actually represented
 333 .\"O using the corresponding range 40..1
 334 .\"O (since negative numbers are error codes) and these are the values
 335 .\"O employed by the
 336 .\"O .BR setpriority ()
 337 .\"O and
 338 .\"O .BR getpriority ()
 339 .\"O system calls.
 340 .\"O The glibc wrapper functions for these system calls handle the
 341 .\"O translations between the user-land and kernel representations
 342 .\"O of the nice value according to the formula
 343 .\"O .IR "unice\ =\ 20\ \-\ knice" .
 344 実際の優先度の値の範囲はカーネルのバージョンによって異なる。
 345 1.3.36 より前の Linux では、優先度の範囲は負の無限大 〜 15 である。
 346 1.3.43 以降の Linux では、優先度の範囲は \-20 〜 19 である。
 347 カーネル内部では、nice 値は実際には 40 〜 1 の範囲を使って
 348 表現されており (負の値はエラーコードとなるため)、こちらの値が
 349 システムコール
 350 .BR setpriority ()
 351 と
 352 .BR getpriority ()
 353 で使用されている。
 354 glibc のこれらのシステムコールのラッパー関数において、nice 値の
 355 ユーザ領域 (user-land) とカーネル表現の間の変換が行われる。
 356 変換式は以下の通り:
 357 .I "unice\ =\ 20\ \-\ knice"
 358 .LP
 359 .\"O On some systems, the range of nice values is \-20..20.
 360 いくつかのシステムでは、nice 値の範囲は \20 〜 20 である。
 361 .LP
 362 .\"O Including
 363 .\"O .I <sys/time.h>
 364 .\"O is not required these days, but increases portability.
 365 .\"O (Indeed,
 366 .\"O .I <sys/resource.h>
 367 .\"O defines the
 368 .\"O .I rusage
 369 .\"O structure with fields of type
 370 .\"O .I struct timeval
 371 .\"O defined in
 372 .\"O .IR <sys/time.h> .)
 373 現在では
 374 .I <sys/time.h>
 375 をインクルードする必要はないが、インクルードすれば移植性を高めることができる
 376 (実際には
 377 .I <sys/resource.h>
 378 で
 379 .I rusage
 380 構造体が定義されているが、そのフィールドで使用されている
 381 .I struct timeval
 382 型は
 383 .I <sys/time.h>
 384 で定義されている)。
 385 .\"O .SH "SEE ALSO"
 386 .SH 関連項目
 387 .BR nice (1),
 388 .BR renice (1),
 389 .BR fork (2),
 390 .BR capabilities (7)
 391 .sp
 392 .\"O .I Documentation/scheduler/sched-nice-design.txt
 393 .\"O in the kernel source tree (since Linux 2.6.23).
 394 (Linux 2.6.23 以降の) カーネルのソースツリー内の
 395 .I Documentation/scheduler/sched-nice-design.txt