[linuxjm/LDP_man-pages.git] / draft / man2 / sigaltstack.2

'\" t
.\" Copyright (c) 2001, Michael Kerrisk (mtk.manpages@gmail.com)
.\"
.\" 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.
.\"
.\" aeb, various minor fixes
.\"
.\" Japanese Version Copyright (c) 2001 Yuichi SATO
.\"         all rights reserved.
.\" Translated 2001-11-04, Yuichi SATO <ysato@h4.dion.ne.jp>
.\" Updated 2001-12-09, Yuichi SATO
.\" Updated 2005-11-04, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
.\" Updated 2006-01-04, Akihiro MOTOKI, Catch up to LDP 2.20
.\"
.\"WORD:        alternate signal stack  代替シグナルスタック
.\"WORD:        establish       (スタックの) 確立
.\"
.TH SIGALTSTACK 2 2010-09-26 "Linux" "Linux Programmer's Manual"
.\"O .SH NAME
.SH 名前
.\"O sigaltstack \- set and/or get signal stack context
sigaltstack \- シグナルスタックのコンテキストを設定・取得する
.\"O .SH SYNOPSIS
.SH 書式
.B #include <signal.h>
.sp
.BI "int sigaltstack(const stack_t *" ss ", stack_t *" oss );
.sp
.in -4n
.\"O Feature Test Macro Requirements for glibc (see
.\"O .BR feature_test_macros (7)):
glibc 向けの機能検査マクロの要件
.RB ( feature_test_macros (7)
参照):
.in
.sp
.BR sigaltstack ():
.ad l
.RS 4
.PD 0
_BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 ||
_XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
.br
.\"O || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L
|| /* glibc 2.12 以降: */ _POSIX_C_SOURCE\ >=\ 200809L
.PD
.RE
.ad
.\"O .SH DESCRIPTION
.SH 説明
.\"O .BR sigaltstack ()
.\"O allows a process to define a new alternate
.\"O signal stack and/or retrieve the state of an existing
.\"O alternate signal stack.
.\"O An alternate signal stack is used during the
.\"O execution of a signal handler if the establishment of that handler (see
.\"O .BR sigaction (2))
.\"O requested it.
.BR sigaltstack ()
を使うと、
プロセスは新しい代替シグナルスタックを定義したり、
既存の代替シグナルスタックの状態を取得できる。
シグナルハンドラが代替シグナルスタックを要求するように設定されていると
.RB ( sigaction (2)
参照)、ハンドラの実行中はそのシグナルスタックが使われる。

.\"O The normal sequence of events for using an alternate signal stack
.\"O is the following:
代替シグナルスタックを使う際の一般的な手順は、以下の通りである:
.TP 3
1.
.\"O Allocate an area of memory to be used for the alternate
.\"O signal stack.
代替シグナルスタックで使うメモリ領域を確保する。
.TP
2.
.\"O Use
.\"O .BR sigaltstack ()
.\"O to inform the system of the existence and
.\"O location of the alternate signal stack.
.BR sigaltstack ()
を使って、
代替シグナルスタックの存在と場所をシステムに知らせる。
.TP
3.
.\"O When establishing a signal handler using
.\"O .BR sigaction (2),
.\"O inform the system that the signal handler should be executed
.\"O on the alternate signal stack by
.\"O specifying the \fBSA_ONSTACK\fP flag.
.BR sigaction (2)
を使ってシグナルハンドラを確立する際、
\fBSA_ONSTACK\fP フラグを指定することにより、
そのシグナルハンドラを代替シグナルスタック上で実行することを
システムに知らせる。
.P
.\"O The \fIss\fP argument is used to specify a new
.\"O alternate signal stack, while the \fIoss\fP argument
.\"O is used to retrieve information about the currently
.\"O established signal stack.
\fIss\fP 引き数は、新しいシグナルスタックを指定するために使う。
また \fIoss\fP 引き数は、現在確立されている
シグナルスタックの情報を取得するために使う。
.\"O If we are interested in performing just one
.\"O of these tasks then the other argument can be specified as NULL.
.\"O Each of these arguments is a structure of the following type:
この操作のうち 1 つだけを実行させるには、
使用しない引き数を NULL に指定すればよい。
引き数となる構造体は、以下のような型である:
.sp
.in +4n
.nf
typedef struct {
.\"O     void  *ss_sp;     /* Base address of stack */
    void  *ss_sp;     /* スタックのベースアドレス */
.\"O     int    ss_flags;  /* Flags */
    int    ss_flags;  /* フラグ */
.\"O     size_t ss_size;   /* Number of bytes in stack */
    size_t ss_size;   /* スタックのバイト数 */
} stack_t;
.fi
.in

