共通デスクトップ環境 ToolTalk メッセージの概要

第 4 章 ToolTalk トレースの使い方

ToolTalk ttsession トレースは、ToolTalk パターンを ttsession にある各メッセージと一致させ配信する方法を示します。本リリースの ToolTalk トレースは次のことを行います。

単一クライアントの ToolTalk との対話を表示します。この機能により、実行者は 1 つのクライアントだけをトレースできます。
ttsession トレースを、たとえばメッセージ型、送信者、または受信者ごとといったフィルタに通します。

ToolTalk トレースへのアクセス

本リリースで新規のコマンドである tttrace は、主に ToolTalk トレースへのアクセスに使用します。このコマンドは、用途やコマンド行インタフェースの点で truss コマンドに似ています。このコマンドにより、3 種類の ToolTalk トレースをコントロールできます。ttrace コマンドには、サーバ・モードとクライアント・モードの 2 つの基本モードがあります。

サーバ・モードでは、Session_Trace 要求を送信することによって、指定されたセッションのトレースを指示します。
クライアント・モードでは、ttrace は環境変数を設定し、コマンド行に指定された ToolTalk クライアント・コマンドを実行します。実行されたクライアントの環境変数は、クライアント・メッセージとクライアント API 呼び出しをトレースするかどうかとその方法を libtt に指示します。

注 -

ttrace は、旧バージョンのサーバや、libtt の旧バージョンを使用するクライアントとの下位互換性はありません。ttrace は、旧バージョンのサーバを検出して診断すると、libtt の旧バージョンを使用するクライアント上で何も通知せずに異常終了します。

トレースのコントロール

libtt トレースのコントロール

libtt トレースの動作をコントロールする方法の 1 つは、環境変数 $TT_TRACE_SCRIPT を設定することです。

注 -

libtt のトレースは、変数の値が正確ではない場合や一貫性がない場合は異常終了します。

クライアント側トレースのコントロール

tt_trace_control 呼び出しは、内部フラグを設定または消去して、すべてのクライアント側トレースをコントロールします。この呼び出しを使用して、コード内の問題の領域をトレースします。この呼び出しの形式は次のとおりです。

int tt_trace_control(int option)

オプションの値として 0 を指定するとトレースをオフにし、1 を指定するとトレースをオンにします。-1 を指定すると、トレースのオンとオフを切り替えます。トレースがオンの場合は、トレースの範囲を TT_TRACE_SCRIPT 変数かトレースファイルでコントロールします。この呼び出しは、トレース・フラグの以前の設定を返します。

ToolTalk セッション内のメッセージ・トラフィックのトレース

Session_Trace 要求は、ttsession がそれ自身を処理するために登録する ToolTalk 要求です。つまり、ttsession は Session_Trace 要求のハンドラです。この要求は、どの ToolTalk クライアントでも送信できます。お勧めできる方法ではありませんが、この要求を処理するために他の ToolTalk クライアントを登録できます。

注 -

この方法ではトレースは行われません。

この要求の構文は次のとおりです

[file] Session_Trace( in boolean on,
                      in boolean follow
                      [in attribute toPrint
                      |in state toTrace
                      |in op toTrace
                      |in handler_ptype toTrace
                      |in sender_ptype toTrace][...] );

Session_Trace 要求は、配信範囲指定されたセッションでのメッセージ・トレースをオンまたはオフにします。

トレースがオンで、要求のファイル属性が設定されている場合、後続のトレース出力は属性が名前を付けたファイルに付け加えられます。
トレースがオンで、ファイル属性が設定されていない場合、トレースは現在のトレースを続行します。

デフォルトの場合、デーモン・モードでは ttsession を実行中のホストのコンソールが出力先になります。ジョブ・コントロール・モードでは、ttsession の標準エラーが出力先になります。表 4-1 は、この要求の必須およびオプションの引き数を示しています。

表 4-1 Session_Trace 引き数


引き数		説明
`boolean` on	必須	トレースをオンまたはオフにします。toTrace 引き数がなく on が true の場合は、前のトレース設定が復元されます。
`boolean` follow	必須	起動したクライアントのクライアント側トレースをオンにします。
`attribute` toPrint	オプション	トレースされた各メッセージの属性を出力します。有効な属性は次のとおりです。 none - トレースされたメッセージの記述を 1 行だけ出力 (デフォルト) all - トレースされたメッセージの属性全部を出力


