Vue 関数

add_range(range_t range_data, String S1, String S2, ..., String Sn);

range_data

range_t データ型。

S1, S2,...

range_data パラメーターに追加される文字列。

void append ( List listvar, long long val );

append 関数は、 Vueで使用可能な唯一のリスト連結関数です。 この関数は、最初のパラメーターで指定されたリスト変数に、2 番目のパラメーターで指定された値を追加します。 append 関数への呼び出しごとに、リスト変数に既に保存されている値のセットに新しい値が追加され、リスト変数のサイズが大きくなります。 また、append 関数は別のリストを引数として受け入れるため、2 つのリストを結合することもできます。

append 関数には戻り値がありません。

リスト・データ・タイプについて詳しくは、 リスト・タイプを参照してください。 上記の list セクションには、 append 関数を使用するスクリプトの例があります。

int atoi( String str ); 

atoi 関数は、str パラメーターで指定された文字列で表記される値をもつ整数を戻します。 この関数は、数字 (0-9) でない最初の文字まで文字列を読み取り、スキャンした文字を同等の整数に変換します。 先頭の空白文字は無視されます。オプションの符号標識は数字の前に付けることができます。

atoi 関数は、すべての引数を二重引用符で囲む sprobevue シェル・スクリプトを実行する場合に文字列を整数に戻すのに役立ちます。 次のスクリプトの例では、予期したよりも速く fork するプロセスを収集します。

/* File: ffork.e 
 *
 * Usage: sprobevue ffork.e processname delta
 *
 *	Traces whenever a specified process is forking faster than
 *	the "delta" value passed. Specify a process name and the time
 *	in milliseconds as parameters.
 */

/* Ignore other parameters to execve */
int execve(char *path);

@@BEGIN
{
	int done;
	int pid;

	pname = $1;		/* name of process we are monitoring */

	/* 
	 * Since sprobevue is used, need to extract the integer value
	 * from the string (double quotes around the delta).
	 */
	delta = atoi($2);	/* minimum delta in millisecs between forks */
	printf("pname = %s, delta = %d\n", pname, delta);
}

@@syscall:*:execve:entry
	when (done == 0)
{
	__auto String exec[128];
	__thread int myproc;

	/* Find process being 'exec'ed */
	exec = get_userstring(__arg1, 128);

	/* Got it. Set a thread-local and reset 'done' so that we 
	 * avoid entering this probe from now on.
	 */
	if (exec == pname) {
		pid = __pid;
		myproc = 1;
		done = 1;
		printf("Process name = %s, pid = %d\n", __pname, pid);
	}
}

@@syscall:*:fork:entry
	when (thread:myproc == 1)
{
	/* old_ts is initialized to zero */
	probev_timestamp_t old_ts, new_ts;
	unsigned long long interval;

	/* Get current time stamp */
	new_ts = timestamp();

	/* Find time from last fork */
	if (old_ts != 0) {
		interval = diff_time(old_ts, new_ts, MILLISECONDS);

		/* if below the specified limit, trace that */
		if (interval < delta)
			printf("%s (%ld) forking too fast (%d milliseconds)\n",
					pname, __pid, interval);
	}

	/* Save current fork timestamp */
	old_ts = new_ts;
}

@@syscall:*:exit:entry
	when (__pid == pid)
{
	/* Catch process exit and terminate ourselves */
	printf("Process '%s' exited.\n", pname);
	exit();
}

long long avg ( List listvar );

avg 関数は、listvar パラメーターで指定されたリスト変数に追加されたすべてのエレメントの平均を戻します。

void commit_tentative( String bufID );
void discard_tentative( String bufID );

commit_tentative 関数は、bufID パラメーターで識別される一時トレース・バッファーと関連するトレース・データをコミットします。 これにより、データが保存され、トレース・コンシューマーが使用できるようになります。

discard_tentative 関数は、bufID パラメーターで示される一時トレース・バッファー内のすべてのデータを廃棄します。 これにより、一時トレース・データで満たされたトレース・バッファーのスペースが解放されます。

一時トレース・データを通常のトレース・データと一緒に保存する場合、後でコミットされる、以前の一時トレース・データと、通常のトレース・データはトレース・コンシューマーに対してタイム・スタンプ順で使用可能になります。 このため、トレース・バッファーを解放するために、可能な限り最も早い段階で一時データをコミットまたは廃棄するのが適切です。

ProbeVue セッションが終了すると、コミットされていない一時トレース・データはすべて破棄されます。

一時トレース のトピックでは、一時トレースについて詳しく説明し、一時トレースを使用する Vue スクリプトの例を示します。

ipv4_data

ip_addr_t 形式に変換する必要がある IPv4 アドレス・データを指定します。

ip_addr_t convert_ip6_addr (int *ipv6_data);

ipv6_data

ip_addr_t 形式に変換する必要がある ipv6 アドレス・データを指定します。

/* Declare the Function prototype */
int sendto(int s,  char * uap_buf,   int len,  int flags,  char * uap_to,  int tolen);

typedef unsigned int in_addr_t;

/* Structure Declarations */

/* Declare the in_addr structure */
struct in_addr {
        in_addr_t        s_addr;
};

/* Declare the sockaddr_in structure */
struct sockaddr_in {
        unsigned char           sin_len;
        unsigned char           sin_family;
        unsigned short          sin_port;
        struct in_addr          sin_addr;
        unsigned char           sin_zero[8];
};
/* Declare the in6_addr structure */
struct in6_addr {
        union {
                int s6_addr32[4];
                unsigned short s6_addr16[8];
                unsigned char  s6_addr8[16];
        } s6_addr;
};
/* Declare the sockaddr_in6 structure */
struct sockaddr_in6 {
        unsigned char          sin6_len;
        unsigned char          sin6_family;
        unsigned short         sin6_port;
        unsigned int           sin6_flowinfo;
        struct   in6_addr      sin6_addr;
        unsigned int           sin6_scope_id;  /* set of interfaces for a scope */
};


