Merge branch 'work-coreutils'

[linuxjm/jm.git] / manual / LDP_man-pages / release / man2 / execve.2

.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
.\" and Copyright (c) 2006 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.
.\"
.\" Modified by Michael Haardt <michael@moria.de>
.\" Modified 1993-07-21 by Rik Faith <faith@cs.unc.edu>
.\" Modified 1994-08-21 by Michael Chastain <mec@shell.portal.com>:
.\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com>
.\" Modified 1999-11-12 by Urs Thuermann <urs@isnogud.escape.de>
.\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
.\" 2006-09-04 Michael Kerrisk <mtk.manpages@gmail.com>
.\"     Added list of process attributes that are not preserved on exec().
.\" 2007-09-14 Ollie Wild <aaw@google.com>, mtk
.\"     Add text describing limits on command-line arguments + environment
.\"
.\" Japanese Version Copyright (c) 1996 TABATA Tomohira
.\"         all rights reserved.
.\" Translated 1996-07-04, TABATA Tomohira <loba@k2.t.u-tokyo.ac.jp>
.\" Updated 1997-12-14, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
.\" Updated 2001-08-17, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
.\" Updated 2005-02-05, Yuichi SATO <ysato444@yahoo.co.jp>
.\" Updated 2005-09-06, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
.\" Updated 2005-11-19, Akihiro MOTOKI
.\" Updated 2006-08-13, Akihiro MOTOKI, LDP v2.39
.\" Updated 2007-01-09, Akihiro MOTOKI, LDP v2.43
.\" Updated 2007-06-03, Akihiro MOTOKI, LDP v2.51
.\" Updated 2007-10-12, Akihiro MOTOKI, LDP v2.66
.\" Updated 2008-04-04, Akihiro MOTOKI, LDP v2.79
.\" Updated 2008-11-05, Akihiro MOTOKI, LDP v3.12
.\"
.TH EXECVE 2 2010-01-06 "Linux" "Linux Programmer's Manual"
.SH 名前
execve \- プログラムを実行する
.SH 書式
.B #include <unistd.h>
.sp
.BI "int execve(const char *" filename ", char *const " argv "[], "
.br
.BI "           char *const " envp []);
.SH 説明
.BR execve ()
は、\fIfilename\fP によって指定されたプログラムを実行する。
\fIfilename\fP は、バイナリ実行形式か、
以下の形式の行で始まるスクリプトでなければならない。

.in +4n
.nf
\fB#!\fP \fIinterpreter \fP[optional-arg]
.fi
.in

後者の詳細は、後ろの「インタプリタ・スクリプト」の節を参照のこと。

\fIargv\fP は新しいプログラムに渡される引き数文字列の配列である。
\fIenvp\fP は文字列の配列であり、伝統的に \fBkey=value\fP の形式を
しており、新しいプログラムの環境変数として渡される。
\fIargv\fP と \fIenvp\fP はいずれもの NULL ポインタで終わっている
必要がある。引き数配列と環境変数は、呼び出されたプログラムの main 関数を
以下のように定義することによってアクセス可能になる。

.in +4n
.nf
int main(int argc, char *argv[], char *envp[])
.fi
.in

成功した場合、
.BR execve ()
は返らない。
そして、呼び出し元のプロセスの text, data, bss, スタックは、
読み込まれたプログラムによって上書きされる。

元のプログラムが ptrace されている場合、
.BR execve ()
が成功した後に
そのプログラムに \fBSIGTRAP\fP が送られる。

.I filename
で指定されたプログラムファイルに set-user-ID ビットが設定されており、
ファイルが存在するファイルシステムが
.I nosuid
.RB ( mount (2)
の
.B MS_NOSUID
フラグ) でマウントされておらず、
呼び出したプロセスが ptrace されていない場合、
呼び出したプロセスの実効 (effective) ユーザ ID は
プログラムファイルの所有者 (owner) に変更される。
同様に、プログラムファイルに set-group-ID ビットが設定されていた場合、
呼び出したプロセスの有効グループ ID は
プログラムファイルのグループに変更される。

プロセスの実効ユーザ ID は保存 (saved) set-user-ID にコピーされる。
同様に、実効グループ ID は保存 set-group-ID にコピーされる。
このコピーは、set-user-ID / set-group-ID 許可ビットにより発生する
実効 ID の変更後に行われる。

実行ファイルが動的リンクされた a.out 実行形式で、共有ライブラリの
スタブを含むものだった場合、実行の開始時に Linux の
ダイナミック・リンカ
.BR ld.so (8)
が呼び出され、必要な共有ライブラリをメモリに読み込んでリンクを行う。

