.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
.\"     <mtk.manpages@gmail.com>
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.\"
.\" Japanese Version Copyright (c) 2012  Akihiro MOTOKI
.\"         all rights reserved.
.\" Translated 2012-05-04, Akihiro MOTOKI <amotoki@gmail.com>
.\"
.TH PTHREAD_SETSCHEDPARAM 3 2014\-12\-31 Linux "Linux Programmer's Manual"
.SH 名前
pthread_setschedparam, pthread_getschedparam \- スレッドの
スケジューリングポリシーとパラメーターを設定/取得する
.SH 書式
.nf
\fB#include <pthread.h>\fP

\fBint pthread_setschedparam(pthread_t \fP\fIthread\fP\fB, int \fP\fIpolicy\fP\fB,\fP
\fB                          const struct sched_param *\fP\fIparam\fP\fB);\fP
\fBint pthread_getschedparam(pthread_t \fP\fIthread\fP\fB, int *\fP\fIpolicy\fP\fB,\fP
\fB                          struct sched_param *\fP\fIparam\fP\fB);\fP
.sp
\fI\-pthread\fP でコンパイルしてリンクする。
.fi
.SH 説明
\fBpthread_setschedparam\fP() 関数は、スレッド \fIthread\fP の
スケジューリングポリシーとスケジューリングパラメーターを設定する。

.\" FIXME . pthread_setschedparam() places no restriction on the policy,
.\" but pthread_attr_setschedpolicy() restricts policy to RR/FIFO/OTHER
.\" http://sourceware.org/bugzilla/show_bug.cgi?id=7013
\fIpolicy\fP は \fIthread\fP の新しいスケジューリングポリシーを指定する。 \fIpolicy\fP に指定できる値とその意味は
\fBsched\fP(7) で説明されている。

\fIparam\fP が指す構造体は \fIthread\fP の新しいスケジューリングパラメーターを
指定する。スケジューリングパラメーターは以下の構造体で管理される。

.in +4n
.nf
struct sched_param {
    int sched_priority;     /* Scheduling priority */
};
.fi
.in

見て分かる通り、サポートされているスケジューリングパラメーターは一つだけである。各スケジューリングポリシーで許可されるスケジューリング優先度の詳細については、\fBsched\fP(7)
を参照のこと。