/* Print the information about to whom it is sending data */
@@syscall:*:sendto:entry
{
        struct sockaddr_in6 in6;
        struct sockaddr_in in4;
        ip_addr_t ip;

                /* Copy the arg5 data into sockaddr_storage variable */
                /* using copy_userdata( ) Vue function */
        copy_userdata(__arg5, in4);

       /*
        * Verify  whether the destination address is IPv4 or IPv6 and based on that call the
        * corresponding IPv4 or IPV6 conversion routine.
        */
       if (in4.sin_family == AF_INET)
       {
               /* Copy the ipv4 data into sockaddr_in structure using copy_userdata routine */
                copy_userdata(__arg5, in4);

               /* Convert Ipv4 data into ip_addr_t format */
                ip = convert_ip4_addr(in4.sin_addr.s_addr);

               /* Print the destination address and hostname  using %H and %I format specifier */
               printf("It is sending the data to node %H(%I)\n",ip,ip);
        }
        else if(in4.sin_family == AF_INET6)
        {
              /* Copy the ipv6 data into sockaddr_in6 structure using copy_userdata routine */
               copy_userdata(__arg5, in6);

              /* Convert Ipv6 data into ip_addr_t format */
               ip = convert_ip6_addr(in6.sin6_addr.s6_addr.s6_addr32);

              /* Print the destination address and hostname using %H and %I format specifier */
              printf("It is sending the data to node %H(%I)\n", ip,ip);
        }
}

long long count ( List listvar );

count 関数は、listvar パラメーターで指定されたリスト変数に追加されたエレメントの数を戻します。

リスト・データ型について詳しくは、 Vue のデータ型を参照してください。 上記の list セクションには、 count 関数を使用するスクリプト例があります。

void copy_kdata( <type> *kaddr,<type>svar);

copy_kdata 関数は、カーネル・メモリーから Vue スクリプト変数にデータを読み取ります。 変数は、ポインター型を除き、 Vue でサポートされる任意の C-89 型にすることができます。 コピーされるデータの長さは、変数のサイズと同じです。 例えば、ターゲットの Vue スクリプト変数が int 型の場合は 4 バイトがコピーされ、long long 型の場合は 8 バイトがコピーされ、12 個の整数または int [12] の配列の場合は 48 バイトがコピーされます。

カーネル・スペース内のデータは、式で使用したり、 Vue 関数にパラメーターとして渡したりする前にコピーする必要があります。

プロセスがこの関数を実行しているときに例外が発生した場合 (例えば、正しくないカーネル・アドレスが関数に渡された場合)、 ProbeVue セッションは打ち切られ、エラー・メッセージが出されます。

kaddr (Kaddr)

カーネル・スペース・データのアドレスを指定します。

svar

カーネル・データのコピー先となるスクリプト変数を指定します。 スクリプト変数の型は、カーネル・データの型にすることができます。

void copy_userdata( <type> *uaddr,<type>svar);

copy_userdata 関数は、ユーザー・メモリーから Vue スクリプト変数にデータを読み取ります。 この変数は、 Vue でサポートされる C-89 型のいずれかです。 コピーされるデータの長さは、変数型のサイズと同じです。 例えば、ターゲットの Vue スクリプト変数が int 型の場合は 4 バイトがコピーされ、long long 型の場合は 8 バイトがコピーされ、12 個の整数または int [12] の配列の場合は 48 バイトがコピーされます。

ユーザー・スペース内のデータは、式で使用したり、 Vue 関数にパラメーターとして渡したりする前にコピーする必要があります。

プロセスがこの関数を実行している間に例外が発生した場合 (例えば、不正なユーザー・アドレスが関数に渡された場合)、 ProbeVue セッションは打ち切られ、エラー・メッセージが出されます。

uaddr (uaddr)

ユーザー・スペース・データのアドレスを指定します。

svar

ユーザー・データのコピー先となるスクリプト変数を指定します。 スクリプト変数の型は、 ユーザー・データの型にする必要があります。

unsigned long long diff_time( probev_timestamp_t ts1, probev_timestamp_t ts2, intformat );

diff_time 関数は、timestamp 関数を使用して記録された 2 つのタイム・スタンプの時間差を戻します。 この関数は、format パラメーターで指定されるマイクロ秒またはミリ秒で時間差を戻します。

get_location_point セクションと list セクションには、 diff_time 関数を使用するスクリプトの例があります。

void eprintf ( String format[ , data, ... ]);

eprintf 関数は printf 関数と似ていますが、出力が標準エラーに送信される点が異なります。 eprintf 関数は、 format パラメーターに応じて、data パラメーターの値を変換、フォーマットして トレース・バッファーにコピーします。 構文が示すように、 引数の可変リストが data パラメーターとして eprintf 関数に渡されます。 Vue は、 C ライブラリーの printf サブルーチンでサポートされる変換指定子を %p 以外すべてサポートしています。

eprintf 関数を使用して リスト型の変数を出力することはできません。 ただし、文字列型の変数は、%s 変換指定子を使用して出力できます。 probev_timestamp_t 型の変数は、%lld 指定子または %16llx 指定子を使用して数値形式で出力されます。 probev_timestamp_t 型の変数は、%A 指定子または %W 指定子を使用して日付形式で出力されます。

format

変更なしでトレース・バッファーに直接コピーされるプレーン文字を含む文字列。 data パラメーターのフォーマット方法を示す別の 1 つ以上の変換指定子。

データ

format パラメーターの変換指定子に対応するゼロ個以上の引数を指定します。

void exit();