実行ファイルがダイナミック・リンクされた ELF 実行形式だった場合、
PT_INTERP セグメントに指定されたインタプリタが必要な
共有ライブラリ (shared library) を読み込むのに使用される。
通常、インタプリタとしては、
Linux libc 5 をリンクしたバイナリの場合には
\fI/lib/ld-linux.so.1\fP が、
glibc 2 をリンクしたバイナリの場合には
\fI/lib/ld-linux.so.2\fP が使用される。

以下に示す以外のすべてのプロセス属性は
.BR execve ()
の前後で保持される。
.IP *
捕捉されたシグナルの処理方法 (disposition) は
デフォルト動作にリセットされる
.RB ( signal (7))。
.IP *
代替シグナルスタックはどれも保持されない
.RB ( sigaltstack (2))。
.IP *
メモリマッピングは保持されない
.RB ( mmap (2))。
.IP *
付加された (attached) System V 共有メモリセグメントは分離される
.RB ( shmat (2))。
.IP *
POSIX 共有メモリ領域はマッピングを解除される
.RB ( shm_open (3))。
.IP *
オープンされた POSIX メッセージキューディスクリプタはクローズされる
.RB ( mq_overview (7))。
.IP *
オープンされた POSIX 名前付きセマフォはいずれもクローズされる
.RB ( sem_overview (7))。
.IP *
POSIX タイマは保持されない
.RB ( timer_create (2))。
.IP *
オープンされたディレクトリストリームはいずれもクローズされる
.RB ( opendir (3))。
.IP *
メモリロックは保持されない
.RB ( mlock (2),
.BR mlockall (2))。
.IP *
終了 (exit) ハンドラは保持されない
.RB ( atexit (3),
.BR on_exit (3))。
.IP *
浮動小数点関連の環境はデフォルトにリセットされる
.RB ( fenv (3)
参照)。
.PP
上記のリストのプロセス属性はいずれも POSIX.1-2001 で規定されている。
以下に示す Linux 固有のプロセス属性も
.BR execve ()
の前後で保持されない。
.IP * 3
set-user-ID か set-group-ID されたプログラムが実行されている場合、
.BR prctl (2)
の
.B PR_SET_DUMPABLE
フラグはクリアされる。それ以外の場合、このフラグはセットされる。
.IP *
.BR prctl (2)
の
.B PR_SET_KEEPCAPS
フラグはクリアされる。
.IP *
プロセス名は新しい実行ファイルの名前にリセットされる。
プロセス名は
.BR prctl (2)
の
.B PR_SET_NAME
で設定でき、
.I "ps\ \-o comm"
で表示できる。
.IP *
終了シグナル (termination signal) は
.B SIGCHLD
にリセットされる
.RB ( clone (2)
参照)。
.PP
以下の点についても注意すること:
.IP * 3
呼び出し元スレッド以外の全てのスレッドは
.BR execve ()
中に破棄される。
mutex、条件変数、その他の pthread オブジェクトは保持されない。
.IP *
\fIsetlocale(LC_ALL, "C")\fP 相当の処理がプログラム開始時に実行される。
.IP *
POSIX.1-2001 は、動作が無視かデフォルトに設定されている全てのシグナル
の処理方法は変更せずそのままにする、と規定している。
但し、POSIX.1-2001 には一つ例外があり、
.B SIGCHLD
が無視になっている場合、
その処理方法を変更せずにそのままにするか、デフォルト動作にリセットするかは
実装依存となっている。
Linux では前者 (変更しない) となっている。
.IP *
完了していない非同期 I/O 操作はキャンセルされる
.RB ( aio_read (3),
.BR aio_write (3))。
.IP *
.BR execve (2)
時のケーパビリティの扱いについては、
.BR capabilities (7)
を参照。
.IP *
デフォルトでは、ファイルディスクリプタは
.BR execve ()
を行った後でもオープンされたままである。
close-on-exec の印が付いているファイルディスクリプタはクローズされる。
.BR fcntl (2)
の
.B FD_CLOEXEC
の説明を参照。
(ファイルディスクリプタがクローズされると、このプロセスが
ファイルディスクリプタに対応するファイルに対して獲得していた
レコードのロックが全て解放されることになる。)
POSIX.1-2001 では、
ファイルディスクリプタ 0, 1, 2 が
.BR execve ()
成功後にどこかでクローズされ、かつ
実行されるファイルに set-user_ID か set-group_ID の許可ビットが
セットされていてプロセスが特権を獲得した場合、
システムは何らかのファイルをオープンする際に
これらの番号のディスクリプタのどれかを使うことがある、
とされている。
原則として、移植性が必要なプログラムでは、
特権の有無に関わらず、
.BR execve ()
の前後でこれら 3つのファイルディスクリプタがクローズされたままで
あることを前提にすることはできない。
.\" On Linux it appears that these file descriptors are
.\" always open after an execve(), and it looks like
.\" Solaris 8 and FreeBSD 6.1 are the same. -- mtk, 30 Apr 2007
.SS インタプリタ・スクリプト
インタプリタ・スクリプトとは、実行許可が有効になっていて、
最初の行が以下の形になっているテキストファイルのことである。

