prcmd(3N)

システム名 (ドメインサフィックスの有無を問わず)、 またはドット表記で指定したインターネットアドレスのいずれか。 この値は各ホストごとに異なるので、呼び出し側プログラムは、 prcmd_init() にリストを直接渡すよりも、簡単に値をセットすることができます。

この値は、 呼び出し側プログラムが割り当てるメモリのポインタになります。 prcmd() がホストへの接続を確立するまで、下層のデータを破壊しないようにしてください。 接続が確立された後は、 prc_hostid は必要なくなります。

rcmd() と同様に prcmd() は、ホスト名の参照を指定してインターネットアドレスを 確保しますが、 rcmd() とは異なり、呼び出し側プログラムの prc_hostid 値は変更しません。

あるホストの接続を行っている間にシステムコールが異常終了すると、 下記の場合を除き、 prcmd() は、ホストの prc_conn_status フィールドを PRC_CONN_FAILED にセットし、 異常終了した呼び出しから戻される値 errno に prc_errno をセットした後、 ファイル (ソケット) 記述子と、 ホストに対応するストリームポインタ (存在する場合) をすべて クローズします。

接続のリモート側の (remshd) で異常終了が起きた場合 (下記参照)、 あるいはホストの標準エラーポートに不当な接続を試みた場合、 prcmd() は、 prc_conn_status を PRC_CONN_REFUSED にセットして、 ホストの prc_fp と prc_fp2 の各フィールドで指定されたファイルをクローズします。 リモート remshd からのメッセージ (最大 BUFSIZ-1 文字) があり、 malloc() が正常終了の場合、 prcmd() は prc_errmsg が指す位置にメッセージテキストを保存します。 これ以外の場合、そのフィールドにはヌルポインタが残ります。 また、「ローカル」な理由で拒否が起き、 errno がある場合、 prcmd() は、その値を prc_errno にセットします。これ以外の場合は 0 にセットします。

接続が PRC_CONN1_WAIT, PRC_CONN2_WAIT, または PRC_CONN3_WAIT のいずれかの状態にあり (下記参照)、 select() によりホストの準備できていないことが報告され、 かつホストが該当する状態に入ってから timeout 秒が経過すると、接続がタイムアウトになります。 テストは、 time() を使用して秒単位の精度で行われます。 この場合、 prcmd() は、ホストに対する prc_conn_status フィールドを PRC_CONN_TIMEOUT にセットし、ホストの prc_fp と prc_fp2 の各フィールドで指定されたファイルをクローズします。

名前で指定されたホストは、 ホストデータベースにある複数の IP アドレスでリストすることができます。 この場合、ホストの IP アドレスの 1 つに対する接続が失敗すると、 PRC_READ_WAIT 状態に入って prcmd() がホストの次の IP アドレス (ホストあたりの最大 IP は 5 個) への接続オープンを試みる前に、接続が拒否、あるいは タイムアウトになります。 すべての IP アドレスが試行されるまで、異常終了にはなりません。

prcmd() は、名前の prc_hostid 値を 1 つ以上の IP アドレスにマップします (アドレスとみなされない場合)。 さらに、 IP アドレスをバイナリにマップし、 ホストとの通信用として予約されたポート番号に対応する インターネットソケットを受け取り、 fdopen() を使用して、このソケット記述子をストリームポインタにマップした後、リモートホストの「シェル」サービスに対して ソケット記述子のノンブロッキング connect() を実行します。 ソケットの送受信バッファサイズはデフォルトとなります。 ただし、呼び出し側プログラムでは必要に応じ setsockopt (fileno (hostp → prc_fp)) を使用して、サイズを変更できます。なお、このサイズは setsockopt(2) で説明された制限に従います。

gethostbyname() ( gethostbyname(3N) 参照)、または inet_addr() ( inet_addr(3N) 参照) が異常終了すると、 prcmd() は、 prc_conn_status フィールドを PRC_CONN_NO_IPS にセットします。

rcmd() 接続に必要な情報には、 「シェル」サービスのポート番号、 およびローカル/リモートユーザー名としての 実効ユーザー ID のユーザー名があります。 prcmd() は、最初に接続を行う時点でこの情報を探します。 prcmd() がこの情報を得られない場合は、 PRC_ERR_RCMD を返します (呼び出しのたびに試行します)。

socket() が、 EHOSTDOWN, EAFNOSUPPORT, ESOCKTNOSUPPORT, EPROTONOSUPPORT, EPROTOTYPE, または EINVAL のいずれかのローカルホスト エラーとともに異常終了すると、 prcmd() は PRC_ERR_NETWORKING を返し、 ホストリストのステータスは未定義になります。