exit 関数は Vue スクリプトを終了します。 この関数は、動的トレース・セッションで使用可能なすべてのプローブを使用不可にし、一時トレース・データを廃棄し、@@END プローブで示されたアクションを実行し、収集されたすべてのトレース・データをトレース・コンシューマーにフラッシュします。 トレース・コンシューマーが @@END プローブでトレースされた出力を印刷すると、トレース・セッションが終了し、probevue プロセスが終了します。

これは probevue コマンドが実行された端末で Ctrl-C を押した場合と同様です (フォアグラウンド・タスクとして実行されている場合)。 また、kill コマンドまたは kill システム・コールを使用して SIGINT を probevue プロセスに直接送ることもできます。

list セクションには、 exit 関数を使用するスクリプトの例があります。 atoi セクションには、プローブしているプロセスの終了と同時に終了する方法を示すサンプル・スクリプトがあります。

char * fd_fname(int fd); 

この関数は、特定ファイル・ディスクリプターのファイルの名前を取得します。 これは、同じファイルについて、__file->fname (I/O プローブ・マネージャーの __file 組み込み変数を参照) と同じ値を戻します。

fd

ファイル・ディスクリプターまたはソケット・ディスクリプターの値

int fd_fstype(int fd);

fd

ファイル・ディスクリプターの値

int fd_ftype(int fd);

この関数は、特定のファイル・ディスクリプターのファイル・タイプを取得します。 これは、__file->f_type (I/O プローブ・マネージャーの __file 組み込み変数を参照) と同じ値を戻します。

fd

ファイル・ディスクリプターの値

unsigned long long fd_inodeid(int fd);

この関数は、特定のファイル・ディスクリプターに関連したファイルの i ノード ID を戻します。 i ノード ID は、システム内で固有な unsigned long long 値です (ファイルシステムの i ノード番号とは異なり、システムがリブートすると値が変更される可能性があります)。 この値は、同じファイルについて fpath_inodeid() 関数によって戻される値と一致します。

fd

ファイル・ディスクリプターの値

char * fd_mpath(int fd);

この関数は、特定のファイル・ディスクリプターのファイルが属しているファイルシステムのマウント・パスを取得します。 これは、同じファイルについて、__file->mount_path (I/O プローブ・マネージャーの __file 組み込み変数を参照) と同じ値を戻します。

fd

ファイル・ディスクリプターの値

path_t fd_path(int fd); 

この関数は、特定ファイル・ディスクリプターのファイルの絶対パスを戻します。 戻り値の型は path_t です。 これは、同じファイルについて、 __file->path( 入出力プローブ・マネージャーの __file 組み込みを参照 ) と同じ値を戻します。

fd

ファイル・ディスクリプターの値

unsigned long long fpath_inodeid(String file_path); 

この関数は、特定のファイル・パスの i ノード ID を戻します。 i ノード ID は、システム内で固有な unsigned long long 値です (ファイルシステムの i ノード番号とは異なり、システムが再始動すると値が変更される可能性があります)。 ファイル・パスが存在しない場合、Vue スクリプトは probevue コマンドによってリジェクトされます。 i ノード ID 値は、同じファイルの vfs プローブ・イベント内の __file->inode_id によって提供されるものと同じままです ( 入出力プローブ・マネージャーの __file 組み込みを参照 ) 。

file_path

既存のファイルを表す、二重引用符で囲まれたリテラル・ストリング。 例えば、"/usr/lib/boot/unix_64" です。 変数にすることはできません。

String get_function ( );

get_function 関数は、プローブされる関数、すなわち現行プローブ・ポイントを囲む関数の名前を戻します。 通常、プローブされる関数の名前は、ロケーション・フィールドの前にあるプローブ・ポイント組です。

上記の get_probe セクションには、 get_function 関数を使用するスクリプトの例があります。

get_function 関数は、間隔プローブ・マネージャーから呼び出された場合は空文字列を戻します。

get_function 関数はパラメーターを取りません。

String get_kstring( char *kaddr,int len);

get_kstring 関数は、カーネル・メモリー内のデータを String 型の変数に読み取ります。

カーネル・スペース内のストリングは、式で使用したり、 Vue 関数にパラメーターとして渡したりする前にコピーする必要があります。

get_kstring 関数のターゲットは、常に String 型の変数でなければなりません。 len パラメーターに値 -1 が指定されている場合、NULL バイトが読み取られるまで、データはカーネル・メモリーからコピーされます (C 言語では、テキスト・ストリングを停止するために NULL バイトが使用されます)。 文字列の長さがターゲットの String 変数の宣言されたサイズよりも大きい場合は、変数のサイズまでの文字列のみがコピーされます。 ただし、最初は、NULL バイトが読み取られるまで文字列全体が一時的な文字列バッファー領域にコピーされます。 関数のユーザーは、 ProbeVue セッションを停止させる一時ストリング・バッファー域のオーバーフローを避けるために、カーネル・アドレスが NULL 終了ストリングを指すように注意する必要があります。

カーネル・メモリーから読み取られる文字列の最大長は、len パラメーターに負でない値を指定することで修正できます。 この場合は、NULL バイトが読み取られるまで、または、指定されたバイト数が読み取られるまでコピーは続行します。 この機能により、カーネル・メモリ内の長い文字列をより安全にコピーすることができます。コピーは 'lenパラメータの値によって制限され、ProbeVue の内部一時文字列バッファがオーバーフローすることはありません。

この関数の実行中に例外が発生した場合 (例えば、不正なカーネル・アドレスが関数に渡された場合)、 ProbeVue セッションは打ち切られ、エラー・メッセージが出されます。

addr

カーネル・スペース・データのアドレスを指定します。

len