`state` toTrace	オプション	メッセージをトレースするための状態。`tt_c.h` に定義されている `Tt_states` の他に有効な状態は次のとおりです。 edge - 初期の状態 (`TT_SENT`) と最後の状態 (`TT_HANDLED`、 `TT_FAILED`) を入力しているメッセージ deliver - すべての状態の変更と、すべてのクライアントの配信 dispatch - deliver 状態および一致するように考慮されたすべてのパターン (デフォルト)
`op` toTrace `sender_ptype` toTrace `handler_ptype` toTrace	オプションオプションオプション	表示されたメッセージ属性の値として toTrace を持っているトレース・メッセージ要求には、toTrace 引き数を任意の数だけ含めることができます。 toTrace にはシェルのワイルドカード文字も指定できます。指定のメッセージ属性に対して toTrace 引き数がない場合、トレースからメッセージを除外する属性の値もありません。

現在のセッション・トレースの動作は、この要求が失敗しない場合にのみ変更されます。失敗した場合には、応答の tt_message_status は表 4-2 で説明されているエラーの 1 つに設定されます。

表 4-2 Session_Trace 要求が返すエラー・メッセージ


エラー	説明
`TT_ERR_NO_MATCH`	要求に対するハンドラを見つけることができません。
`TT_ERR_APPFIRST + EACCES`	ttsession がトレース・ファイルを開くまたは作成するためのアクセス権を持っていません。
`TT_ERR_APPFIRST + EISDIR`	トレース・ファイルがディレクトリです。
`TT_ERR_APPFIRST + ENOSPC`	ターゲット・ファイル・システムにトレース・ファイルの作成に十分なスペースがありません。
`TT_ERR_APPFIRST + EEXIST`	トレースがすでに別のファイルで行われています。ttsession は、応答のファイル属性を再設定して既存のトレース・ファイルの名前を付けます。別のファイルへのトレースを行うには、最初に現在のトレース・ファイルへのトレースをオフにします。

サーバによる ToolTalk 呼び出しとメッセージのトレース

ttrace 関数は、指定の ToolTalk セッションのためにサーバによりメッセージ・トラフィックをトレースするか、ToolTalk クライアント・トレースをオンにしてコマンドを実行します。セッションとコマンドの両方とも指定されない場合は、デフォルトのセッションがトレースされます。デフォルトでは、ttrace が終了するとトレースも終了します。この関数の構文は次のとおりです。

  tttrace [-0FCa] [-o outfile ] -S session | command]
  tttrace [-e script | -f scriptfile ] [-S session | command]

表 4-3 では、ttrace オプションについて説明します。

表 4-3 tttrace オプション


オプション	説明
`-0`	セッション内のメッセージ・トレースをオフにするか、メッセージ・トレースを行わないで (つまり呼び出しのトレースだけを行なって) 指定のコマンドを実行します。
`-F`	指定のコマンドによってフォークされた、または ttsession によりセッション内で続けて起動されたすべての子を追跡します。通常、指定のコマンドだけか ttsession インスタンスがトレースされます。`-F` オプションが指定されている場合、プロセス ID がトレース出力の各行に表示され、どのプロセスが生成したかを示します。
`-C`	ToolTalk API へのクライアント呼び出しをトレースしないようにします。デフォルトでは呼び出しをトレースします。
`-a`	トレースされたメッセージのすべての属性、引き数、およびコンテキスト・スロットを出力します。デフォルトでは、トレース出力へメッセージを出力するには単一行だけを使用します。
`-o` `outfile`	トレース出力に使用されるファイル。セッション・トレースの場合、出力先は `tttrace` の標準出力です。
`-S` `session`	トレースするセッション。デフォルトではデフォルト・セッション、つまり `tt_open` が通知するセッションです。
`command`	起動し、トレースを行う ToolTalk クライアント・コマンド
`-e` `script`	`ttrace` 設定として使用されるスクリプト
`-f` `scriptfile`	`ttrace` 設定を読み取るファイル

ttrace は、ttsession へのメッセージ・インタフェースと TT_TRACE_SCRIPT 環境変数を使用する ToolTalk クライアントとして実行できるようになっています。この変数が設定されると、トレース・スクリプトに指定されているようにクライアント側トレースをオンにすることを libtt に通知します。値の最初の文字が「.」か「/」の場合、その値は使用するトレース・スクリプトが入っているファイルのパス名として認識されます。その他の文字の場合は、インライン・トレース・スクリプトとして認識されます。

トレースされた関数の形式

次は、トレースされた ToolTalk 関数の例です。

[pid] function_name(params) = return_value (Tt_status)

メッセージ要約形式

-a オプションは、次のように 1 行のメッセージ要約の後にメッセージ属性を出力します。

Tt_state Tt_paradigm Tt_class (Tt_disposition in Tt_scope) : status == Tt_status