.\" FIXME . nptl/pthread_setschedparam.c has the following
.\"   /* If the thread should have higher priority because of some
.\"      PTHREAD_PRIO_PROTECT mutexes it holds, adjust the priority. */
.\" Eventually (perhaps after writing the mutexattr pages), we
.\" may want to add something on the topic to this page.
\fBpthread_getschedparam\fP() 関数は、スレッド \fIthread\fP の
スケジューリングポリシーとパラメーターを、
それぞれ \fIpolicy\fP と \fIparam\fP が指すバッファーに入れて返す。
返された優先度の値は、最も最近実行した \fIthread\fP に影響を与える
\fBpthread_setschedparam\fP(), \fBpthread_setschedprio\fP,
\fBpthread_create\fP で設定された値となる。
返された優先度は、優先度の継承や優先度の上限を設定する関数
(例えば \fBpthread_mutexattr_setprioceiling\fP(3) や
\fBpthread_mutexattr_setprotocol\fP(3) を参照) の呼び出しの結果
行われる一時的な優先度の調整の影響を受けない。
.SH 返り値
成功すると、これらの関数は 0 を返す。
エラーの場合、0 以外のエラー番号を返す。
\fBpthread_setschedparam\fP() が失敗した場合、 \fIthread\fP の
スケジューリングポリシーとパラメーターは変更されない。
.SH エラー
これらの関数はどちらも以下のエラーで失敗する場合がある。
.TP 
\fBESRCH\fP
ID が \fIthread\fP のスレッドが見つからなかった。
.PP
\fBpthread_setschedparam\fP() はさらに以下のエラーで失敗する場合がある。
.TP 
\fBEINVAL\fP
\fIpolicy\fP が認識できないポリシーであるか、
\fIparam\fP が \fIpolicy\fP では意味を持たない値である。
.TP 
\fBEPERM\fP
呼び出し側が、指定されたスケジューリングポリシーやパラメーターを設定する
のに必要な特権を持たない。
.PP
.\" .SH VERSIONS
.\" Available since glibc 2.0
POSIX.1\-2001 では、 \fBpthread_setschedparam\fP() に関して
エラー \fBENOTSUP\fP ("サポートされていない値をスケジューリングポリシーや
パラメーターに設定しようとした") も追加で規定されている。
.SH 属性
.SS "マルチスレッディング (pthreads(7) 参照)"
関数 \fBpthread_setschedparam\fP() と \fBpthread_getschedparam\fP() はスレッドセーフである。
.SH 準拠
POSIX.1\-2001.
.SH 注意
スレッドのスケジューリングポリシーや優先度を変更するために必要な許可や変更した場合の影響、および各スケジューリングポリシーで認められる優先度の範囲の詳細については、
\fBsched\fP(7) を参照。
.SH 例
以下のプログラムは \fBpthread_setschedparam\fP() と
\fBpthread_getschedparam\fP() やスケジューリングに関連する pthreads の
他のいろいろな関数の使用例を示すものである。

以下の実行例では、メインスレッドは、自分のスケジューリングポリシーを
優先度 10 の \fBSCHED_FIFO\fP を設定し、スレッド属性オブジェクトを
スケジューリングポリシー属性 \fBSCHED_RR\fP とスケジューリング優先度
属性 20 で初期化する。
次に、このプログラムは (\fBpthread_attr_setinheritsched\fP(3) を使って)
そのスレッド属性オブジェクトの inherit scheduler 属性に
\fBPTHREAD_EXPLICIT_SCHED\fP を設定する。\fBPTHREAD_EXPLICIT_SCHED\fP は、
そのスレッド属性オブジェクトを使って作成されたスレッドはスレッド属性
オブジェクトからスケジューリング属性を取得して使うことを意味する。
それから、このスレッド属性オブジェクトを使ってスレッドを作成し、
作成したスレッドのスケジューリングポリシーと優先度を表示する。
.in +4n
.nf

$ \fBsu\fP      # Need privilege to set real\-time scheduling policies
Password:
# \fB./a.out \-mf10 \-ar20 \-i e\fP
Scheduler settings of main thread
    policy=SCHED_FIFO, priority=10

Scheduler settings in \(aqattr\(aq
    policy=SCHED_RR, priority=20
    inheritsched is EXPLICIT

Scheduler attributes of new thread
    policy=SCHED_RR, priority=20
.fi
.in

上記の出力では、スケジューリングポリシーと優先度がスレッド属性
オブジェクトで指定された値から取られていることが分かる。

次の実行例は前のものと同じだが、 inherit scheduler 属性が
\fBPTHREAD_INHERIT_SCHED\fP に設定される点が異なる。
\fBPTHREAD_INHERIT_SCHED\fP は、そのスレッド属性オブジェクトを使って作成
されたスレッドは、スレッド属性オブジェクトからスケジューリング属性を
無視し、代わりに呼び出したスレッドからスケジューリング属性を取得する
ことを意味する。

.in +4n
.nf
# \fB./a.out \-mf10 \-ar20 \-i i\fP
Scheduler settings of main thread
    policy=SCHED_FIFO, priority=10

Scheduler settings in \(aqattr\(aq
    policy=SCHED_RR, priority=20
    inheritsched is INHERIT

Scheduler attributes of new thread
    policy=SCHED_FIFO, priority=10
.fi
.in

上記の出力では、スケジューリングポリシーと優先度が、
スレッド属性オブジェクトからではなく、
スレッドを作成したスレッドから取れれていることが分かる。

なお、 \fI\-i\ i\fP を省略した場合でも、
\fBPTHREAD_INHERIT_SCHED\fP が inherit scheduler 属性のデフォルト値なので、
出力は同じになる。
.SS プログラムのソース
\&
.nf
/* pthreads_sched_test.c */

#include <pthread.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <errno.h>

#define handle_error_en(en, msg) \e
        do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)

static void
usage(char *prog_name, char *msg)
{
    if (msg != NULL)
        fputs(msg, stderr);

    fprintf(stderr, "Usage: %s [options]\en", prog_name);
    fprintf(stderr, "Options are:\en");
#define fpe(msg) fprintf(stderr, "\et%s", msg);          /* Shorter */
    fpe("\-a<policy><prio> Set scheduling policy and priority in\en");
    fpe("                 thread attributes object\en");
    fpe("                 <policy> can be\en");
    fpe("                     f  SCHED_FIFO\en");
    fpe("                     r  SCHED_RR\en");
    fpe("                     o  SCHED_OTHER\en");
    fpe("\-A               Use default thread attributes object\en");
    fpe("\-i {e|i}         Set inherit scheduler attribute to\en");
    fpe("                 \(aqexplicit\(aq or \(aqinherit\(aq\en");
    fpe("\-m<policy><prio> Set scheduling policy and priority on\en");
    fpe("                 main thread before pthread_create() call\en");
    exit(EXIT_FAILURE);
}

static int
get_policy(char p, int *policy)
{
    switch (p) {
    case \(aqf\(aq: *policy = SCHED_FIFO;     return 1;
    case \(aqr\(aq: *policy = SCHED_RR;       return 1;
    case \(aqo\(aq: *policy = SCHED_OTHER;    return 1;
    default:  return 0;
    }
}

static void
display_sched_attr(int policy, struct sched_param *param)
{
    printf("    policy=%s, priority=%d\en",
            (policy == SCHED_FIFO)  ? "SCHED_FIFO" :
            (policy == SCHED_RR)    ? "SCHED_RR" :
            (policy == SCHED_OTHER) ? "SCHED_OTHER" :
            "???",
            param\->sched_priority);
}

static void
display_thread_sched_attr(char *msg)
{
    int policy, s;
    struct sched_param param;

    s = pthread_getschedparam(pthread_self(), &policy, &param);
    if (s != 0)
        handle_error_en(s, "pthread_getschedparam");

    printf("%s\en", msg);
    display_sched_attr(policy, &param);
}

static void *
thread_start(void *arg)
{
    display_thread_sched_attr("Scheduler attributes of new thread");

    return NULL;
}

int
main(int argc, char *argv[])
{
    int s, opt, inheritsched, use_null_attrib, policy;
    pthread_t thread;
    pthread_attr_t attr;
    pthread_attr_t *attrp;
    char *attr_sched_str, *main_sched_str, *inheritsched_str;
    struct sched_param param;

    /* Process command\-line options */

    use_null_attrib = 0;
    attr_sched_str = NULL;
    main_sched_str = NULL;
    inheritsched_str = NULL;

    while ((opt = getopt(argc, argv, "a:Ai:m:")) != \-1) {
        switch (opt) {
        case \(aqa\(aq: attr_sched_str = optarg;      break;
        case \(aqA\(aq: use_null_attrib = 1;          break;
        case \(aqi\(aq: inheritsched_str = optarg;    break;
        case \(aqm\(aq: main_sched_str = optarg;      break;
        default:  usage(argv[0], "Unrecognized option\en");
        }
    }

    if (use_null_attrib &&
            (inheritsched_str != NULL || attr_sched_str != NULL))
        usage(argv[0], "Can\(aqt specify \-A with \-i or \-a\en");

    /* Optionally set scheduling attributes of main thread,
       and display the attributes */

    if (main_sched_str != NULL) {
        if (!get_policy(main_sched_str[0], &policy))
            usage(argv[0], "Bad policy for main thread (\-m)\en");
        param.sched_priority = strtol(&main_sched_str[1], NULL, 0);

        s = pthread_setschedparam(pthread_self(), policy, &param);
        if (s != 0)
            handle_error_en(s, "pthread_setschedparam");
    }

    display_thread_sched_attr("Scheduler settings of main thread");
    printf("\en");

    /* Initialize thread attributes object according to options */

    attrp = NULL;

    if (!use_null_attrib) {
        s = pthread_attr_init(&attr);
        if (s != 0)
            handle_error_en(s, "pthread_attr_init");
        attrp = &attr;
    }

    if (inheritsched_str != NULL) {
        if (inheritsched_str[0] == \(aqe\(aq)
            inheritsched = PTHREAD_EXPLICIT_SCHED;
        else if (inheritsched_str[0] == \(aqi\(aq)
            inheritsched = PTHREAD_INHERIT_SCHED;
        else
            usage(argv[0], "Value for \-i must be \(aqe\(aq or \(aqi\(aq\en");

        s = pthread_attr_setinheritsched(&attr, inheritsched);
        if (s != 0)
            handle_error_en(s, "pthread_attr_setinheritsched");
    }

    if (attr_sched_str != NULL) {
        if (!get_policy(attr_sched_str[0], &policy))
            usage(argv[0],
                    "Bad policy for \(aqattr\(aq (\-a)\en");
        param.sched_priority = strtol(&attr_sched_str[1], NULL, 0);

        s = pthread_attr_setschedpolicy(&attr, policy);
        if (s != 0)
            handle_error_en(s, "pthread_attr_setschedpolicy");
        s = pthread_attr_setschedparam(&attr, &param);
        if (s != 0)
            handle_error_en(s, "pthread_attr_setschedparam");
    }

    /* If we initialized a thread attributes object, display
       the scheduling attributes that were set in the object */

    if (attrp != NULL) {
        s = pthread_attr_getschedparam(&attr, &param);
        if (s != 0)
            handle_error_en(s, "pthread_attr_getschedparam");
        s = pthread_attr_getschedpolicy(&attr, &policy);
        if (s != 0)
            handle_error_en(s, "pthread_attr_getschedpolicy");

        printf("Scheduler settings in \(aqattr\(aq\en");
        display_sched_attr(policy, &param);

        s = pthread_attr_getinheritsched(&attr, &inheritsched);
        printf("    inheritsched is %s\en",
                (inheritsched == PTHREAD_INHERIT_SCHED)  ? "INHERIT" :
                (inheritsched == PTHREAD_EXPLICIT_SCHED) ? "EXPLICIT" :
                "???");
        printf("\en");
    }

    /* Create a thread that will display its scheduling attributes */

    s = pthread_create(&thread, attrp, &thread_start, NULL);
    if (s != 0)
        handle_error_en(s, "pthread_create");

    /* Destroy unneeded thread attributes object */

    if (!use_null_attrib) {
      s = pthread_attr_destroy(&attr);
      if (s != 0)
          handle_error_en(s, "pthread_attr_destroy");
    }

    s = pthread_join(thread, NULL);
    if (s != 0)
        handle_error_en(s, "pthread_join");

    exit(EXIT_SUCCESS);
}
.fi
.SH 関連項目
.ad l
.nh
\fBgetrlimit\fP(2), \fBsched_get_priority_min\fP(2), \fBpthread_attr_init\fP(3),
\fBpthread_attr_setinheritsched\fP(3), \fBpthread_attr_setschedparam\fP(3),
\fBpthread_attr_setschedpolicy\fP(3), \fBpthread_create\fP(3), \fBpthread_self\fP(3),
\fBpthread_setschedprio\fP(3), \fBpthreads\fP(7), \fBsched\fP(7)
.SH この文書について
この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.79 の一部
である。プロジェクトの説明とバグ報告に関する情報は
http://www.kernel.org/doc/man\-pages/ に書かれている。