コピーするカーネル・データのバイト数を指定します。 値 -1 は、カーネル・データが「C」文字列として処理され、ヌル・バイト ('¥0' 文字) が読み取られるまでコピーが続行することを示します。 len パラメーターの値として -1 を指定する場合は注意が必要です。

int get_location_point ( );

get_location_point 関数は、現在のプローブ・ロケーション・ポイントを、エンクロージング型関数のエントリー・ポイントからのオフセットで戻します。 具体的には、プローブ・ポイントが関数のエントリー・ポイントにある場合は FUNCTION_ENTRY またはゼロを戻し、終了ポイントにある場合は FUNCTION_EXIT または -1 を戻します。それ以外の場合は、実アドレスのオフセットを戻します。

次のスクリプトの例では、get_location_point 関数を使用しています。

@@syscall:$1:read:entry, @@syscall:$1:read:exit
	{
		probev_timestamp_t ts1, ts2;
		int diff;

		if (get_location_point() == FUNCTION_ENTRY) 
			ts1 = timestamp();
		else if (get_location_point() == FUNCTION_EXIT) {
			ts2 = timestamp();
			diff = diff_time(ts1, ts2, MICROSECONDS);
			printf("Time for read system call = %d\n", diff);
		}
	}

この関数は、間隔プローブ・マネージャーから呼び出された場合はサポートされません。

get_location_point 関数はパラメーターを取りません。

String get_probe ( );

get_probe 関数は、現在のプローブ・ポイント指定の内部表記を戻します。 プローブ・ポイントは、内部で保存された場合、先頭の @@ 接頭部またはプロセス ID (ある場合) が指定されません。

次のスクリプトの例では、get_probe 関数を使用しています。

#cat get_probe.e 
	@@uft:312678:*:run_prog:entry
	{
		printf("function '%s' probe '%s'\n", get_function(), get_probe());
	}

	#probevue get_probe.e
	function 'run_prog' probe 'uft:*:*:run_prog:entry'

get_probe 関数はパラメーターを取りません。

stktrace_t get_stktrace(int level); 

get_stktrace 関数は現行スレッドのスタック・トレースを返します。 このスタック・トレースは stktrace_t 型変数に保管されるか、ProbeVue 組み込み printf 関数で %t 指定子または %T 指定子を使用するときには表示されます。 level パラメーターは、スタック・トレースが表示される最大のレベル数を示します。 printf 関数内で使用される get_stktrace 関数の動作は、stktrace 組み込み関数に似ています。 ただし、実行中のスレッドに対して %t 指定子が使用された場合にシンボルとアドレスが表示され、それ以外の場合はロウ・アドレスが表示されるということが唯一異なります。 また、すべてのマシン状態間を移動することによって、CPU スタック全体を表示します。

次のスクリプトは、get_stktrace 関数の使用例を示したものです。

t1 = get_stktrace(3)                // Returns the current stack trace & stores in stktrace_t 
                                   // type variable t1.
printf('%t\n', get_stktrace(4));  // Prints the current stack trace up to level 4.                                                          
                                 // Prints symbol with addresses.

printf(“%T\n”, get_stktrace(4));  // Prints the current stack trace up to level 4
                                  // Prints raw addresses.

int get_ubytes(void *src, char *dest, int len); 

get_ubytes 関数は、 len バイト数のデータをユーザー・メモリーから Vue スクリプト変数に読み込みます。 この変数のタイプは、文字ポインターにすることができます。 コピーされるデータの長さは、この関数に渡される len パラメーター、または宛先 Vue 変数のサイズと等しくなります。 len の値が宛先の Vue 変数のサイズより大きい場合、コピーされるデータの長さは宛先変数のサイズと等しくなります。 ユーザー・スペース内のデータは、式で使用したり、 Vue 関数にパラメーターとして渡したりする前に、 Vue 変数にコピーする必要があります。

get_ubytes 関数は、正常にコピーされた合計バイト数を返します。失敗した場合は -1 を返します。 関数実行中に例外が発生した場合、例えば、不正なユーザアドレスが関数に渡された場合、ProbeVueセッションはエラーメッセージとともに終了します。

int get_kbytes(void *src, char *dest, int len);

get_kdata 関数は、カーネル・メモリーから len バイト数のデータを Vue スクリプト変数に読み込みます。 この変数のタイプは、文字ポインターにすることができます。 コピーされるデータの長さは、この関数に渡される len パラメーター、または宛先 Vue 変数のサイズと等しくなります。 len の値が宛先の Vue 変数のサイズより大きい場合、コピーされるデータの長さは宛先変数のサイズと等しくなります。 ユーザー・スペース内のデータは、式で使用したり、 Vue 関数にパラメーターとして渡したりする前に、 Vue 変数にコピーする必要があります。

get_kbytes 関数は、正常にコピーされた合計バイト数を返します。失敗した場合は -1 を返します。 関数実行中に例外が発生した場合、例えば不正なカーネルアドレスが関数に渡された場合、ProbeVueセッションはエラーメッセージとともに終了します。

String get_userstring( char * addr, int len );

get_userstring 関数は、ユーザー・メモリー内のデータを String 型の変数に読み取ります。

ユーザー・スペース内のデータは、式で使用したり、 Vue 関数にパラメーターとして渡したりする前にコピーする必要があります。 get_userstring 関数のターゲットは、通常、String 型の変数です。 len パラメーターに -1 の値を指定すると、NULL バイトが読み取られるまでユーザー・メモリーからデータがコピーされます (NULL バイトは C 言語でテキスト・ストリングを終了するために使用されます)。 文字列の長さがターゲットの String 変数の宣言されたサイズよりも大きい場合は、変数のサイズまでの文字列のみがコピーされます。 ただし、最初は、NULL バイトが読み取られるまで文字列全体を一時的な文字列バッファー領域にコピーしなければなりません。 ProbeVueセッションを中断させる原因となる一時的な文字列バッファ領域のオーバーフローを避けるため、この関数を使用するユーザは、ユーザアドレスがNULL終端文字列を指すように注意する必要があります。