状態変更形式

状態の変更は次の形式で示されます。

old_state => new_state.

メッセージ配信形式

配信は次のように示されます。

Tt_message => procid recipient_procid

表 4-4 は、ディスパッチ・トレース中に受信するメッセージついて説明しています。

表 4-4 ディスパッチ・トレース用の理由


メッセージ	説明
`tt_message_send`	送信するメッセージ
`tt_message_reject`	メッセージが拒否されました。
`tt_message_fail`	メッセージが無視されました。
`tt_message_reply`	メッセージへの応答
`tt_session_join`	参加するセッション
`tt_file_join`	参加するファイル
`tt_message_reply`	クライアントが指定の関数を呼び出しました。
`tt_message_send_on_exit`	ttsession は、`tt_close` を呼び出す前に切り離されたクライアントに対して on_exit メッセージをディスパッチしています。
`tt_message_accept`	ttsession は、ptype が起動されている間にブロックされたメッセージをディスパッチしています。起動されたクライアントは、ptype がブロック解除されることを示す `tt_message_accept` か `tt_message_reply` のどちらかを呼び出します。
`TT_ERR_PTYPE_START`	ptype インスタンスがメッセージの受信のために起動されましたが、起動コマンドは ttsession に接続される前に終了しました。
`TT_ERR_PROCID`	ttsession はこの要求に応じて動作中であったクライアントとの接続を切りました。
`ttsession -> ttsession`	別のセッションが、このセッションに対してメッセージの受信者を見つけるように求めています。
`ttsession <- ttsession`	別のセッションが、このセッションで発信したメッセージの更新 (たとえば失敗すること) を求めています。

形式の照合

ディスパッチがトレースされているとき、照合は次の形式のうちの 1 つで示されます。

