posix_trace_timedgetnext_event サブルーチン

目的

トレース・イベントを取得します。

構文

#include <sys/types.h>
#include <trace.h>

int posix_trace_timedgetnext_event
(trid, event, data, num_bytes, data_len, unavailable, abs_timeout)
trace_id_t trid;
struct posix_trace_event_info *restrict event;
void *restrict data;
size_t num_bytes;
size_t *restrict data_len;
int *restrict unavailable;
const struct timespec *restrict abs_timeout;

説明

posix_trace_timedgetnext_event サブルーチンは、 posix_trace_getnext_event サブルーチンのように、ログなしでアクティブ・トレース・ストリームから別のトレース・イベントを取得しようとします。 ただし、トレース・ストリームから使用可能なトレース・イベントがない場合、パラメーター abs_timeout によって指定されたタイムアウトの有効期限が切れると、暗黙の待機が終了し、関数はエラー [ETIMEDOUT] を返します。

タイムアウトは、 abs_timeout で指定された絶対時間が経過するか、呼び出し時に既に経過している場合に期限切れになります。 abs_timeout によって指定される絶対時間は、タイムアウトが基づくクロックによって測定されます (つまり、そのクロックの値が abs_timeout以上の場合)。

タイムアウトは、CLOCK_REALTIME クロックに基づいています。 タイムアウトの解決は、CLOCK_REALTIME の解決になります。 timespec データ・タイプは、 time.h ヘッダー・ファイルで定義されます。

トレース・イベントがトレース・ストリームからすぐに使用可能な場合、関数はタイムアウトで失敗することはありません。 トレース・イベントがトレース・ストリームからすぐに使用可能な場合、 abs_timeout パラメーターの妥当性は検査されません。

事前記録されたトレース・ストリームに対するこのサブルーチンの動作は指定されません。

num_bytes パラメーターは、 data パラメーターが指すバッファーのサイズと等しくなります。 data_len パラメーターは、転送されたばかりのデータ・レコードの長さ (バイト単位) をアプリケーションに報告します。 num_bytes が、 event パラメーターが指すトレース・イベントに関連付けられたデータのサイズ以上である場合は、記録されたすべてのデータが転送されます。 この場合、トレース・イベント構造体の切り捨て状況メンバーは、POSIX_TRACE_NOT_TRUNCATED (トレース・イベント・データがトレース中に切り捨てられずに記録された場合) または POSIX_TRACE_TRUNCATED_RECORD (トレース・イベント・データが記録されたときに切り捨てられた場合) のいずれかです。 num_bytes パラメーターが、記録されたトレース・イベント・データの長さより短い場合、転送されるデータは num_bytes パラメーターの長さに切り捨てられます。 data_len が指す変数に保管される値は num_bytesになり、 event 構造体パラメーターの切り捨て状況メンバーはUNPOSIX_TRACE_に設定されます。posix_trace_event_infotrace.h) に定義されている構造体。

トレース・イベントのレポートは、記録された最も古いトレース・イベントから順に作成されます。 トレース・イベントは、生成された順序で報告されます。これは、相互に非常に近い場所で発生するトレース・イベントの順序が不明となる、実装で定義された時間解決までです。 報告された後は、アクティブなトレース・ストリームからトレース・イベントを再度報告することはできません。 ログのないアクティブなトレース・ストリームからトレース・イベントが報告されると、トレース・ストリームは、そのトレース・イベントに関連したリソースを将来生成されるトレース・イベントの記録に使用できるようにします。

パラメーター

戻り値

正常終了すると、 posix_trace_timedgetnext_event サブルーチンは値 0 を戻します。 それ以外の場合は、対応するエラー番号を返します。

正常に実行されると、 posix_trace_timedgetnext_event サブルーチンに以下が保管されます。

• event が指すオブジェクト内の記録されたトレース・イベント
• data が指すオブジェクト内の、記録されたトレース・イベントに関連するトレース・イベント情報
• data_len が指すオブジェクト内のこのトレース・イベント情報の長さ
• unavailable が指すオブジェクトの値は 0 です。

エラー・コード

以下のエラー・コードが返された場合、 posix_trace_timedgetnext_event サブルーチンは失敗します。

ファイル

Files Reference のpthread.h、trace.h、types.h。