この関数は、ユーザー・スペース・プローブ (uft プローブ型など) または syscall プローブ・マネージャーで指定されるプローブで許可されます。 データのコピー中にページ・フォールトが発生した場合は、コピー操作が終了し、String 変数には正常にコピーされたデータのみが含まれます。 この関数の発行中に例外が発生した場合 (例えば、不正なユーザー・アドレスが関数に渡された場合)、 ProbeVue セッションは打ち切られ、エラー・メッセージが出されます。

ProbeVue 動的トレース機能 には、 get_userstring 関数を使用するスクリプトの例があります。

/* File: string2int.e
 *
 * Reads an integer passed in a pointer using get_userstring()
 *
 */
int get_file_sizep(int *fd);

@@BEGIN
{
	
	int i;
}

@@uft:$1:*:get_file_sizep:entry
{
	i = *(int *)(get_userstring(__arg1, 4));

	printf("fd = %d\n", i);
}

group_output_start() 関数は、節の出力をグループ化します。 group_output_start() 関数が呼び出された後、group_output_end() 関数が呼び出される前に、節の VUE ステートメントによって生成された出力メッセージは、他の CPU で同時に実行されていると考えられる節から生成されたメッセージによってインターリーブされることはありません。

void group_output_end();

節の出力グループ化を停止します。 それ以降の VUE ステートメントがあれば、それらのステートメントはグループ化された出力を持たないため、他の CPU で同時に実行されている節による出力メッセージによってインターリーブされる場合があります。 group_output_end() 関数の呼び出しは、その前に group_output_start() 呼び出しがなければなりません。 group_output_start() 関数が呼び出された後、group_output_end() 関数の呼び出しはオプションです。 group_output_end() 関数が呼び出されない場合は、出力は節の終了までグループ化されます。

List list ( );

list 関数は、リスト・データ型のコンストラクター関数です。 この関数は空リストを戻し、ターゲットをリスト・データ型として自動宣言します。 変数をリスト・データ型として明示的に宣言する方法はありません。 リスト変数は、常にグローバル・クラスの変数として作成されます。

list 関数はどの節からでも呼び出し可能です。 list 関数を呼び出すときに既存のリスト名を指定した場合は、その既存のリストがクリアされます。

リスト変数は整数型の値を収集するために使用できます。 リストに格納された値は、long long (または 64 ビット整数) データ型に自動的にプロモートされます。

次のスクリプトの例では、list 関数を使用しています。 各引数を二重引用符で囲む sprobevue シェル・プログラムが Vue スクリプトを呼び出すことを想定しています。

/* File: list.e
 * 
 * Collect execution time for read system call statistics
 *
 * Usage: sprobevue list.e <-s|-d>
 *
 *	Pass -s for summary and -d for detailed information
 */

int read(int fd, void *buf, int n);

@@BEGIN
{
	String s[10];
	int detail;
	times = list();		/* declare and create a list */

	/* Check for parameters */
	s = $1;
	if (s == "-d") 
		detail = 1;
	else if (s == "-s")
		detail = 0;
	else {
		printf("Usage: sprobevue list.e <-s|-d>\n");
		exit();
	}
}

@@syscall:*:read:entry
{
	/*
	 * Save entry time in a thread-local to ensure that 
	 * in the read:exit probe point we can access our thread's value for 
	 * entry timestamp. If we use a global, then the variable can be
	 * overlaid by the next thread to enter read and this can give
	 * wrong values when we try to find the difference at read:exit
	 * time since we use this later value instead of the original value.
	 */

	__thread probev_timestamp_t t1;
	t1 = timestamp();
}

@@syscall:*:read:exit
	when (thread:t1 != 0)
{
	__auto t2;
	__auto long difft;

	/* Get exit time */
	t2 = timestamp();
	difft = diff_time(t1, t2, MICROSECONDS);

	/* Append read time to list */
	append(times, difft);

	/* print detail data if "-d" was passed to script */
	if (detail)
		printf("%s (%ld) read time = %d micros\n", __pname, __pid, difft);
}

@@interval:*:clock:10000
{
	/* Print statistics every 10 seconds */
	printf("Read calls so far = %d, total time = %d, max time = %d, " +
	       "min = %d, avg = %d\n",
			count(times),
			sum(times),
			max(times),
			min(times),
			avg(times));
}

list 関数はパラメーターを取りません。

void lquantize( aso-name ,int num-of-entries, int flags, sort_key_ind)

この関数は、連想配列の値の対数値に基づいて、連想配列のエントリーをグラフィカル形式で出力します。 特定のキー・セットを持つエレメントだけを出力する場合は、連想配列変数名に加えて、それらのキーを最初の引数に指定することができます。 特定のディメンション・キーだけを制限して、他のキーの任意の値を許可するには、ANY キーワードを使用できます。 例については、print() 関数のセクションを参照してください。

最初のパラメーターは必須で、その他のパラメーターはすべてオプションです。 オプション・パラメーターを指定しない場合は、デフォルトの出力オプションが使用されます。

ASO 名

出力する連想配列変数の名前。 大括弧の中にすべてのディメンションのキーを指定することもできます。 キー・ディメンションの中のすべてのキーに一致させるには、ANY キーワードを使用できます。

項目数 (num-of-entries)

出力するエントリー数を指定します。 このパラメーターはオプションです。 すべてのエントリーを表示するには、0 を指定します。 値が指定されていない場合は、セッションのデフォルトの出力オプションが使用されます。 負の値は 0 と等価です。

flags