socket() が EMFILE または ENFILE とともに異常終了 (すなわちプロセス、またはシステムにファイル記述子がないとき ) した場合、あるいは 予約されたポートがない場合は、 prc_conn_status フィールドは、後で使用できるように PRC_CONN_NONE として残されます。 ホストエントリーをすべてチェックした後、 prcmd() がいずれのホストについてもオープンファイル (ソケット) を持っておらず、 かつ、この呼び出しの間にいずれのファイルもクローズしていない場合は、 PRC_ERR_NOFILE が返されます。 ― すなわちこのプロセスに全ファイル記述子が使用され、 prcmd() にはファイル記述子がないことになります。

connect() が正常終了した場合、あるいは EINPROGRESS とともに異常終了した場合 (ノンブロッキング接続要求の場合は正常です)、 prcmd() は、 prc_conn_status を PRC_CONN1_WAIT に、また prc_conn_time を現在のシステムクロック (秒単位) に、さらに prc_fp をソケットのストリームポインタにそれぞれセットします。 次いで、このホストは、 PRC_CONN1_WAIT ごとに select() リストに入れられます (下記参照)。

prcmd() により、このホストが書き込みレディとして select() リストに入れられます。 接続が書き込み用として準備できていない場合、 prc_conn_status フィールドは変更されません。

接続が書き込み用として準備できている場合、 prcmd() は、「ブロッキング」にソケットを返し、 リモートコマンドから戻される標準エラーの接続を開始します。 また、この接続に対するファイルポインタに prc_fp2 をセットし、 sigvector() を使用して一時的に無視された SIGPIPE とともにリモートプロセスに対し標準 remsh 接続情報 ( remshd(1M) および上記の説明を参照) を書き込みます。 さらに、 prc_conn_status を PRC_CONN2_WAIT, に変更して、 prc_conn_time を現在のシステムクロック (秒単位) にセットします。

接続が拒否されると、 prcmd() は、remsh 接続情報を書き込もうとした時点で ECONNREFUSED または EPIPE を受け取り、 ``共通エラーの処理'' の項で先述した形式でエラーを処理します。

prcmd() により、 prc_fp (エラーの場合)、と prc_fp2 (標準エラーポートに接続成功が戻され場合) の両方に 読み取りレディとして select() リストにこのホストが入れられます。 いずれの接続も読み取りレディでない場合は、 prc_conn_status フィールドは変更されません。

標準エラー接続が読み取りレディの場合、 prcmd() は、 accept() を実行して、もとの prc_fp2 をクローズし、新しい socket/fd に対する値を更新します。 さらに prc_conn_status を PRC_CONN3_WAIT を変更して、 prc_conn_time を現在のシステムクロック (秒単位) にセットします。

読み取りレディとなるのが stdout 接続だけの場合は、 remshd が異常終了したことになります。 prcmd() は、この状態を ``共通エラーの処理'' で説明したとおり、接続の拒否として処理します。

ファイル記述子、または予約ポートが必要なときに、 これが存在しない場合は、 ホストが PRC_CONN1_WAIT または PRC_CONN2_WAIT のステータスに置かれます。

prcmd() により、このホストが読み取りレディとして select() リストに入れられます。 接続が読み取りレディでない場合、 prc_conn_status フィールドは変更されません。

接続が読み取りレディでない場合、 prcmd() は remshd からの stdout 中でヌルバイトを占め、 prc_conn_status を PRC_READ_WAIT にセットします。また、 呼び出し側のプログラムが対話できるように、 prc_conn_time を現在のシステムクロック (秒単位) にリセットします。 ヌル以外のバイトが返された場合は、 remshd が異常終了したことになります。 prcmd() は、先述のように、この状態を接続の拒否として処理します。

prcmd() により、このホストが 読み取りレディとして select() リストに入れられます。 接続が読み取りレディでない場合、 prc_conn_status フィールドは変更されません。 リモートコマンドが、呼び出し側プログラムから データが書き込まれるまで待っていることがあります。

接続が読み取りレディの場合、 prcmd() は prc_conn_status を PRC_READ_READY にセットします。

prcmd() は、この状態のホストを PRC_READ_WAIT と同様に処理します。 接続が読み取りレディでない場合、 prcmd() は、 prc_conn_status を PRC_READ_WAIT に戻します。

prcmd() は、このホストのエントリーを無視します。