.in +4n
.nf
\fB#!\fP \fIinterpreter \fP[optional-arg]
.fi
.in

.I interpreter
は有効な実行ファイルのパス名でなければならず、
それ自身がスクリプトであってはならない。
.BR execve ()
の
.I filename
引き数がインタプリタスクリプトを指定している場合、
.I interpreter
は以下の引き数で起動される。

.in +4n
.nf
\fIinterpreter\fP [optional-arg] \fIfilename\fP arg...
.fi
.in

.I arg...
は
.BR execve ()
の
.I argv
引き数が指すワード列である。

移植性を持たすには、
.I optional-arg
は空か 1ワードだけにすべきである
(つまり、ホワイト・スペースを含めるべきではない)。
下記の「注意」の節を参照。
.SS "引き数と環境変数の合計サイズの上限"
ほとんどの UNIX の実装は、新しいプログラムに渡すことができる
コマンドライン引き数
.RI ( argv )
と環境変数
.RI ( envp )
の文字列群の合計サイズに何らかの上限を設けている。
POSIX.1 は、
.B ARG_MAX
定数を使ってこの上限を決める実装を認めている
.RB ( ARG_MAX
は
.I <limits.h>
で定義されるか、実行時に
.I "sysconf(_SC_ARG_MAX)"
の呼び出しで入手できるかのいずれかである)。

カーネル 2.6.23 より前の Linux では、環境変数と引き数の文字列群を
格納するのに使用されるメモリは 32 ページに制限されていた
(32 ページというのはカーネル定数
.B MAX_ARG_PAGES
で定義される)。したがって、
ページサイズが 4 kB のアーキテクチャでは、
最大サイズは 128 kB ということになる。