sort-type、sort-by、および list-value のフラグを指定します。 このパラメーターはオプションです。 フラグ sort-type、sort-by、および list-value については、「連想配列タイプ」セクションで説明しています。 0 を指定すると、セッションのデフォルトの出力オプションが使用されます。

ソート・キーの種類

出力のソートに使用するキーの索引 (キー・ディメンション)。 -1 を指定すると、最初のキーがソートに使用されます。 最初のキーがソート可能なタイプでない場合は、出力はソートされません。

long long max ( List listvar );

max 関数は、listvar パラメーターで指定されたリスト変数に追加されたすべてのエレメントの最大を戻します。

リスト・データ・タイプについて詳しくは、 ProbeVue 動的トレース機能 のトピックを参照してください。 前セクションの listvarでは、max 関数を使用するスクリプト例を記載しています。

listvar: list 型の変数を指定します。

long long min ( List listvar );

min 関数は、listvar パラメーターで指定されたリスト変数に追加されたすべてのエレメントの最小を戻します。

前セクションの listvar では、min 関数を使用するスクリプト例を記載しています。

listvar: list 型の変数を指定します。

void print_args(); 

print_args 関数は、関数名と、その後に続く、丸括弧で囲んだコンマ区切りの関数引数を表示します。 引数値は、関数のトレースバック・テーブルにある引数タイプ情報に基づいて表示されます。 このルーチンは、uft/uftxlc++ プローブと syscall/syscallx プローブのエントリー・プローブで許可されます。 これは、プローブ・ロケーションが正規表現として指定されているプローブで有用です。

print_args 関数はパラメーターをとりません。

void print ( aso-name , int num-of-entires , int flags, int sort_key_ind );

この関数は、変数 aso-name で指定した連想配列のエレメントを出力します。 特定のキー・セットを持つエレメントのみを出力する場合は、連想配列変数名と共に最初の引数にそれらのキーを指定することができます。 特定のディメンション・キーのみを制限して、他のすべてのキーの任意の値を許可するには、ANY キーワードを使用します。

print(aso_var[0][ANY][ANY]);    // print all elements having first key as 0 (other keys can be anything)
print(aso_var[ANY][ANY][ANY]);  // print all; equivalent to print(aso_var);

最初のパラメーターは必須で、その他のパラメーターはすべてオプションです。 オプション・パラメーターを指定しない場合は、デフォルトの出力オプションが使用されます。

aso1[0][“a”][2.5] = 100;
aso1[1][“b”][3.5] = 101;
print(aso1);
The output from previous print() function follows:
[key1               |    key2                |    key3]               |    value
0                   |    a                   |    2.5000000           |    100
1                   |    b                   |    3.5000000           |    101

aso2[0][get_stktrace(-1)] = “abc”;
print(aso2);

The output from print() function above will be similar to:
[key1               |    key2]                                   |    value
0
                    |
                         0x100001b8
                         0x10003328
                         0x1000166c
                         0x10000c30
                         .read+0x288
                         sc_entry_etrc_point+0x4
                         .kread+0x0
                                                                 |
                                                                      abc

ASO 名

出力する連想配列変数の名前。 大括弧の中にすべてのディメンションのキーを指定することもできます。 キー・ディメンションの中のすべてのキーに一致させるには、ANY キーワードを使用できます。

エントリー数 (num-of-entires)

出力するエントリー数を指定します。 このパラメーターはオプションです。 すべてのエントリーを表示するには、0 を指定します。 値が指定されていない場合は、セッションのデフォルトの出力オプションが使用されます。 負の値は 0 と等価です。

flags

sort-type、sort-by、および list-value のフラグを指定します。 このパラメーターはオプションです。 フラグ sort-type、sort-by、および list-value については、「連想配列タイプ」セクションで説明しています。 0 を指定すると、セッションのデフォルトの出力オプションが使用されます。

ソート・キーの種類

キー索引 (キー・ディメンション) は、出力のソートに使用されます。 -1 を指定すると、最初のキーがソートに使用されます。 最初のキーがソート可能なタイプでない場合は、出力はソートされません。

void printf ( String format[ , data, ... ]);

printf 関数は、format パラメーターに応じて、data パラメーターの値を変換、フォーマット、およびトレース・バッファーにコピーします。 構文が示すように、引数の可変リストが data パラメーターとして printf 関数に渡されます。 Vue は、 %p 変換指定子を除き、C ライブラリーによって提供される printf サブルーチンによってサポートされるすべての変換指定子をサポートします。

C ライブラリーの printf() 指定子以外に、Vue 言語は、もう 2 つの指定子 %A および %W をサポートします。

%A

probev_timestamp_t 「t」をデフォルトの日付形式で出力します。 この形式は、set_date_format() 関数を使用して変更することができます。

%W

probevue セッションの開始を基準として、 probev_timestamp_t の「t」を秒およびマイクロ秒単位で出力します。

%p

指定された path_t 値の絶対ファイル・パスに対応するストリングを出力します。

%M

指定された mac_addr_t 値の MAC アドレスを出力します。

%I

指定された ip_addr_t 値の ipv4 アドレスの IP アドレスを小数点付き 10 進数形式で、 IPV6 アドレスの IP アドレスを小数点付き 16 進数形式で出力します。

%H

指定された ip_addr_t 値のストリング、小数点付き 10 進数、または 16 進数形式でホスト名を出力します。

printf 関数を使用して list 型の変数を印刷することはできません。 ただし、string 型の変数は、%s 変換指定子を使用して印刷できます。 probev_timestamp_t 型の変数は、%lld 指定子または %16llx 指定子を使用して数値形式で印刷されます。 probev_timestamp_t は、%A 指定子または %W 指定子を使用して日付形式で印刷されます。

次のスクリプトの例では、printf 関数を使用しています。