Tt_message & Tt_pattern {
Tt_message & ptype ptid {
Tt_message & otype otid {

パターンまたはシグニチャーが次の形式で出力されます。

} == match_score; [/* mismatch_reason */]

例

この節では、tttrace 関数の使用例を取り上げます。

パターンの登録とパターンとの一致通知の送信

パターンを登録し、そのパターンに一致するという通知を送信するには、次のように入力します。

 % tttrace -a myclientprogram

例 4-1 は、その結果を示します。

例 4-1 パターンの登録と通知の送信

tt_open() = 0x51708=="7.jOHHM X 129.144.153.55 0" (TT_OK) 
tt_fd() = 11 (TT_OK)  
tt_pattern_create() = 0x50318 (TT_OK) 
tt_pattern_category_set(0x50318, TT_OBSERVE) = 0 (TT_OK) 
tt_pattern_scope_add(0x50318, TT_SESSION) = 0 (TT_OK) 
tt_pattern_op_add(0x50318, 0x2f308=="Hello World") = 0 (TT_OK) 
tt_default_session() = 0x519e0=="X 129.144.153.55 0" (TT_OK) 
tt_pattern_session_add(0x50318, 0x519e0=="X 129.144.153.55 0") = 0 (TT_OK) 
tt_pattern_register(0x50318) = 0 (TT_OK)  
tt_message_create() = 0x51af0 (TT_OK)
tt_message_class_set(0x51af0, TT_NOTICE) = 0 (TT_OK) 
tt_message_address_set(0x51af0, TT_PROCEDURE) = 0 (TT_OK) 
tt_message_scope_set(0x51af0, TT_SESSION) = 0 (TT_OK) 
tt_message_op_set(0x51af0, 0x2f308=="Hello World") = 0 (TT_OK) 
tt_message_send(0x51af0)        ...
    TT_CREATED => TT_SENT:
    TT_SENT TT_PROCEDURE TT_NOTICE (TT_DISCARD in TT_SESSION): 0 == TT_OK
    id:             0 7.jOHHM X 129.144.153.55 0
    op:             Hello World
    session:        X 129.144.153.55 0
    sender:         7.jOHHM X 129.144.153.55 0
= 0 (TT_OK)         
tt_message_receive()        ...
    Tt_message => procid <7.jOHHM X 129.144.153.55 0>
    TT_SENT TT_PROCEDURE TT_NOTICE (TT_DISCARD in TT_SESSION): 0 == TT_OK
    id:             0 7 jOHHM X 129.144.153.55 0
    op:             Hello World
    session:        X 129.144.153.55 0
    sender:         7.jOHHM X 129.144.153.55 0
    pattern:        0:7.jOHHM X 129.144.153.55 0 
= 0x51af0 (TT_OK)

ttsession によるメッセージ・フローの表示を見るには、次のように入力します。

 % tttrace -a

ttsession による mylientprogram のメッセージ・フローの表示は、例 4-2 のとおりです。

例 4-2 ttsession によるトレースの表示

tt_message_reply:
    TT_SENT => TT_HANDLED:
    TT_HANDLED TT_PROCEDURE TT_REQUEST (TT_DISCARD in TT_SESSION): 0 == TT_OK
    id:     0 2.jOHHM X 129.144.153.55 0
    op:     Session_Trace
    args:   TT_IN string: "> /tmp/traceAAAa002oL; version 1; states"[...]
    session:X 129.144.153.55 0
    sender: 2.jOHHM X 129.144.153.55 0
    pattern:0:X 129.144.153.55 0
    handler:0.jOHHM X 129.144.153.55 0 
    Tt_message => procid <2.jOHHM X 129.144.153.55 0>        
tt_message_send:
    TT_CREATED TT_PROCEDURE TT_NOTICE (TT_DISCARD in TT_SESSION): 0 == TT_OK
    id:     0 7.jOHHM X 129.144.153.55 0
    op:     Hello World
    session:X 129.144.153.55 0
    sender: 7.jOHHM X 129.144.153.55 0                
    TT_CREATED => TT_SENT:
    TT_SENT TT_PROCEDURE TT_NOTICE (TT_DISCARD in TT_SESSION): 0 == TT_OK
    id:     0 7.jOHHM X 129.144.153.55 0 
    op:     Hello World
    session:X 129.144.153.55 0 
    sender: 7.j HHM X 129.144.153.55 0
    Tt_message & Tt_pattern { 
    id:     0:7.jOHHM X 129.144.153.55 0
    category:TT_OBSERVE
    scopes: TT_SESSION
    sessions:X 129.144.153.55 0
    ops:    Hello World
    } == 3;
    Tt_message => procid <7.jOHHM X 129.144.153.55 0>

注 -

トレースされた最初のメッセージは、ほとんどの場合 ttrace が送信した要求への ttsession による応答になります。

メッセージ・フローのトレース

特定の、デフォルトではないセッション内のメッセージ・フローをトレースするには、次のように入力します。

 % tttrace -S "01 15303 1342177284 1 0 13691 129.144.153.55 2"

"01 15303 1342177284 1 0 13691 129.144.153.55 2" は、デフォルトではない特定のトレースされるセッションです。

ToolTalk トレースのための設定

ttrace スクリプトには、ToolTalk 呼び出しとメッセージをコントロールする設定があります。ttrace スクリプトは、セミコロンか復帰改行で区切られたコマンドから成ります。重複している値が設定に指定されると、最後の値が使用されます。

表 4-5 では、これらのコマンドについて説明します。

表 4-5 tttrace スクリプト・コマンド


コマンド	説明
`version` n	使用されている `tttracefile` コマンド構文のバージョン。現在のバージョンは 1 です。
`follow [off \| on]`	トレースされたクライアントによってフォークされた、またはトレースされたセッションで続けて起動されたすべての子についても追跡するかどうか設定します。デフォルトは `off` です。
`[> \| >>]` `outfile`	トレース出力に使用されるファイル。デフォルトでは、トレースの出力先は標準エラーです。> と >> の通常のシェル解釈が適用されます。
`functions` [`all \| none` \| `func`...]	トレースする ToolTalk API 関数。`func` には、シェル・ワイルドカード文字が入ります。デフォルトは `all` です。
`attributes [all \| none]`	`none` (デフォルト) は、トレース出力にメッセージを出力するときに単一行だけを使用することを意味します。`all` は、トレースされたメッセージの属性、引き数、コンテキスト・スロットすべてを出力することを意味します。
`states [none \| edge \| deliver \| dispatch \| Tt_states]...`	メッセージをトレースするための状態。`tt_c.h` に定義されている `Tt_states` の他に有効な`状態`は次のとおりです。 `none` - メッセージのトレースをすべて使用不可能にする `edge` - 最初の状態 (`TT_SENT`) と最後の状態 (`TT_HANDLED`、`TT_FAILED`) を入力しているメッセージ `deliver` - すべての状態の変更と、すべてのクライアントの配信 `dispatch` - 配信および一致するように考慮されたすべてのパターン (デフォルト)
`ops` `toTrace`... `sender_ptypes` `toTrace`... `handler_ptypes` `toTrace`...	表示されたメッセージ属性の値として `toTrace` を持っているトレース・メッセージ。`toTrace` にはシェル・ワイルドカード文字が入ります。指定のメッセージ属性に対して指定されている `toTrace` 引き数がない場合、その属性の値でメッセージをトレースから除外するものもありません。