カーネル 2.6.23 以降では、ほとんどのアーキテクチャにおいて、
.BR execve ()
が呼び出された時点で適用されているリソースのソフト上限
.B RLIMIT_STACK
に基づいたサイズ上限が使われる
(メモリ管理ユニット (MMU) を持たないアーキテクチャは上記の変更の
例外であり、これらのアーキテクチャではカーネル 2.6.23 より前と
同じ上限がそのまま使用される)。
.\" For some background on the changes to ARG_MAX in kernels 2.6.23 and
.\" 2.6.25, see:
.\"     http://sourceware.org/bugzilla/show_bug.cgi?id=5786
.\"     http://bugzilla.kernel.org/show_bug.cgi?id=10095
.\"     http://thread.gmane.org/gmane.linux.kernel/646709/focus=648101,
.\"     checked into 2.6.25 as commit a64e715fc74b1a7dcc5944f848acc38b2c4d4ee2.
これらのアーキテクチャでは、合計サイズは許可されたスタックサイズの
1/4 に制限されている
(1/4 の上限を設けているのは、新しいプログラムが必ずある程度の
スタック空間を持てることを保証するためである)。
.\" Ollie: That doesn't include the lists of pointers, though,
.\" so the actual usage is a bit higher (1 pointer per argument).
Linux 2.6.25 以降では、カーネルはこのサイズ上限に 32 ページの下限を
設けている。これにより、
.B RLIMIT_STACK
が非常に小さく設定された場合でも、アプリケーションが少なくとも
Linux 2.6.23 以前で提供されていたのと同じ大きさの引き数と環境変数の空間
と同じだけは確保できることが保証されている
(この最低限の保証は Linux 2.6.23 と 2.6.24 では提供されていない)。
また、各文字列の上限は 32 ページ (カーネル定数
.BR MAX_ARG_STRLEN )
で、文字列数の最大値は 0x7FFFFFFF である。
.SH 返り値
成功すると
.BR execve ()
は返らない。エラーの場合は \-1 を返し、
.I errno
を適切に設定する。
.SH エラー
.TP
.B E2BIG
環境変数
.RI ( envp )
と引き数リスト
.RI ( argv )
の合計バイト数が大き過ぎる。
.TP
.B EACCES
.I filename
やスクリプトインタプリタ名の構成要素に検索許可 (search permission)
が与えられていない
.RB ( path_resolution (7)
も参照すること)。
.TP
.B EACCES
ファイルもしくはスクリプトのインタプリタが通常ファイル (regular file)
でない。
.TP
.B EACCES
ファイルやスクリプトや ELF インタプリタに
実行許可 (execute permission) が与えられていない。
.TP
.B EACCES
ファイル・システムが
.I noexec
でマウントされている。
.TP
.B EFAULT
.I filename
がアクセス可能なアドレス空間の外を指している。
.TP
.B EINVAL
ELF 実行形式で複数の PT_INTERP セグメントが存在する。
(すなわち複数のインタプリタを指定した。)
.TP
.B EIO
I/O エラーが発生した。
.TP
.B EISDIR
ELF インタプリタがディレクトリだった。
.TP
.B ELIBBAD
ELF インタプリタが理解できるフォーマットでなかった。
.TP
.B ELOOP
.I filename
やスクリプトや ELF のインタプリタを解決する際に遭遇した
シンボリック・リンクが多過ぎる。
.TP
.B EMFILE
そのプロセスがオープンできるファイル数の上限まで既にオープンしている。
.TP
.B ENAMETOOLONG
.I filename
が長過ぎる。
.TP
.B ENFILE
そのシステムでオープンできるファイル数の制限に達した。
.TP
.B ENOENT
ファイル
.I filename
かスクリプトや ELF のインタプリタが存在しない。
.TP
.B ENOEXEC
実行ファイルが理解できない形式であるか、違うアーキテクチャのものか、
その他のフォーマット・エラーにより実行ができなかった。
.TP
.B ENOMEM
カーネルに十分なメモリがない。
.TP
.B ENOTDIR
.I filename
やスクリプトや ELF のインタプリタの構成要素がディレクトリでない。
.TP
.B EPERM
ファイル・システムが
.I nosuid
でマウントされ、ユーザがスーパーユーザでなく、
ファイルに set-user-ID あるいは set-group-ID ビットが設定されている。
.TP
.B EPERM
プロセスがトレースされ、ユーザがスーパーユーザでなく、
ファイルに set-user-ID あるいは set-group-ID ビットが設定されている。
.TP
.B ETXTBSY
実行ファイルを書き込み用にオープンしているプロセスがある。
.SH 準拠
SVr4, 4.3BSD, POSIX.1-2001.
POSIX.1-2001 には #! 動作についての記述はないが、
他は互換性がある。
.\" SVr4 には他に EAGAIN, EINTR, ELIBACC, ENOLINK, EMULTIHOP
.\" についての記述がある。
.\" POSIX には ETXTBSY, EPERM, EFAULT, ELOOP, EIO, ENFILE, EMFILE,
.\" EINVAL, EISDIR, ELIBBAD エラー状態についての記述はない。
.SH 注意
set-user-id プロセスと set-group-ID プロセスは
.BR ptrace (2)
できない。

Linux はスクリプトの set-user-ID と set-group-ID ビットを無視する。

ファイルシステムを
.I nosuid
でマウントした場合に set-user-ID/set-group-ID の実行ファイルを
どの様に扱うかは、Linux カーネルのバージョンによって異なる:
あるバージョンでは、すでに必要な権限を持っている場合を除いて、
その実行を拒否する (そして
.B EPERM
を返す)。別のあるバージョンでは
set-user-ID/set-group-ID ビットのみを無視し
.BR exec ()
は成功する。

#! 実行形式のシェル・スクリプトの 1行目に許されている文字数は、
最大 127 文字である。

インタプリタ・スクリプトの
.I optional-arg
引き数の解釈方法は実装により異なる。
Linux では、インタプリタ名
.I interpreter
に続く文字列全体がインタプリタに 1個の引き数として渡される。
しかし、動作が異なるシステムもある。
あるシステムでは、
.\" 例えば、Solaris 8
.I optional-arg
のうち最初のホワイト・スペースまでが
引き数として渡される。
また、別のシステムでは
.\" 例えば、6.0 より前の FreeBSD (FreeBSD 6.0 以降は違う)
インタプリタ・スクリプトは複数の引き数を持つことができ、
.I optional-arg
内のホワイト・スペースが引き数の区切りとなる。

