RC.SUBR(8)

名称
rc.subr - システムシェルスクリプトで使用する関数群

書式
. /etc/rc.subr

backup_file action file current backup
checkyesno var
check_pidfile pidfile procname [interpreter]
check_process procname [interpreter]
debug message
err exitval message
force_depend name
info message
load_rc_config command
mount_critical_filesystems type
rc_usage command ...
reverse_list item ...
run_rc_command argument
run_rc_script file argument
set_rcvar [base]
wait_for_pids [pid ...]
warn message

解説
rc.subr スクリプトは、 rc(8) のような様々なスクリプトから利用される、一般的に使用する シェルスクリプト関数や変数定義を含んでいます。 また ports が要求する /usr/local/etc/rc.d 内のスクリプトも、やがては本スクリプトを使用するように 書き換えられるでしょう。

rc.subr の関数群は、大部分が NetBSD から取り込まれたものであり、またそれらは二つのプロジェクト間で同期できるように 考えられています。 そのことを考慮した、役に立ついくつかの変数定義があります:

OSTYPE
    この値は "FreeBSD" か "NetBSD" のどちらかで、実行されている OS によります。

SYSCTL
    sysctl(8) コマンドのパス。

SYSCTL_N
    name=value ペアとしてではなく、 sysctl(8) 変数のみを表示する際の、パスと引数のリスト。

SYSCTL_W
    sysctl(8) 変数を設定または変更する際の、パスと引数。

rc.subr 関数群には、カレントシェルで /etc/rc.subr を読み込む事でアクセスできます。

以下のシェル関数が利用可能です:

backup_file action file current backup
    file のバックアップコピーを current として作成します。 rc.conf(5) 変数の backup_uses_rcs が “YES” である場合、以前のバージョンの current は rcs(1) を使ってアーカイブします。 そうでなければ、以前のバージョンの current は backup として保存します。

    引数 action は次のうちのどれかです:

    add file はこのバックアップ機構によりすぐにバックアップされるか、もしくは再投入されます。 current が作成され、必要なら、 rcs(1) ファイルが同様に作成されます。

    update
        file は変更されており、バックアップを取る必要があります。 current が存在するなら、 backup にコピーされるか、もしくは rcs(1) にチェックされます (リポジトリファイルが古い場合)。 その後に、 file が current にコピーされます。

    remove
        file はこのバックアップ機構で管理される事はもうありません。 rcs(1) が使われている場合は、空のファイルがチェックインされて current は削除されます。 そうでなければ、 current は backup に移動します。

checkyesno var
    var の値が “YES”, “TRUE”, “ON”, ‘1’ ならば、 0 を返します。 var の値が “NO”, “FALSE”, “OFF”, ‘0’ ならば、 1 を返します。 これら以外の値ならば、 var が正しく設定されていないという警告を出します。 値は大文字 / 小文字を問いません。

check_pidfile pidfile procname [interpreter]
    pidfile の最初の行の最初の語を解析して PID とし、この PID を持つプロセスが 実行されていて、最初の引数が procname とマッチすることを確かめます。 成功すればマッチした PID を出力し、そうでなければ何もしません。 interpreter が与えられれば、 procname の最初の行を解析して、

        #! interpreter [...]

    という形式であることを確かめます。 そして interpreter とオプション引数に procname を追加したものを、検索するプロセス文字列として使用します。

check_process procname [interpreter]
    最初の引数が procname にマッチする、実行されている任意のプロセスの PID を出力します。 interpreter は check_pidfile と同様に扱われます。

debug message
    デバッグメッセージを stderr に表示し、 logger(1) を使用してシステムログに記録をして、呼び出し元に戻ります。 このエラーメッセージは、スクリプト名 ($0 より), “: DEBUG: ”, 及びこれに続く message で構成されます。 この関数はスクリプトのデバッグの手助けとして、開発者が使用することを 目的にしています。 これは rc.conf(5) 変数の rc_debug により、有効あるいは無効にすることができます。

err exitval message
    エラーメッセージを stderr に表示し、 logger(1) を使用してシステムログに記録をして、終了値 exitval で 終了します。 このエラーメッセージは、スクリプト名 ($0 より), “: ERROR: ”, 及びこれに続く message で構成されます。

force_depend name
    勧告メッセージを出力し、 name サービスを強制的に起動します。 引数 name は、通常 /etc/rc.d/name といったスクリプトのパスの basename(1) 要素です。 スクリプトが何らかの原因で失敗した場合、警告を出力して戻り値 1 を返します。 成功した場合は、戻り値 0 を返します。

info message
    情報メッセージを stdout に表示し、 logger(1) を使用してシステムログに記録をします。 このメッセージは、スクリプト名 ($0 より), “: INFO: ”, 及びこれに続く message で構成されます。 この情報出力の表示は rc.conf(5) 変数の rc_info により、有効あるいは無効にすることができます。

