日本語 man コマンド類 (ja-man-1.1j_5) と日本語 man ドキュメント (ja-man-doc-5.4 (5.4-RELEASE 用) など) をインストールすると、以下のような man コマンド閲覧、キーワード検索が コンソールからできるようになります。
4.11-RELEASE-K, 5.4-RELEASE-K, 5.5-RELEASE-K, 6.0-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K, 12.1-RELEASE-K は、 プライベート版 (小金丸が編集してまとめたもの) ですが、 より多くの翻訳したファイルが含まれています。 (5.4-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K から 12.4-RELEASE-K, 13.0-RELEASE-K から 13.3-RELEASE-K, 14.0-RELEASE-K から 14.1-RELEASE-K は、全翻訳済み)
13.3-STABLE-K, 15.0-CURRENT-K は現在、作成中で日々更新されています。
Table of Contents
POSIX_SPAWN(3) FreeBSD ライブラリ関数マニュアル POSIX_SPAWN(3)
名称
posix_spawn, posix_spawnp -- プロセスをスポン (spawn) する
ライブラリ
標準 C ライブラリ (libc, -lc)
書式
#include <spawn.h>
int
posix_spawn(pid_t *restrict pid, const char *restrict path,
const posix_spawn_file_actions_t *file_actions,
const posix_spawnattr_t *restrict attrp, char *const argv[restrict],
char *const envp[restrict]);
int
posix_spawnp(pid_t *restrict pid, const char *restrict file,
const posix_spawn_file_actions_t *file_actions,
const posix_spawnattr_t *restrict attrp, char *const argv[restrict],
char *const envp[restrict]);
解説
posix_spawn() と posix_spawnp() 関数は、指定されたプロセスイメージから新
しいプロセス (子プロセス) を作成します。新しいプロセスイメージは、新しい
プロセスイメージファイルと呼ばれる通常の実行形式ファイルから構成されま
す。
C プログラムが、この呼び出しの結果として実行されるとき、それは、次の C 言
語の関数呼び出しとして入ります:
int main(int argc, char *argv[]);
ここで、argc は、引数カウントであり、argv は、引数自体への文字ポインタの
配列です。さらに、次の変数:
extern char **environ;
は、環境文字列への文字ポインタの配列を指します。
引数 argv は、ヌル文字で終了する文字列への文字ポインタの配列です。この配
列の最後のメンバは、null ポインタであり、argc でカウントされせん。これら
の文字列は、新しいプロセスイメージに利用可能な引数のリストを構成します。
argv[0] の値は、posix_spawn() または posix_spawnp() 関数によって開始され
れるプロセスイメージに関連しているファイル名を指すべきです。
引数 envp は、ヌル文字で終了する文字列への文字ポインタの配列です。これら
の文字列は、新しいプロセスイメージのための環境を構成します。環境配列は、
NULL ポインタによって終了されます。
posix_spawn() への path 引数は、実行する新しいプロセスイメージファイルを
識別するパス名です。
posix_spawnp() への file パラメータは、新しいプロセスイメージファイルを識
別するパス名を構成するために使用されます。ファイルパラメータがスラッシュ
文字を含んでいるなら、ファイルパラメータは、新しいプロセスイメージファイ
ルにパス名として使用されます。そうでなければ、このファイルのためのパス接
頭辞は、環境変数 ``PATH'' として渡されたディレクトリの検索によって取得さ
れます。この変数が指定されないなら、デフォルトのパスは、
``/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin'' に設定さ
れた <paths.h> の _PATH_DEFPATH 定義にしたがって設定されます。
file_actions が NULL ポインタであるなら、呼び出しプロセスでオープンされて
いるファイル記述子は、close-on-exec フラグ FD_CLOEXEC が設定されている
(fcntl() 参照) いるものを除いて、子プロセスでオープンされたままで残りま
す。オープンしているままのそれらのファイル記述子について、対応するオープ
ンファイル記述子のすべての属性は、ファイルロック (fcntl() 参照) を含ん
で、変更しないままとなります。
file_actions が NULL でないなら、子プロセスでオープンされたファイル記述子
は、file_actions によって指されるスポンファイルアクションオブジェクトに
よって変更され、スポンファイルアクションが処理された後に、それぞれの残っ
ているオープンされたファイル記述子の FD_CLOEXEC フラグとして、呼び出しプ
ロセスでオープンされたものです。スポンファイルアクションを処理する効果的
な順序は、次の通りです:
1. 最初に、子プロセスのためのオープンファイル記述子のセットは、呼び出し
プロセスのためにオープンされたものと同じセットです。対応するオープン
されたファイル記述子のすべての属性は、ファイルロック (fcntl() 参照)
を含んで、変更しないままとなります。
2. 子プロセスのためのシグナルマスク、シグナルのデフォルトアクション、実
効ユーザ、とグループ ID は、attrp によって参照される属性オブジェクト
で指定されるように変更されます。
3. スポンファイルアクションオブジェクトによって指定されたファイルアク
ションは、それらがスポンファイルアクションオブジェクトに追加された順
序で実行されます。
4. FD_CLOEXEC フラグ設定 (fcntl() 参照) がある任意のファイル記述子は、
クローズされます。
posix_spawnattr_t スポン属性オブジェクトタイプは、<spawn.h> に定義されて
います。それは、下記に定義された属性を含んでいます。
POSIX_SPAWN_SETPGROUP フラグが attrp によって参照されたオブジェクトの
spawn-flags 属性で設定され、同じオブジェクトの spawn-pgroup 属性が 0 でな
いなら、子供のプロセスグループは、attrp によって参照されたオブジェクトの
spawn-pgroup 属性で指定されるものです。
特別なものとして、POSIX_SPAWN_SETPGROUP フラグが attrp によって参照された
オブジェクトの spawn-flags 属性で設定され、同じオブジェクトの spawn
pgroup 属性が 0 に設定されているなら、子供のプロセスは、そのプロセス ID
と等しいプロセスグループ ID で新しいプロセスグループとなります。
POSIX_SPAWN_SETPGROUP フラグが attrp によって参照されたオブジェクトの
spawn-flags 属性で設定されていないなら、新しい子プロセスは、親のプロセス
グループを継承します。
POSIX_SPAWN_SETSCHEDPARAM フラグが attrp によって参照されたオブジェクトの
spawn-flags 属性で設定されていますが、POSIX_SPAWN_SETSCHEDULER が設定され
ていないなら、最初に、新しいプロセスイメージには、attrp によって参照され
たオブジェクトの spawn-schedparam 属性で指定されたスケジューリングパラ
メータで呼び出しプロセスのスケジューリングポリシがあります。
POSIX_SPAWN_SETSCHEDULER フラグが (POSIX_SPAWN_SETSCHEDPARAM フラグの設定
にかかわらず) attrp によって参照されたオブジェクトの spawn-flags 属性で設
定されているなら、最初に、新しいプロセスイメージには、attrp によって参照
されたオブジェクトの spawn-schedpolicy 属性で指定されたスケジューリングポ
リシと同じオブジェクトの spawn-schedparam 属性で指定されたスケジューリン
グパラメータがあります。
attrp によって参照されたオブジェクトの spawn-flags 属性の
POSIX_SPAWN_RESETIDS フラグは、子プロセスの実効ユーザ ID を支配します。こ
のフラグが設定されていないなら、子プロセスは、親プロセスの実効ユーザ ID
を継承します。このフラグが設定されているなら、子プロセスの実効ユーザ ID
は、親の実ユーザ ID にリセットされます。どちらの場合にも、新しいプロセス
イメージファイルのセットユーザ ID (set-user-ID) が設定されているなら、新
しいプロセスイメージが実行を始める前に、子プロセスの実効ユーザ ID は、そ
のファイルの所有者の ID になります。
また、attrp によって参照されたオブジェクトの spawn-flags 属性の
POSIX_SPAWN_RESETIDS フラグは、子プロセスの実効グループ ID を支配します。
このフラグが設定されていないなら、子プロセスは、親プロセスの実効グループ
ID を継承します。このフラグが設定されているなら、子プロセスの実効グループ
ID は、親の実グループ ID にリセットされます。どちらの場合にも、新しいプロ
セスイメージファイルのセットグループ ID (set-group-ID) モードビットが設定
されているなら、新しいプロセスイメージが実行を始める前に、子プロセスの実
効グループ ID は、そのファイルのグループ ID になります。
POSIX_SPAWN_SETSIGMASK フラグが attrp によって参照されたオブジェクトの
spawn-flags 属性で設定されているなら、最初に、子プロセスには、attrp に
よって参照されたオブジェクトの spawn-sigmask 属性で指定されたシグナルマス
クがあります。
POSIX_SPAWN_SETSIGDEF フラグが attrp によって参照されるオブジェクトの
spawn-flags 属性で設定されるなら、同じオブジェクトの spawn-sigdefault 属
性で指定されたシグナルは、子プロセスのそれらのデフォルトアクションに設定
されます。親プロセスのデフォルトアクションへのシグナルセットは、子プロセ
スのデフォルトアクションに設定されます。
呼び出しプロセスによって獲得されるシグナルセットは、子プロセスのデフォル
トアクションに設定されます。
呼び出しプロセスイメージによって無視されるシグナルセットは、そうでなけれ
ば、attrp によって参照されたオブジェクトの spawn-flags 属性で設定されてい
る POSIX_SPAWN_SETSIGDEF フラグと、attrp によって参照されるオブジェクトの
spawn-sigdefault 属性で示されているシグナルによって指定さないなら、子プロ
セスによって無視されるように設定されます。
attrp ポインタの値が NULL であるなら、デフォルト値が、使用されます。
上記で指定されるような attrp によって参照されたオブジェクトに設定された属
性によって、または file_actions で指定されたファイル記述子操作によって、
影響されたもの以外のすべてのプロセス属性は、まるで vfork() が、子プロセス
を作成するために呼び出され、次に、execve() が、新しいプロセスイメージを実
行するための子プロセスによって呼び出されるかのように新しいプロセスイメー
ジに現れます。
したがって、vfork() を使用する実装では、fork ハンドラは、posix_spawn() ま
たは posix_spawnp() が呼び出されるとき、実行されません。
戻り値
成功して終了すれば、posix_spawn() と posix_spawnp() は、NULL でない pid
引数によって指された変数に、親プロセスへの子プロセスのプロセス ID を返
し、関数の返り値として 0 を返します。そうでなければ、子プロセスは、作成さ
れず、値は、pid によって指された変数に格納されません、そして、エラー番号
は、エラーを示すために関数の返り値として返されます。pid 引数が NULL ポイ
ンタであるなら、子供のプロセス ID は、呼び出し側に返されません。
エラー
1. posix_spawn() と posix_spawnp() は、vfork() を引き起こす理由のどれか
で失敗するか、または、exec の 1 つで失敗し、エラー値は、それぞれ、
vfork() と exec によって記述されるように返されます (または、呼び出し
プロセスが成功して戻った後に、エラーが発生するなら、子プロセスは、終
了ステータス 127 で終了します)。
2. POSIX_SPAWN_SETPGROUP が、attrp によって参照されたオブジェクトの
spawn-flags 属性で設定され、posix_spawn() または posix_spawnp() が、
子供のプロセスグループを変更しているる間に失敗するなら、エラー値は、
setpgid() によって説明されるように返されます、(または、呼び出しプロ
セスが成功して返った後にエラーが発生するなら、子プロセスは、終了ス
テータス 127 で終了します)。
3. POSIX_SPAWN_SETSCHEDPARAM が設定され、POSIX_SPAWN_SETSCHEDULER が、
attrp によって参照されたオブジェクトの spawn-flags 属性で設定されて
いないなら、次に、posix_spawn() または posix_spawnp() が、
sched_setparam() が失敗する何らかの理由で失敗するなら、エラー値は、
sched_setparam() によって説明されるように返されます、(または、呼び出
しプロセスが成功して返った後にエラーが発生するなら、子プロセスは、終
了ステータス 127 で終了します)。
4. POSIX_SPAWN_SETSCHEDULER が attrp によって参照されたオブジェクトの
spawn-flags 属性で設定され、posix_spawn() または posix_spawnp() が、
sched_setscheduler() が失敗する何らかの理由で失敗するなら、エラー値
は、sched_setscheduler() によって説明されるように返されます、(また
は、呼び出しプロセスが成功して返った後にエラーが発生するなら、子プロ
セスは、終了ステータス 127 で終了します)。
5. file_actions 引数が NULL でなく、実行される任意の dup2 または open
アクションを指定して、posix_spawn() または posix_spawnp() が dup2()
または open() が失敗する何らかの理由で失敗するなら、エラー値は、それ
ぞれ dup2() と open() によって説明されるように返され (るか、または、
エラーが呼び出しプロセスが成功して返った後に発生するなら、子プロセス
は、終了ステータス 127 で終了し) ます。オープンされたファイルアク
ションは、それ自体によって、open() によって説明されたものに加えて
dup2() によって説明されたエラーのいずれかの結果となります。この実装
は、オープンされていない記述子をクローズすることを含んで、close() か
らのどんなエラーも無視します。無視は、closefrom() アクションの一部と
して実行される個別のファイル記述子 close() からのあらゆるエラーに展
開されます。
関連項目
close(2), dup2(2), execve(2), fcntl(2), open(2), sched_setparam(2),
sched_setscheduler(2), setpgid(2), vfork(2),
posix_spawn_file_actions_addclose(3),
posix_spawn_file_actions_addclosefrom_np(3),
posix_spawn_file_actions_adddup2(3), posix_spawn_file_actions_addopen(3),
posix_spawn_file_actions_addchdir_np(3),
posix_spawn_file_actions_addfchdir_np(3),
posix_spawn_file_actions_destroy(3), posix_spawn_file_actions_init(3),
posix_spawnattr_destroy(3), posix_spawnattr_getflags(3),
posix_spawnattr_getpgroup(3), posix_spawnattr_getschedparam(3),
posix_spawnattr_getschedpolicy(3), posix_spawnattr_getsigdefault(3),
posix_spawnattr_getsigmask(3), posix_spawnattr_init(3),
posix_spawnattr_setflags(3), posix_spawnattr_setpgroup(3),
posix_spawnattr_setschedparam(3), posix_spawnattr_setschedpolicy(3),
posix_spawnattr_setsigdefault(3), posix_spawnattr_setsigmask(3)
規格
posix_spawn() と posix_spawnp() 関数は、close() からのすべてのエラーを無
視することを除いて、IEEE Std 1003.1-2001 (``POSIX.1'') に適合しています。
規格の将来の更新は、(posix_spawn_file_actions_addclose() を通して) クロー
ズされるファイル記述子がオープンされないので、これらの関数が失敗しないこ
とが期待されます。
歴史
posix_spawn() と posix_spawnp() 関数は、FreeBSD 8.0 ではじめて登場しまし
た。
作者
Ed Schouten <ed@FreeBSD.org>
FreeBSD 13.2 November 28, 2021 FreeBSD 13.2