.\"O To establish a new alternate signal stack,
.\"O \fIss.ss_flags\fP is set to zero, and \fIss.ss_sp\fP and
.\"O \fIss.ss_size\fP specify the starting address and size of
.\"O the stack.
新規の代替シグナルスタックを確立するには、
\fIss.ss_flags\fP を 0 に設定し、
\fIss.ss_sp\fP と \fIss.ss_size\fP に
スタックの開始アドレスとスタックサイズを指定する。
.\"O The constant \fBSIGSTKSZ\fP is defined to be large enough
.\"O to cover the usual size requirements for an alternate signal stack,
.\"O and the constant \fBMINSIGSTKSZ\fP defines the minimum
.\"O size required to execute a signal handler.
定数 \fBSIGSTKSZ\fP は、代替シグナルスタックが通常必要する
サイズよりも充分大きく定義されている。
また定数 \fBMINSIGSTKSZ\fP は、
シグナルハンドラの実行に必要な最小サイズに定義されている。

.\"O When a signal handler is invoked on the alternate stack,
.\"O the kernel automatically aligns the address given in \fIss.ss_sp\fP
.\"O to a suitable address boundary for the underlying hardware architecture.
代替スタックでシグナルハンドラが起動された場合には、
カーネルにより自動的に、\fIss.ss_sp\fP で指定されたアドレスは
動作しているハードウェアアーキテクチャに適したアドレス境界に
調整される。

.\"O To disable an existing stack, specify \fIss.ss_flags\fP
.\"O as \fBSS_DISABLE\fP.
.\"O In this case, the remaining fields
.\"O in \fIss\fP are ignored.
既存のスタックを無効にするには、
\fIss.ss_flags\fP を \fBSS_DISABLE\fP に指定する。
この場合、\fIss\fP の他のフィールドは無視される。