@@BEGIN
{
	String s[128];
	int i;
	float f;
	f = 2.3;

	s = "Test: %d, float = %f\n";
	i = 44;

	printf(s, i, f);

	s = "Note:";
	printf("%s Value of i (left justified) = %-12d and right-justified = %12d\n",
				s, i, i);

	printf("With a long format string that may span multiple lines, you " +
			"can use the '+' operator to concatenate the strings " +
			"in multiple lines into a single string: 0x%08x\n", i); 

	exit();
}

format

トレース・バッファーに変更なしで直接コピーされるプレーン文字を含む文字列、および data パラメーターのフォーマット方法を示す 1 つ以上の変換指定子。

data

format パラメーターの変換指定子に対応するゼロ個以上の引数を指定します。

void ptree ( int depth );

ptree 関数は、プローブしているプロセスのプロセス・ツリーを表示します。 この関数は、親階層と子階層の両方を表示します。 パラメーターとして渡される深さは、表示が必要な子プロセスの深さを制御するのに役立ちます。 この関数は、BEGIN プローブ、END プローブ、または systrace プローブでは使用できません。 また、この関数は、PID が指定されている場合にのみ、間隔プローブで使用できます。

void quantize ( aso-name, int num-of-entries, int flags, int sort_key_ind)

この関数は、連想配列の値の線形値に基づいて、連想配列のエントリーをグラフィカル形式で表示します。 特定のキー・セットを持つエレメントのみを出力する場合は、連想配列変数名と共に最初の引数でそれらのキーを使用することができます。 特定のディメンション・キーのみを制限して、残りのディメンション内のすべてのキーを許可するには、ANY キーワードを使用できます。

最初のパラメーターを除いて、その他はオプション・パラメーターです。 これらのオプション・パラメーターを指定しない場合は、デフォルトの出力オプションが使用されます。

ASO 名

出力する連想配列変数の名前。 大括弧の中にすべてのディメンションのキーを指定することもできます。 キー・ディメンションの中のすべてのキーに一致させるには、ANY キーワードを使用できます。

項目数 (num-of-entries)

出力するエントリー数を指定します。 このパラメーターはオプションです。 すべてのエントリーを表示するには、0 を指定します。 値が指定されていない場合は、セッションのデフォルトの出力オプションが使用されます。 負の値は 0 と等価です。

flags

sort-type、sort-by、および list-value のフラグを指定します。 このパラメーターはオプションです。 フラグ sort-type、sort-by、および list-value については、「連想配列タイプ」セクションで説明しています。 0 を指定すると、セッションのデフォルトの出力オプションが使用されます。

ソート・キーの種類

出力のソートに使用するキーの索引 (キー・ディメンション)。 -1 を指定すると、最初のキーがソートに使用されます。 最初のキーがソート可能なタイプでない場合は、出力はソートされません。

void qrange(aso[key], range_t range_data, int value);
void qrange(aso[key], range_t range_data, String value);

qrange ルーチンは、整数と文字列の両方の範囲型のスロット番号を検出できます。 範囲型が整数型の場合、3 番目の引数型は整数でなければなりません。また範囲データ型が文字列の場合、3 番目の引数は文字列型でなければなりません。 qrange ルーチンは渡された値が入るスロット番号を検出します。 そのスロット番号のカウントは、連想配列内に値として保管されている範囲型について増分されます。

aso[key]

指定されたキーを持つ連想配列。

range_data

range_t データ型。

値

value は、整数型または文字列型のいずれかです。

int round_trip_time(int sock_fd);

round_trip_time 関数は、特定のソケット・ディスクリプターの、平滑化された往復時間 (srtt) を取得します。 ストリーム・ソケット・ディスクリプターの場合は、有効な往復値を提供し、無効または非ストリーム・ソケット・ディスクリプターの場合は、平滑往復時間値として -1 を戻します。 この関数は、uft プローブ・マネージャーおよび syscall プローブ・マネージャーでのみ使用可能です。

fd

ファイル・ディスクリプターまたはソケット・ディスクリプターの値。

void set_aso_print_options( int num-of-entries, int flags);

set_aso_print_options() 関数は、連想配列のデフォルトの出力オプションを変更します。 ユーザーが指定できる印刷オプションとその初期値は、「共用の配列タイプ」セクションにリストされています。 この関数は BEGIN プローブでのみ使用できます。

項目数 (num-of-entries)

最初の 'n' 対のキーまたは値を出力することを指定します。 0 の場合、すべてのエントリーが表示されます。

flags

sort-type、 sort-by、 list-value 、および stack-raw フラグを指定します。 これらのフラグについては、「共用の配列型」セクションで説明しています。 以下のパラメーターはオプションです。

void set_range(range_t range_data, LINEAR, int min, int max, int step);
void set_range(range_t range_data, POWER, 2);

set_range には 2 つの異なるバリアントがあります。 範囲データを線形範囲として初期化する場合は、フラグ LINEAR と、min、max、および step が引数として渡されます。 Power 範囲を初期化する場合、2 つのフラグ POWER が引数として渡されます。 このルーチンは、渡された引数に基づいて、範囲型を線形または累乗として初期化します。 線形範囲型のデータは、渡された値 min、max、および step で初期化されます。累乗範囲型のデータは累乗値を 2 として初期化されます。

パラメーター (線形範囲型の場合):

range_data

range_t データ型。

LINEAR

range_data 値の分布が線形であることを示す整数定数フラグ。

分

range_data の下限を指示します。

max

range_data の上限を指示します。

step

range_data の行ごとに、指定された値の範囲のサイズを指示します。 min、max、および step の型は必ず整数 (int、short、long、long、long) でなければなりません。 それ以外の型は使用できません。

パラメーター (累乗範囲型の場合):

range_data

range_t データ型。

電源

値の分布が POWER 分布であることを示す整数定数フラグ。

累乗の値を示す定数。 現時点では 2 の累乗のみがサポートされます。