load_rc_config command
    command の設定ファイルを読み込みます。 最初に、 /etc/rc.conf がまだ読み込まれていなければ、読み込みます。 その後に、ファイル /etc/rc.conf.d/command が存在すれば、これを読み込みます。 後者は呼び出しスクリプト側で指定した run_rc_command 引数を上書きする変数定義を含めることもできます。 これは管理者が任意の rc.d(8) スクリプトを編集すること無く、その動作を上書きできる簡易な仕組みを提供します。

mount_critical_filesystems type
    rc.conf(5) 変数の critical_filesystems_type で定義された重要なファイルシステムの一覧のうち、この時点でマウントされて いないものがあれば、マウントします。

rc_usage command ...
    $0 の使用方法を、有効な引数の一覧として、 command をプレフィックスの “[fast|force|one]” と共に出力します。

reverse_list item ...
    item のリストを逆順で出力します。

run_rc_command argument
    各種のシェル変数の設定に基づいて、現在の rc.d(8) スクリプトの、 argument 処理を実行します。 run_rc_command はきわめて柔軟性があり、完全に機能する rc.d(8) スクリプトを小量のシェルコードで記述することができます。

    argument はサポートされているコマンドから検索され、それは以下のうちのどれかです:

    start
        サービスを起動します。 本コマンドは、 rc.conf(5) の指定によりサービスを起動するべきかをチェックします。 またサービスが既に実行中で、そのために起動を拒否するかどうかもチェックします。 標準の FreeBSD スクリプトにおいて、システムが直接マルチユーザモードで起動する場合は、 起動プロセスの高速化のために、後者のチェックは行われません。

    stop
        rc.conf(5) の指定によりサービスが起動していれば、サービスを停止します。 本コマンドはサービスが実行中かどうかをチェックし、そうでない場合、 その旨を表示します。

    restart
        stop の後に、 start を実行します。 デフォルトでは、 (もし実行中なら) プログラムのプロセス ID を表示します。

    rcvar
        サービスの起動を制御するのに使用する rc.conf(5) 変数を (もしあれば) 表示します。

    pidfile または procname が設定されていれば、以下もサポートされています:

    poll
        コマンドが終了するのを待ちます。

    status
        プロセスのステータスを表示します。

    他にサポートされているコマンドは、オプション変数の extra_commands に列挙されています。

    argument はそれ自身の動作を変更する、以下のプレフィックスをつけることができます:

    fast
        実行中のプロセスの有無をチェックしません。 rc_fast=YES をセットします。

    force
        rcvar が “YES” にセットされているかどうかをチェックしません。 rc_force=YES をセットします。 argument_precmd が非 0 を返しても無視します。 required_* テストのどれかが失敗しても無視します。 また終了ステータスとして常に 0 を返します。

    one rcvar が “YES” にセットされているかどうかをチェックしません。 しかし他の全ての前提チェックは行います。

    run_rc_command はその動作を制御するために、以下のシェル変数を使用します。 特に明記が無いものは、オプションです。

    name
        このスクリプトの名称。 これはオプションではありません。

    rcvar
        rcvar の値は checkyesno によりチェックされ、この処理を実行するかどうかを判定します。

    command
        コマンドのフルパス。 サポートされる各キーワードに対して argument_cmd が設定されている場合は、必要ありません。

    command_args
        オプション引数、及び / または command に対するシェルディレクティブ。

    command_interpreter
        command は

            #! command_interpreter [...]
        という形式で起動されるので、 ps(1) コマンドの出力は

            command_interpreter [...] command

        のようになります。 ですので、この文字列は実行中のコマンドの PID を検索するのに、 command の代わりに使用します。

    extra_commands
        特別にサポートするコマンド / キーワード / 引数。

    pidfile
        PID ファイルのパス。 実行中のコマンドの PID を特定するのに使用します。 pidfile が設定された場合、 PID を検索するのには

            check_pidfile $pidfile $procname

        を使用します。 そうでなければ、 command が設定されている場合、 PID を検索するのには

            check_process $procname

        を使用します。

    procname
        チェックする時のプロセス名。 デフォルトは command の値です。

    required_dirs
        デフォルトの start 処理を実行する前に、これに列挙されたディレクトリの 存在をチェックします。

    required_files
        デフォルトの start 処理を実行する前に、これに列挙されたファイルが 読み取り可能かをチェックします。

    required_vars
        デフォルトの start 処理を実行する前に、これに列挙された変数に対して checkyesno を適用します。

    ${name}_chdir
        ${name}_chroot が提供されない場合、 command を実行する前に cd するディレクトリ。

    ${name}_chroot
        command を実行する前に chroot(8) するディレクトリ。 /usr がマウントされた後にのみサポートされています。

    ${name}_flags
        command の呼び出し時に適用する引数。 これは通常 rc.conf(5) で設定され、 rc.d(8) スクリプトで設定されるものではありません。 これを上書きするのに、環境変数の ‘flags’ を使うことができます。

    ${name}_nice
        command を実行する際の nice(1) レベル。 /usr がマウントされた後にのみサポートされています。

    ${name}_user
        command を実行する際のユーザ。 ${name}_chroot が設定されている場合は chroot(8) を使用し、そうでなければ su(1) を使用します。 /usr がマウントされた後にのみサポートされています。

    ${name}_group
        chroot 後に command を実行する際のグループ。

    ${name}_groups
        コンマで区切られたリストで、 chroot 後に command を実行する際の補助グループ。

    argument_cmd
        argument のデフォルト処理を上書きするシェルコマンド。

    argument_precmd
        argument_cmd を実行する直前、もしくは argument のデフォルト処理の直前に実行するシェルコマンド。 もしこれが非 0 の終了コードを返した場合、メイン処理は行われません。 デフォルト処理が実行されるならば、このチェックは required_* チェックとプロセスの (非) 存在チェックの後に行われます。

    argument_postcmd
        実行された argument_cmd 、もしくは argument のデフォルト処理が終了コード 0 を返した時に実行されるシェルコマンド。

    sig_stop
        デフォルトの stop 処理において、プロセスを停止するのに送られるシグナル。 デフォルトは SIGTERM です。

    sig_reload
        デフォルトの reload 処理において、プロセスを再読み込みさせるのに送られるシグナル。 デフォルトは SIGHUP です。

    argument で与えられた処理に対して、 argument_cmd が定義されていなければ、デフォルト処理が run_rc_command によって与えられます:

    argument
        デフォルト処理

    start
        command が実行されておらず、 checkyesno rcvar が成功すれば、 command を起動します。

    stop
        check_pidfile または check_process (適切なほう) により command の PID を特定し、それらの PID に対して kill sig_stop を実行し、そしてそれらの PID に対して wait_for_pids を実行します。

    reload
        stop と似ていますが、違うのは代わりに sig_reload を使い、 wait_for_pids を実行しないことです。

    restart
        stop 処理を実行後に、 start 処理を実行します。

    status
        command の PID を表示するか、もしくはスクリプト固有のステータス情報を表示します。

    poll
        command が終了するのを待ちます。

    rcvar
        使用される rc.conf(5) 変数を (もしあれば) 表示します。 この処理は、対応する rc.conf(5) 変数が “NO” に設定されていても動作します。

    以下の変数は、 run_rc_command が完了した後だけでなく、 (argument_cmd のような) 処理でも参照できます:

    rc_arg
        fast 及び force 処理が済んだ後の、 run_rc_command に与えられた引数。

    rc_flags
        デフォルトのコマンド実行時のフラグ。 環境変数の ‘flags’ で上書きされない限り、デフォルトは ${name}_flags です。 この変数は argument_precmd 処理で変更することができます。

    rc_pid
        command の PID (もしあるならば)。

    rc_fast
        “fast” プレフィックスが使われた場合、空ではありません。

    rc_force
        “force” プレフィックスが使われた場合、空ではありません。