.\"O If \fIoss\fP is not NULL, then it is used to return information about
.\"O the alternate signal stack which was in effect prior to the
.\"O call to
.\"O .BR sigaltstack ().
\fIoss\fP が NULL 以外の場合、
\fIoss\fP に代替シグナルスタックの情報が返される。
これは (実質的に)
.BR sigaltstack ()
の呼び出しより先に行われる。
.\"O The \fIoss.ss_sp\fP and \fIoss.ss_size\fP fields return the starting
.\"O address and size of that stack.
.\"O The \fIoss.ss_flags\fP may return either of the following values:
\fIoss.ss_sp\fP と \fIoss.ss_size\fP フィールドに
スタックの開始アドレスとスタックサイズが返される。
\fIoss.ss_flags\fP には以下のどちらかの値が返される:
.TP
.B SS_ONSTACK
.\"O The process is currently executing on the alternate signal stack.
.\"O (Note that it is not possible
.\"O to change the alternate signal stack if the process is
.\"O currently executing on it.)
プロセスが代替シグナルスタック上で実行されている
(プロセスが既にそのシグナルスタック上で実行されている場合は、
それと同じシグナルスタックには変更できない点に注意すること)。
.TP
.B SS_DISABLE
.\"O The alternate signal stack is currently disabled.
代替シグナルスタックが現在無効になっている。
.\"O .SH "RETURN VALUE"
.SH 返り値
.\"O .BR sigaltstack ()
.\"O returns 0 on success, or \-1 on failure with
.\"O \fIerrno\fP set to indicate the error.
.BR sigaltstack ()
は成功した場合 0 を返す。
失敗した場合は \-1 を返して、
エラーを示す値に \fIerrno\fP を設定する。
.\"O .SH ERRORS
.SH エラー
.TP
.B EFAULT
.\"O Either \fIss\fP or \fIoss\fP is not NULL and points to an area
.\"O outside of the process's address space.
\fIss\fP または \fIoss\fP のどちらが、NULL 以外で、
かつプロセスのアドレス空間の外を指している。
.TP
.B EINVAL
.\"O \fIss\fP is not NULL and the \fIss_flags\fP field contains
.\"O a nonzero value other than
.\"O .BR SS_DISABLE .
\fIss\fP が NULL 以外で、\fIss_flags\fP フィールドが
.B SS_DISABLE
以外の 0 でない値になっている。
.TP
.B ENOMEM
.\"O The specified size of the new alternate signal stack
.\"O (\fIss.ss_size\fP) was less than \fBMINSTKSZ\fP.
新しい代替シグナルスタック (\fIss.ss_size\fP) に指定したサイズが
\fBMINSTKSZ\fP より小さい。
.TP
.B EPERM
.\"O An attempt was made to change the alternate signal stack while
.\"O it was active (i.e., the process was already executing
.\"O on the current alternate signal stack).
代替シグナルスタックが有効であるときに変更を行おうとした
(つまり、プロセスが既に現在の代替シグナルスタック上で実行されていた)。
.\"O .SH "CONFORMING TO"
.SH 準拠
SUSv2, SVr4, POSIX.1-2001.
.\"O .SH NOTES
.SH 注意
.\"O The most common usage of an alternate signal stack is to handle the
.\"O .B SIGSEGV
.\"O signal that is generated if the space available for the
.\"O normal process stack is exhausted: in this case, a signal handler for
.\"O .B SIGSEGV
.\"O cannot be invoked on the process stack; if we wish to handle it,
.\"O we must use an alternate signal stack.
代替シグナルスタックを使用する最もよくある場面は、
.B SIGSEGV
シグナルを扱うときである。
.B SIGSEGV
はプロセスの通常のスタックが利用できる空間が使い果たされた際に
生成されるシグナルである。この場合には、
.B SIGSEGV
用のシグナルハンドラをプロセスのスタック上では起動することができない。
そのため、このシグナルを扱おうとする場合には、
代替シグナルスタックを使用しなければならない。
.P
.\"O Establishing an alternate signal stack is useful if a process
.\"O expects that it may exhaust its standard stack.
プロセスが標準のシグナルスタックを使い果たすことが予想される場合は、
代替シグナルスタックを確立すると便利である。
.\"O This may occur, for example, because the stack grows so large
.\"O that it encounters the upwardly growing heap, or it reaches a
.\"O limit established by a call to \fBsetrlimit(RLIMIT_STACK, &rlim)\fP.
例えば、スタックが最上位アドレスから
下位アドレス方向に非常にたくさん積まれてしまうことで、
最下位アドレスから上位アドレス方向に積まれるヒープとぶつかってしまう場合や、
\fBsetrlimit(RLIMIT_STACK, &rlim)\fP の呼び出しで確立された
制限に達してしまった場合に、この様な事が起こる。
.\"O If the standard stack is exhausted, the kernel sends
.\"O the process a \fBSIGSEGV\fP signal.
.\"O In these circumstances the only way to catch this signal is
.\"O on an alternate signal stack.
標準のスタックを使い果たしてしまうと、
カーネルはプロセスに \fBSIGSEGV\fP シグナルを送る。
このような状況では、代替シグナルスタック上でしかシグナルをキャッチできない。
.P
.\"O On most hardware architectures supported by Linux, stacks grow
.\"O downward.
.\"O .BR sigaltstack ()
.\"O automatically takes account
.\"O of the direction of stack growth.
Linux がサポートする多くのハードウェアアーキテクチャでは、
スタックは下位アドレス方向に積まれる。
.BR sigaltstack ()
はスタックが積まれる方向を自動的に決定する。
.P
.\"O Functions called from a signal handler executing on an alternate
.\"O signal stack will also use the alternate signal stack.
.\"O (This also applies to any handlers invoked for other signals while
.\"O the process is executing on the alternate signal stack.)
.\"O Unlike the standard stack, the system does not
.\"O automatically extend the alternate signal stack.
.\"O Exceeding the allocated size of the alternate signal stack will
.\"O lead to unpredictable results.
代替シグナルスタック上で実行されている
シグナルハンドラから呼ばれる関数も、代替シグナルハンドラを使う
(プロセスが代替シグナルスタック上で実行されている場合、
他のシグナルで呼び出されるハンドラもこの代替シグナルハンドラを使う)。
標準のスタックとは異なり、
システムは代替シグナルスタックを自動的に拡張しない。
代替シグナルスタック用に確保したサイズを越えた場合、
結果は予想できない。
.P
.\"O A successful call to
.\"O .BR execve (2)
.\"O removes any existing alternate
.\"O signal stack.
.\"O A child process created via
.\"O .BR fork (2)
.\"O inherits a copy of its parent's alternate signal stack settings.
.BR execve (2)
の呼び出しが成功すると、
既存の全ての代替シグナルスタックが削除される。
.BR fork (2)
経由で作成された子プロセスは、親プロセスの代替シグナルスタックの
設定のコピーを継承する。
.P
.\"O .BR sigaltstack ()
.\"O supersedes the older
.\"O .BR sigstack ()
.\"O call.
.\"O For backward compatibility, glibc also provides
.\"O .BR sigstack ().
.\"O All new applications should be written using
.\"O .BR sigaltstack ().
.BR sigaltstack ()
は以前の
.BR sigstack ()
を置き換えるものである。
過去プログラムとの互換性のため、glibc では
.BR sigstack ()
も提供している。
新しいのアプリケーションは全て
.BR sigaltstack ()
を使って書くべきである。
.\"O .SS History
.SS 歴史
.\"O 4.2BSD had a
.\"O .BR sigstack ()
.\"O system call.
.\"O It used a slightly
.\"O different struct, and had the major disadvantage that the caller
.\"O had to know the direction of stack growth.
4.2BSD には
.BR sigstack ()
システムコールがあった。
この関数は少し異なった構造体を使っており、
呼び出した側がスタックの積まれる方向を知っていなければならないという
大きな欠点があった。
.\"O .SH EXAMPLE
.SH 例
.\"O The following code segment demonstrates the use of
.\"O .BR sigaltstack ():
以下のコードで
.BR sigaltstack ()
の使用法の一部を示す:

.in +4n
.nf
stack_t ss;

ss.ss_sp = malloc(SIGSTKSZ);
if (ss.ss_sp == NULL)
.\"O     /* Handle error */;
    /* ハンドルエラー */;
ss.ss_size = SIGSTKSZ;
ss.ss_flags = 0;
if (sigaltstack(&ss, NULL) == \-1)
.\"O     /* Handle error */;
    /* ハンドルエラー */;
.fi
.in
.\"O .SH "SEE ALSO"
.SH 関連項目
.BR execve (2),
.BR setrlimit (2),
.BR sigaction (2),
.BR siglongjmp (3),
.BR sigsetjmp (3),
.BR signal (7)