prc_conn_close フィールド (呼び出し側フィールドでセットされる) が非ゼロの場合、 prcmd() は、別の状態からこの状態に入ります。 また、 prc_fp と prc_fp2 で指定されたファイル (ヌルでない場合) をクローズし、 各フィールドをヌルによりセットし、 prc_conn_close フィールドを 0 にリセットします。

これらのいずれの故障ステータス値の場合、 prcmd() はホストエントリーを無視します。ただし prc_conn_close がセットされているときは、エントリーの prc_conn_status フィールドが PRC_CONN_DONE にセットされます。

最初の prcmd() 呼び出しの後。 1 つ以上の接続を行った後 (あるいは今回の呼び出し、 または前回の呼び出しでまだオープンされているときに)、 プロセスのソケット (ファイル) 記述子、 または予約済みポートが不足していることを示します。 このホストに対する接続が、次回の呼び出しで再度試みられます。 呼び出し側プログラムは、ファイルをクローズする、あるいは rlimit() を呼び出すことにより、可用なファイル記述子の数が増やすか、 あるいは既存の接続が通信を終了するまで待機します。

これらは、呼び出し側プログラムにはほとんど無関係の内部状態です。 後で prcmd() を再度呼び出す場合を除き、 必要な動作はありません。 (prc_prev_status != prc_conn_status) の場合、呼び出し側プログラムではホストの新しいステータス をログ/表示することができます。

コマンドが実行中ですが、まだ出力が生成されていません。 呼び出し側プログラムが最初に通信する場合は、 コマンドで何らかの初期入力が必要になるので、 prc_fp で指定されるファイルに書き込みを行い、 prc_caller_status フィールドを使用して書き込みが行われたことを記憶しておきます。 これ以外の場合は、接続ステータスのログ/表示を除き、 必要な動作はありません。

コマンドにより、読み取りレディの出力が生成されました。 出力を読み取った後、コマンドがさらに入力を必要とする場合は、 prc_fp で指定されたファイルに書き込みを行います。 代わりに、対話を行う場合は、 prc_conn_close フィールドを非ゼロにセットします。

コマンドが終了しました。 呼び出し側プログラムが prc_conn_close フィールドをセットした後、 接続がクローズされました。 必要な動作はありません。

呼び出し側プログラムでは、 (prc_conn_status & PRC_CSBIT_ERR) を使用して、エラーステータスを効率的に検出 できます。 1 回限りの処理の場合は (prc_prev_status != prc_conn_status) を使用して 新しいエラー状態を検出することができます。 また、 prc_caller_status を使用して、 prcmd() から最初に戻された時点で処理されたことを記録することもできます。 いずれの場合も、呼び出し側プログラムでは、必要に応じてエラーを 処理、または報告できなければなりません。

prc_hostid フィールドがアドレスではなく名前とみなされ、 対応する gethostbyname() が異常終了、あるいは inet_addr() が prc_hostid の数値で異常終了します。

その他の条件は、ホストの IP アドレスの最後 (複数存在する場合) で起きた異常終了の原因 だけを参照します。

ローカルシステムが故障したことにより、何らかの理由で (ホストの IP アドレスのいずれか) 接続が開始できません。 prc_errno が異常終了したシステムコールの値 errno にセットされます。

接続の拒否。 errno(2)ごとに、 `` 外部ホストで非アクティブになっているサービスに接続しようとすると起きます。" また、その他のリモート (remshd) の故障 (アクセスの拒否など) や標準エラーポートへの 不当な接続なども考られます。

呼び出し側プログラムでは、ホストの prc_errmsg フィールドをチェックしなければなりません。 ヌルポインタでない場合は、 remshd リモートコマンドからメッセージテキストが送られ、 呼び出し側プログラムでは値の使用が終わった時点で ポインタを free() にする必要があります。

接続のタイムアウト。 接続は、 I/O の準備ができない PRC_CONN1_WAIT、 PRC_CONN2_WAIT、 または PRC_CONN3_WAIT のいずれかの状態に timeout 秒以上の間、置かれます。

呼び出し側プログラムが、ストリームではなく、 ソケット (ファイル) 記述子を使用してバッファリングされていない I/O を行う場合、 fileno(prc_fp) ( fileno(3S) 参照) を参照することができます。

呼び出し側プログラムがリモートコマンドに 信号を送信する場合、 prc_fp2 で指定されるファイルに信号番号を書き込むことができます ( rcmd(3N) 参照)。

prcmd() にすべての接続をクローズさせる場合は、 全ホストに prc_conn_close をセットし、 prcmd() を再度呼び出す以外に、方法はありません。 これにより、 prc_conn_status が PRC_CONN_DONE にセットされます。