run_rc_script file argument
    スクリプト file を引数 argument で実行し、スクリプトからの戻り値を処理します。

    file が実行される前に、多くのシェル変数が消去されます:

    name, command, command_args, command_interpreter, extra_commands, pidfile, rcvar, required_dirs, required_files, required_vars, argument_cmd, argument_precmd. argument_postcmd.

    file 起動時の動作は、以下のチェックに依るものになります:

    1.  file の名前が .sh で終わっていれば、カレントシェルに読み込まれます。

    2.  file がバックアップもしくは一時ファイルのようならば (例. サフィックスが ~, #, .OLD, .orig である)、無視します。

    3.  file が実行可能でなければ、無視します。

    4.  rc.conf(5) 変数の rc_fast_and_loose が空ならば、 file をサブシェルで読み込みます。 そうでなければ、カレントシェルで file を読み込みます。

set_rcvar [base]
    サービスを起動させるために必要な変数名を設定します。 通常 FreeBSD では、デーモンの名称に文字列 “_enable” を後置した rc.conf(5) 変数により、デーモンが制御されます。 これは NetBSD には当てはまりません。 次のような行がスクリプト中にある場合、

        rcvar=`set_rcvar`

    この関数は適切な rc.conf(5) 変数を作成するために、呼び出し側のスクリプトで定義されているべき変数 $name の値を使用します。 引数 base が設定されている場合は、 $name の代わりに base を使用します。

wait_for_pids [pid ...]
    指定された全ての pid が消失するまで待ち、 2 秒ごとに残存している pid を出力します。

warn message
    警告メッセージを stderr に表示し、 logger(1) を使用してシステムログに記録をします。 この警告メッセージは、スクリプト名 ($0 より), “: WARNING: ”, 及びこれに続く message で構成されます。

関連ファイル
/etc/rc.subr
    rc.subr ファイルは /etc に存在します。

関連項目
rc.conf(5), rc(8)

歴史
rc.subr スクリプトは NetBSD 1.3 で登場しました。 rc.d(8) をサポートする関数は NetBSD 1.5 で登場しました。 rc.subr スクリプトは FreeBSD 5.0 ではじめて登場しました。