void set_date_format(String s);

日付形式を更新します。

この関数は、日付形式に対して C ライブラリーの strftime() によってサポートされるすべての変換指定子をサポートします。 strftime() によってサポートされない指定子はいずれも無効であり、デフォルトの形式が使用されます。

デフォルト形式

MM:DD:YYYY hh:mm:ss TZ

MM

10 進数としての月 (01 から 12)。

DD

10 進数としての日付 (01 から 31)。

YYYY

10 進数としての年 (例えば、1989)。

hh

10 進数としての 24 時の刻時 (00 から 23)。

mm

10 進数としての分 (00 から 59)。

ss

10 進数としての秒 (00 から 59)。

TZ

判別できる場合はタイムゾーン名 (例えば、CDT)。

void sockfd_netinfo(int sock_fd,  net_info_t ninfo);

sockfd_netinfo 関数は、入力ソケット・ディスクリプターのローカル IP アドレス、リモート IP アドレス、ローカル・ポート番号、およびリモート・ポート番号の情報を取得します。 この関数は、有効なソケット・ディスクリプターの有効なローカルおよびリモートのポート番号および IP アドレスの情報を取得します。 無効なディスクリプターの場合、またはディスクリプターがソケット・タイプでない場合、0 を取得します。

fd

ファイル・ディスクリプターまたはソケット・ディスクリプターの値。

ninfo

特定のファイル・ディスクリプターのネットワークの 4 タプル (ローカルおよびリモートの IP アドレスとポート番号) 情報がコピーされる、スクリプト変数 net_info_t を指定します。

void start_tentative( String bufID );
void end_tentative( String bufID );

これらの関数は、 Vue 節内の一時トレース・セクションの開始と終了を示します。 一時トレース・セクションの中で囲まれた、トレース出力関数で生成されたトレース・データは、commit_tentative または discard_tentative 関数がこのデータをコミットまたは廃棄するために呼び出されるまで、一時的に保存されます。 end_tentative 関数はオプションです。この関数が指定されていない場合は、Vue 節の終了が一時トレース・セクションの終了を示すように暗黙的に想定されます。

生成された一時トレース・データは、bufID パラメーターで識別されます。このパラメーターは文字列定数またはリテラルであり、変数ではありません。 一時トレース・データは複数の異なる ID で同時に収集でき、それぞれ別々のブロックとしてコミットまたは廃棄できます。 ProbeVue は、同じ動的トレース・セッションで最大 16 個の一時トレース・バッファーをサポートするため、 Vue スクリプトでは最大 16 個の異なるトレース ID を使用できます。 1 つの Vue 節には、複数の異なる ID をもつ複数の一時トレース・セクションを含めることができます。

bufID

一時トレース・バッファー ID を示す文字列定数を指定します。

void stktrace ( int flags, int levels );

stktrace 関数は、現行のプローブ・ポイントにあるスタック・トレースを印刷します。 デフォルトでは、スタック・トレースは、2 レベルまでの呼び出しチェーン・アドレスのみでコンパクトに生成されます。 スタック・トレースのフォーマットと内容を変更するには、flags と levels パラメーターを使用できます。 ProbeVue はページアウトされたデータを読み取ることができないため、スタックへのアクセス時にページ不在が発生すると、スタック・トレースは切り捨てられます。

stktrace 関数は値を戻しません。

String strstr( String s1, String s2 ); 

strstr 関数は、s2 パラメーターで指定された文字列が s1 パラメーターで指定された文字列に最初に出現したのを検出し、このロケーションから開始する s1 パラメーターの文字を含む新しい文字列を戻します。 この操作では、s1 パラメーターまたは s2 パラメーターのどちらも変更されません。 s2 パラメーターで指定された文字列が s1 パラメーターに一度も出現しなかった場合、この関数は空文字列を戻します。

long long sum ( List listvar );

リスト変数

list 型の変数を指定します。

probev_timestamp_t timestamp( );

timestamp 関数は、probev_timestamp_t 抽象データ型の現在のタイム・スタンプを戻します。 抽象ではありますが、値には次の属性があります。

• 複数の異なる CPU から同時に呼び出された場合は、等しい値または近い値を戻します。
• timestamp 関数が 2 回呼び出され、2 回目の呼び出しが時間的に後で発生したと構造的に保証される場合は、2 回目の呼び出しに対して戻された値が、最初の呼び出しで戻された値より大きいか等しくなります (2 回の呼び出しの間にシステムがリブートされなかった場合)。

2 つの異なるシステムで timestamp 関数により戻された値には関連性はありません。 コンパイラーでは戻り値を 64 ビット整数として扱うように指示されますが、これを行うと互換性の問題が発生する可能性があります。

typedef long long time_t;
	__kernel time_t lbolt;   	/* number of ticks since last boot     */
	__kernel time_t time;    	/* memory mapped time in secs since epoch  */

void trace ( data );

trace 関数はパラメーターを 1 つ取ります。このパラメーターは変数でなければなりません。 trace 関数は式を受け入れません。

trace 関数は、渡された引数の値をトレース・バッファーにコピーします。 引数には任意のデータ型を指定でき、トレース・バッファーにコピーされるデータのサイズはその元々のサイズに基づいています。 このため、整数引数の場合は 4 バイトがコピーされ、ポインターの場合は 4 または 8 バイトがコピーされ (実行が 32 ビット・モードか 64 ビット・モードのどちらかにより異なる)、struct 型の引数の場合は構造体のサイズがコピーされます。 String 型の変数の場合は、コピーされるバイト数は宣言された文字列の長さです (この長さは変数にある文字列の長さとは異なります)。 probev_timestamp_t 型の変数は少なくとも 8 バイト長です。

データ

トレース・バッファーにコピーするデータ引数。