getcontextのヘルプ・マニュアル
日本語 英語
getcontext --help
man getcontext
GETCONTEXT(2) Linux Programmer’s Manual GETCONTEXT(2)
名前
getcontext, setcontext - ユーザコンテキストを取得/設定する
書式
#include
int getcontext(ucontext_t *ucp);
int setcontext(const ucontext_t *ucp);
説明
System V 的な環境では、 mcontext_t および ucontext_t という 2 つの型と
、 getcontext(), setcontext(), makecontext(3), swapcontext(3) という 4
つ の関数が で定義されており、あるプロセス内部で制御下にあ
る複数のスレッド間で、ユーザレベルのコンテキスト切替えができるように な
っている。
mcontext_t 型はマシン依存で、外部からは隠蔽されている。 ucontext_t 型は
構造体で、少なくとも以下の 4 つのフィールドを持つ。
typedef struct ucontext {
struct ucontext *uc_link;
sigset_t uc_sigmask;
stack_t uc_stack;
mcontext_t uc_mcontext;
...
} ucontext_t;
sigset_t と stack_t は で定義されている。ここで uc_link は、
現 在のコンテキストが終了したとき、続いて切り替わるコンテキストへのポイ
ンタである (現在のコンテキストが makecontext(3) で生成されたものの場合)
。 uc_sigmask はこのコンテキストでブロックされているシグナル群である
(sigprocmask(2) を見よ)。 uc_stack はこのコンテキストが用いているスタッ
クである (signalstack(2) を見よ)。 uc_mcontext は保存されているコンテキ
ストのマシン特有の表現形式であり、ここには呼び出したスレッドのマシン レ
ジスタが格納される。
getcontext() 関数は、ポインタ ucp が指す構造体を、現在アクティブなコン
テキストに初期化する。
setcontext() 関数は、ポインタ ucp が指すユーザコンテキストをリストア す
る 。 呼 び出しに成功すると返らない。このコンテキストは、以前に getcon-
text() または makecontext(3) で得られたものか、あるいはシグナルの第三引
数として与えられたものになる。
コ ンテキストが getcontext() の呼び出しによって得られていたものの場合は
、プログラムはこの呼び出しから返った直後からのように実行を継続する。
コンテキストが makecontext(3) の呼び出しによって得られていたものの場 合
は 、プログラムの実行はその makecontext(3) 呼び出しの第二引数で指定され
た関数 func を呼び出すかたちで継続する。 func から返 る と 、 makecon-
text(3) 呼び出しの第一引数で指定されていた ucp 構造体の uc_link メンバ
で継続する。このメンバが NULL だった場合は、そのスレッドは終了する。
コンテキストがシグナルハンドラの呼び出しによって得られていたものの場 合
は 、古い標準によれば「プログラムの実行はシグナルによって割り込まれた命
令の次の命令から継続される」。しかしこの文は SUSv2 で削除されたので、現
在の判断は「結果は定義されていない」である。
返り値
成功すると、 getcontext() は 0 を返し、 setcontext() は返らない。失敗す
ると、両者とも -1 を返し、errno をエラーに応じて設定する。
エラー
定義されていない。
準拠
SUSv2, POSIX.1-2001. POSIX.1-2008 では、移植性の問題から getcontext()
の仕様が削除された。代わりに、アプリケーションを POSIX スレッドを使って
書き直すことが推奨されている。
注意
このメカニズムの最古の実装は、 setjmp(3)/longjmp(3) 機構であった。こ れ
ら にはシグナルコンテキストの取り扱いが定義されていなかったので、次の段
階では sigsetjmp(3)/siglongjmp(3) のペアが現われた。現在の機構ではず っ
と 細かな制御ができる。一方 getcontext() から返ったとき、これが最初の呼
び出しであったか、それとも setcontext() 呼び出しからのものであるかを 区
別 する容易な方法がなくなってしまった。ユーザは「しおり」機構を自分で作
らなければならない。レジスタ変数は (レジスタはリストアされてしまうので)
これをやってくれない。
シ グナルが発生すると、現在のユーザコンテキストは保存され、シグナルハン
ドラ用のコンテキストがカーネルによって生成される。今後は ハ ン ド ラ に
longjmp(3) を使わせないこと: この関数のコンテキスト下での動作は定義され
ていない。代わりに siglongjmp(3) か setcontext() を使うこと。
関連項目
sigaction(2), sigaltstack(2), sigprocmask(2), longjmp(3), makecon-
text(3), sigsetjmp(3)
Linux 2009-03-15 GETCONTEXT(2)
GETCONTEXT(2) Linux Programmer’s Manual GETCONTEXT(2)
NAME
getcontext, setcontext - get or set the user context
SYNOPSIS
#include
int getcontext(ucontext_t *ucp);
int setcontext(const ucontext_t *ucp);
DESCRIPTION
In a System V-like environment, one has the two types mcontext_t and
ucontext_t defined in and the four functions getcontext(),
setcontext(), makecontext(3) and swapcontext(3) that allow user-level
context switching between multiple threads of control within a process.
The mcontext_t type is machine-dependent and opaque. The ucontext_t
type is a structure that has at least the following fields:
typedef struct ucontext {
struct ucontext *uc_link;
sigset_t uc_sigmask;
stack_t uc_stack;
mcontext_t uc_mcontext;
...
} ucontext_t;
with sigset_t and stack_t defined in . Here uc_link points
to the context that will be resumed when the current context terminates
(in case the current context was created using makecontext(3)), uc_sig-
mask is the set of signals blocked in this context (see sigproc-
mask(2)), uc_stack is the stack used by this context (see sigalt-
stack(2)), and uc_mcontext is the machine-specific representation of
the saved context, that includes the calling thread’s machine regis-
ters.
The function getcontext() initializes the structure pointed at by ucp
to the currently active context.
The function setcontext() restores the user context pointed at by ucp.
A successful call does not return. The context should have been
obtained by a call of getcontext(), or makecontext(3), or passed as
third argument to a signal handler.
If the context was obtained by a call of getcontext(), program execu-
tion continues as if this call just returned.
If the context was obtained by a call of makecontext(3), program execu-
tion continues by a call to the function func specified as the second
argument of that call to makecontext(3). When the function func
returns, we continue with the uc_link member of the structure ucp spec-
ified as the first argument of that call to makecontext(3). When this
member is NULL, the thread exits.
If the context was obtained by a call to a signal handler, then old
standard text says that "program execution continues with the program
instruction following the instruction interrupted by the signal". How-
ever, this sentence was removed in SUSv2, and the present verdict is
"the result is unspecified".
RETURN VALUE
When successful, getcontext() returns 0 and setcontext() does not
return. On error, both return -1 and set errno appropriately.
ERRORS
None defined.
CONFORMING TO
SUSv2, POSIX.1-2001. POSIX.1-2008 removes the specification of getcon-
text(), citing portability issues, and recommending that applications
be rewritten to use POSIX threads instead.
NOTES
The earliest incarnation of this mechanism was the setjmp(3)/longjmp(3)
mechanism. Since that does not define the handling of the signal con-
text, the next stage was the sigsetjmp(3)/siglongjmp(3) pair. The
present mechanism gives much more control. On the other hand, there is
no easy way to detect whether a return from getcontext() is from the
first call, or via a setcontext() call. The user has to invent her own
bookkeeping device, and a register variable won’t do since registers
are restored.
When a signal occurs, the current user context is saved and a new con-
text is created by the kernel for the signal handler. Do not leave the
handler using longjmp(3): it is undefined what would happen with con-
texts. Use siglongjmp(3) or setcontext() instead.
SEE ALSO
sigaction(2), sigaltstack(2), sigprocmask(2), longjmp(3), makecon-
text(3), sigsetjmp(3)
COLOPHON
This page is part of release 3.22 of the Linux man-pages project. A
description of the project, and information about reporting bugs, can
be found at http://www.kernel.org/doc/man-pages/.
Linux 2009-03-15 GETCONTEXT(2)