Linux では、
.I argv
に NULL を指定することができる。これは、この引き数に NULL ポインタ
1個だけを含むリストへのポインタを指定したのと同じ効果を持つ。
.BR 「この間違った機能を利用しないこと」 。
これは非標準で、移植性もない。
他のほとんどの UNIX システムでは、これを行うとエラー
.RB ( EFAULT )
になる。
.\" e.g., EFAULT on Solaris 8 and FreeBSD 6.1; but
.\" HP-UX 11 is like Linux -- mtk, Apr 2007
.\" Bug filed 30 Apr 2007: http://bugzilla.kernel.org/show_bug.cgi?id=8408
.\" Bug rejected (because fix would constitute an ABI change).
.\"

POSIX.1-2001 は、
.BR sysconf (3)
が返す値はプロセスの生存中は変化しないべきだとしている。
しかしながら、Linux 2.6.23 以降では、リソース上限
.B RLIMIT_STACK
が変化した場合、
コマンドライン引き数と環境変数を保持するための空間に対する上限が
変化したことを反映して、
.B _SC_ARG_MAX
が返す値も変化する。
.\"
.\" .SH バグ
.\" Linux 版の中には、ELF インタプリタにおける
.\" 権限のチェックに失敗するものがある。
.\" これはセキュリティホールである。
.\" なぜなら、ユーザに任意のファイルをオープンを許可したり、
.\" 読み込みのためにテープデバイスを巻き戻しを許可したりする。
.\" Linux 版の中には
.\" .BR execve ()
.\" に他のセキュリティホールが
.\" 存在するものもあり、巧妙に細工された ELF バイナリによって
.\" サービス拒否 (denial of service) に利用されてしまう。
.\" 2.0.34 また 2.2.15 には、知られている問題はない。
.SS 歴史
UNIX V6 では
.BR exec ()
コールの引き数リストは 0 で終端され、
.I main
の引き数リストは \-1 で終端されていた。
そのため、
.I main
の引き数リストは、その後の
.BR exec ()
コールには直接使用できなかった。
UNIX V7 以降では、ともに NULL で終端される。
.SH 例
このプログラムは、以下の二つ目のプログラムから実行するためのものである。
コマンドラインを 1行に 1個ずつ表示するだけのプログラムである。

.in +4n
.nf
/* myecho.c */

#include <stdio.h>
#include <stdlib.h>

int
main(int argc, char *argv[])
{
    int j;

    for (j = 0; j < argc; j++)
        printf("argv[%d]: %s\\n", j, argv[j]);

    exit(EXIT_SUCCESS);
}
.fi
.in

以下のプログラムは、コマンドライン引き数で指定した名前のプログラムを
実行するのに使う。
.in +4n
.nf

/* execve.c */

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

int
main(int argc, char *argv[])
{
    char *newargv[] = { NULL, "hello", "world", NULL };
    char *newenviron[] = { NULL };

    if (argc != 2) {
        fprintf(stderr, "Usage: %s <file-to-exec>\\n", argv[0]);
        exit(EXIT_FAILURE);
    }

    newargv[0] = argv[1];

    execve(argv[1], newargv, newenviron);
    perror("execve");   /* execve() only returns on error */
    exit(EXIT_FAILURE);
}
.fi
.in

二つ目のプログラムを使って一つ目のプログラムを実行するには
以下のようにする。

.in +4n
.nf
.RB "$" " cc myecho.c \-o myecho"
.RB "$" " cc execve.c \-o execve"
.RB "$" " ./execve ./myecho"
argv[0]: ./myecho
argv[1]: hello
argv[2]: world
.fi
.in

さらに、これらのプログラムを使って、スクリプト・インタプリタの例を示す。
このために、「インタプリタ」として先ほど作成したプログラム
.I myecho
を使うスクリプトを作成する。

.in +4n
.nf
.RB "$" " cat > script.sh"
.B #! ./myecho script-arg
.B ^D
.RB "$" " chmod +x script.sh"
.fi
.in

作成しておいたプログラムを使ってスクリプトを実行する。

.in +4n
.nf
.RB "$" " ./execve ./script.sh"
argv[0]: ./myecho
argv[1]: script-arg
argv[2]: ./script.sh
argv[3]: hello
argv[4]: world
.fi
.in
.SH 関連項目
.BR chmod (2),
.BR fork (2),
.BR ptrace (2),
.BR execl (3),
.BR fexecve (3),
.BR getopt (3),
.BR credentials (7),
.BR environ (7),
.BR path_resolution (7),
.BR ld.so (8)