release/man2/getcontext.2

   1 .\" Copyright (C) 2001 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\"
  23 .\" Japanese Version Copyright (c) 2001 NAKANO Takeo all rights reserved.
  24 .\" Translated Sat Dec 15 2001 by NAKANO Takeo <nakano@apm.seikei.ac.jp>
  25 .\" Updated 2009-04-13, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.20
  26 .\"
  27 .TH GETCONTEXT 2 2009-03-15 "Linux" "Linux Programmer's Manual"
  28 .SH 名前
  29 getcontext, setcontext \- ユーザコンテキストを取得/設定する
  30 .SH 書式
  31 .B #include <ucontext.h>
  32 .sp
  33 .BI "int getcontext(ucontext_t *" ucp );
  34 .br
  35 .BI "int setcontext(const ucontext_t *" ucp );
  36 .SH 説明
  37 System V 的な環境では、
  38 \fImcontext_t\fP および \fIucontext_t\fP という 2 つの型と、
  39 .BR getcontext (),
  40 .BR setcontext (),
  41 .BR makecontext (3),
  42 .BR swapcontext (3)
  43 という 4 つの関数が
  44 .I <ucontext.h>
  45 で定義されており、あるプロセス内部で制御下にある複数のスレッド間で、
  46 ユーザレベルのコンテキスト切替えができるようになっている。
  47 .LP
  48 \fImcontext_t\fP 型はマシン依存で、外部からは隠蔽されている。
  49 \fIucontext_t\fP 型は構造体で、少なくとも以下の 4 つのフィールドを持つ。
  50 .in +4
  51 .nf
  52
  53 typedef struct ucontext {
  54     struct ucontext *uc_link;
  55     sigset_t         uc_sigmask;
  56     stack_t          uc_stack;
  57     mcontext_t       uc_mcontext;
  58     ...
  59 } ucontext_t;
  60
  61 .fi
  62 .in
  63 \fIsigset_t\fP と \fIstack_t\fP は
  64 .I <signal.h>
  65 で定義されている。
  66 ここで \fIuc_link\fP は、
  67 現在のコンテキストが終了したとき、
  68 続いて切り替わるコンテキストへのポインタである
  69 (現在のコンテキストが
  70 .BR makecontext (3)
  71 で生成されたものの場合)。
  72 \fIuc_sigmask\fP はこのコンテキストでブロックされている
  73 シグナル群である
  74 .RB ( sigprocmask (2)
  75 を見よ)。
  76 \fIuc_stack\fP はこのコンテキストが用いているスタックである
  77 .RB ( signalstack (2)
  78 を見よ)。
  79 \fIuc_mcontext\fP は保存されているコンテキストの
  80 マシン特有の表現形式であり、
  81 ここには呼び出したスレッドのマシンレジスタが格納される。
  82 .LP
  83 .BR getcontext ()
  84 関数は、
  85 ポインタ \fIucp\fP が指す構造体を、
  86 現在アクティブなコンテキストに初期化する。
  87 .LP
  88 .BR setcontext ()
  89 関数は、ポインタ
  90 \fIucp\fP が指すユーザコンテキストをリストアする。
  91 呼び出しに成功すると返らない。
  92 このコンテキストは、以前に
  93 .BR getcontext ()
  94 または
  95 .BR makecontext (3)
  96 で得られたものか、
  97 あるいはシグナルの第三引数として与えられたものになる。
  98 .LP
  99 コンテキストが
 100 .BR getcontext ()
 101 の呼び出しによって得られていたものの場合は、
 102 プログラムはこの呼び出しから返った直後からのように実行を継続する。
 103 .LP
 104 コンテキストが
 105 .BR makecontext (3)
 106 の呼び出しによって得られていたものの場合は、
 107 プログラムの実行はその
 108 .BR makecontext (3)
 109 呼び出しの第二引数で指定された関数 \fIfunc\fP
 110 を呼び出すかたちで継続する。
 111 \fIfunc\fP から返ると、
 112 .BR makecontext (3)
 113 呼び出しの第一引数で指定されていた
 114 \fIucp\fP 構造体の \fIuc_link\fP メンバで継続する。
 115 このメンバが NULL だった場合は、そのスレッドは終了する。
 116 .LP
 117 コンテキストがシグナルハンドラの呼び出しによって得られていたものの場合は、
 118 古い標準によれば
 119 「プログラムの実行はシグナルによって割り込まれた命令の次の命令から継続される」。
 120 しかしこの文は SUSv2 で削除されたので、
 121 現在の判断は「結果は定義されていない」である。
 122 .SH 返り値
 123 成功すると、
 124 .BR getcontext ()
 125 は 0 を返し、
 126 .BR setcontext ()
 127 は返らない。
 128 失敗すると、両者とも \-1 を返し、\fIerrno\fP をエラーに応じて設定する。
 129 .SH エラー
 130 定義されていない。
 131 .SH 準拠
 132 SUSv2, POSIX.1-2001.
 133 POSIX.1-2008 では、移植性の問題から
 134 .BR getcontext ()
 135 の仕様が削除された。
 136 代わりに、アプリケーションを POSIX スレッドを使って書き直すことが
 137 推奨されている。
 138 .SH 注意
 139 このメカニズムの最古の実装は、
 140 .BR setjmp (3)/ longjmp (3)
 141 機構であった。
 142 これらにはシグナルコンテキストの取り扱いが定義されていなかったので、
 143 次の段階では
 144 .BR sigsetjmp (3)/ siglongjmp (3)
 145 のペアが現われた。
 146 現在の機構ではずっと細かな制御ができる。
 147 一方
 148 .BR getcontext ()
 149 から返ったとき、
 150 これが最初の呼び出しであったか、
 151 それとも
 152 .BR setcontext ()
 153 呼び出しからのものであるかを
 154 区別する容易な方法がなくなってしまった。
 155 ユーザは「しおり」機構を自分で作らなければならない。
 156 レジスタ変数は (レジスタはリストアされてしまうので) これをやってくれない。
 157 .LP
 158 シグナルが発生すると、
 159 現在のユーザコンテキストは保存され、
 160 シグナルハンドラ用のコンテキストがカーネルによって生成される。
 161 今後はハンドラに
 162 .BR longjmp (3)
 163 を使わせないこと:
 164 この関数のコンテキスト下での動作は定義されていない。
 165 代わりに
 166 .BR siglongjmp (3)
 167 か
 168 .BR setcontext ()
 169 を使うこと。
 170 .SH 関連項目
 171 .BR sigaction (2),
 172 .BR sigaltstack (2),
 173 .BR sigprocmask (2),
 174 .BR longjmp (3),
 175 .BR makecontext (3),
 176 .BR sigsetjmp (3)