日本語 man コマンド類 (ja-man-1.1j_5) と日本語 man ドキュメント (ja-man-doc-5.4 (5.4-RELEASE 用) など) をインストールすると、以下のような man コマンド閲覧、キーワード検索が コンソールからできるようになります。
4.11-RELEASE-K, 5.4-RELEASE-K, 5.5-RELEASE-K, 6.0-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K, 12.1-RELEASE-K は、 プライベート版 (小金丸が編集してまとめたもの) ですが、 より多くの翻訳したファイルが含まれています。 (5.4-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K から 12.4-RELEASE-K, 13.0-RELEASE-K から 13.3-RELEASE-K, 14.0-RELEASE-K から 14.1-RELEASE-K は、全翻訳済み)
13.3-STABLE-K, 15.0-CURRENT-K は現在、作成中で日々更新されています。
Table of Contents
PTRACE(2) FreeBSD システムコールマニュアル PTRACE(2)
名称
ptrace -- プロセスのトレースとデバッグ
ライブラリ
標準 C ライブラリ (libc, -lc)
書式
#include <sys/types.h>
#include <sys/ptrace.h>
int
ptrace(int request, pid_t pid, caddr_t addr, int data);
解説
ptrace() システムコールは、トレースとデバッグ機能を提供します。それによっ
て、1 つのプロセス (トレースしているプロセス) は、別の (トレースされたプ
ロセス) を制御することができます。トレースしているプロセスは、最初にト
レースされたプロセスにアタッチしなければならず、次に、プロセスメモリとレ
ジスタ状態のアクセスと同様に、プロセスの実行を制御するために、一連の
ptrace() システムコールを発行します。トレースしているセッションの期間中
に、トレースされたプロセスは、トレースしているプロセスに変更されたその親
のプロセス ID (と、結果の振る舞い) で ``再び親と'' されます。一度に複数の
他のプロセスにアタッチするトレースしているプロセスを許可します。トレース
しているプロセスがその作業を完了したとき、トレースされたプロセスをデタッ
チしなければなりません。トレースしているプロセスが最初にアタッチされてい
たすべてのプロセスをデタッチせずに終了するなら、それらのプロセスは、kill
されます。
ほとんどの場合に、トレースされるプロセスは、正常に実行しますが、シグナル
(sigaction(2) を参照) を受信するとき、停止します。トレースしているプロセ
スは、wait(2) または SIGCHLD シグナルの配信を通してこれを通知することが期
待され、停止されたプロセスの状態を調べ、必要に応じて、終了するか、または
継続します。シグナルは、正常なプロセスシグナルであり、トレースされるプロ
セスの振る舞いの結果として、または kill(2) システムコールの使用として生成
されます。代わりに、それは、トレースしているプロセス、またはトレースされ
るプロセスのイベントによってステップ実行され、アタッチの結果としてトレー
スしている機能によって生成できます。トレースしているプロセスは、(SIGTRAP
のような) プロセスの振る舞いを観察するか、または適切であるなら、シグナル
をプロセスに転送するために、それを使用して、シグナルをインターセプトする
かを選択します。ptrace() システムコールは、すべてのこれが起こるメカニズム
です。
トレースされるプロセスは、トレースされるプロセスのイベントに対応して追加
のシグナルの停止を報告します。これらの追加のシグナルの停止は、SIGTRAP ま
たは SIGSTOP シグナルとして報告されます。トレースしているプロセスは、どの
イベントが SIGTRAP または SIGSTOP シグナルと関連するかを決定するために
PT_LWPINFO 要求を使用することができます。複数のイベントは、単一のシグナル
と関連されることに注意してください。例えば、PL_FLAG_BORN, PL_FLAG_FORKED
と PL_FLAG_EXEC フラグによって示されるイベントは、また、システムコールの
終了イベント (PL_FLAG_SCX) として報告されます。PTRACE_FORK を通して有効に
された新しい子プロセスのためのシグナルの停止は、SIGSTOP シグナルを報告し
ます。すべての他の追加のシグナルの停止は、SIGTRAP を使用します。
各トレースされるプロセスには、トレースしているイベントマスクがあります。
トレースされるプロセスのイベントは、対応しているフラグが、トレースしてい
るイベントマスクに設定されるなら、シグナルの停止のみを報告します。トレー
スしているイベントフラグの現在のセットは、次を含んでいます:
PTRACE_EXEC execve(2) の成功した呼び出しのための停止を報告します。
このイベントは、struct ptrace_lwpinfo の pl_flags メン
バの PL_FLAG_EXEC フラグによって示されます。
PTRACE_SCE 各システムコールのエントリで停止を報告します。このイベ
ントは、struct ptrace_lwpinfo の pl_flags メンバの
PL_FLAG_SCE フラグによって示されます。
PTRACE_SCX 各システムコールの終了で停止を報告します。このイベント
は、struct ptrace_lwpinfo の pl_flags メンバの
PL_FLAG_SCX フラグによって示されます。
PTRACE_SYSCALL システムコールのエントリと終了の両方のための停止を報告
します。
PTRACE_FORK このイベントフラグは、トレースされるプロセスの新しい子
プロセスのためのトレースを制御します。
このイベントフラグが有効にされるとき、新しい子プロセス
は、トレースすることを有効にし、それらの最初の命令を実
行する前に停止します。新しい子プロセスは、struct
ptrace_lwpinfo の pl_flags メンバの PL_FLAG_CHILD フラ
グを含めます。トレースされるプロセスは、PL_FLAG_FORKED
フラグを含む停止を報告します。また、新しい子プロセスの
プロセス ID は、struct ptrace_lwpinfo の pl_child_pid
メンバに存在します。新しい子プロセスが vfork(2) によっ
て作成されたなら、トレースされるプロセスの停止は、
PL_FLAG_VFORKED フラグも含みます。新しい子プロセスは、
デフォルトのトレースしているイベントマスクでアタッチさ
れることに注意してください。それらは、トレースされるプ
ロセスのイベントマスクを継承しません。
このイベントフラグが有効にされないとき、新しい子プロセ
スは、有効にされたトレースなしで実行します。
PTRACE_LWP このイベントフラグは、LWP (kernel thread) (カーネルス
レッド) の作成と破壊のトレースを制御します。このイベン
トが有効にされるとき、新しい LWP は、それらの最初の命
令を実行する前に設定される PL_FLAG_BORN でイベントを停
止して報告し、LWP を終了することは、それらの終了を完了
する前に設定される PL_FLAG_EXITED でイベントを停止して
報告します。
新しいプロセスがそれらの初期のスレッドの作成のためのイ
ベントを報告せず、終了プロセスは、最後のスレッドの終了
のためのイベントを報告しないことに注意してください。
PTRACE_VFORK vfork(2) の後に親プロセスが再開するとき、停止イベント
を報告します。
トレースされるプロセスのスレッドが vfork(2) によって新
しい供プロセスを作成するとき、PL_FLAG_FORKED と
PL_FLAG_SCX 報告する停止は、子プロセスが作成された直後
に起こりますが、スレッドが共有しているプロセスのメモリ
を停止するために子プロセスをウェートする前です。デバッ
ガが新しい子プロセスをトレースしていないなら、それは、
ブレークポイントが、新しい子プロセスからデタッチする前
に、共有されたプロセスのメモリで有効にされないことを保
証しなければなりません。これは、ブレークポイントがいず
れかの親プロセスで有効にされないことを意味しています。
PTRACE_VFORK フラグは、新しい子プロセスが、親プロセス
のプロセスのメモリを共有するのを停止するとき、示す新し
い停止を有効にします。デバッガは、親プロセスにブレーク
ポイントを再挿入することができ、このイベントに応答でそ
れを再開することができます。このイベントは、
PL_FLAG_VFORK_DONE フラグを設定することによって示され
ます。
デフォルトのトレースしているイベントマスクは、PT_ATTACH, PT_TRACE_ME また
は PTRACE_FORK によってプロセスにアタッチするとき、PTRACE_EXEC イベントだ
けを含みます。すべての他のイベントフラグは、無効にされます。
request 引数は、どのような操作が実行されているかを指定します。引数の残り
の意味は、操作に依存しますが、下記に注意される 1 つの特別な場合を除いて、
すべての ptrace() 呼び出しは、トレースしているプロセスによって行われ、pid
引数は、トレースされるプロセスまたは対応しているスレッド ID のプロセス ID
を指定します。request 引数は、次を指定できます:
PT_TRACE_ME この要求は、トレースされたプロセスによって使用され
る唯一のものです。それは、プロセスが、その親によっ
てトレースされることを期待すると宣言します。すべて
の他の引数は、無視されます。(親プロセスが、子プロセ
スをトレースすることを期待しないなら、それは、おそ
らく、結果によってかなり混同されます。いったんト
レースされたプロセスが停止すると、それは、ptrace()
を経ることを除いて継続することができません。) プロ
セスが、この要求と execve(2) を呼び出し、または
(execv(3) のような) それで、構築されたルーチンのい
ずれかを使用するとき、それは、新しいイメージの最初
の命令を実行する前に停止します。また、実行されてい
る実行形式であらゆる setuid または setgid ビットが
無視されます。子プロセスが vfork(2) システムコール
または指定された RFMEM フラグを付けた rfork(2) 呼び
出しによって作成されるなら、デバッグイベントは、
execve(2) が実行された後だけ、親プロセスに報告され
ます。
PT_READ_I, PT_READ_D これらの要求は、トレースされるプロセスのアドレス空
間から単一の int のデータを読み込むます。伝統的に、
ptrace() は、なぜ、2 つの要求があるかの理由ですが、
命令とデータのための区別されたアドレス空間があるマ
シンに対して許可されていました。概念的に、PT_READ_I
は、命令空間から読み込み、PT_READ_D は、データ空間
から読み込みます。現在の FreeBSD の実装では、これら
の 2 つの要求は、完全に同一です。addr 引数は、読み
込みが行われることになっている (トレースされたプロ
セスの仮想アドレス空間の) アドレスを指定します。こ
のアドレスは、あらゆる整列制約を満たす必要はありま
せん。読み込む値は、ptrace() から返された値として返
されます。
PT_WRITE_I, PT_WRITE_D
これらの要求は、それらが読み込みではなく書き込むこ
とを除いて、PT_READ_I と PT_READ_D と同等です。data
引数は、書き込まれる値を提供します。
PT_IO この要求によって、トレースされたプロセスのアドレス
空間の任意の量のデータを読み込み書き込むすることが
できます。addr 引数は、次のように定義されている
struct ptrace_io_desc へのポインタを指定します:
struct ptrace_io_desc {
int piod_op; /* I/O 操作 */
void *piod_offs; /* 子オフセット */
void *piod_addr; /* 親オフセット */
size_t piod_len; /* 要求の長さ */
};
/*
* piod_op の操作
*/
#define PIOD_READ_D 1
/* データ空間から読み込む */
#define PIOD_WRITE_D 2
/* データ空間に書み込む */
#define PIOD_READ_I 3
/* 命令空間から読み込む */
#define PIOD_WRITE_I 4
/* 命令空間に書み込む */
data 引数は、無視されます。実際に読み込みまたは書き
込まれたバイトの数は、返り時に、piod_len に格納され
ます。
PT_CONTINUE トレースされるプロセスは、実行を継続します。addr 引
数は、実行が再開される場所を指定するアドレス (プロ
グラムカウンタのための新しい値)、または実行が中断し
たところからまた始めることを示す (caddr_t)1 です。
data 引数は、実行を再開するようにトレースされたプロ
セスに配信されるシグナル番号を与えるか、またはシグ
ナルを送られないなら、0 です。
PT_STEP トレースされたプロセスは、1 命令ごとに 1 ステップ実
行されます。addr 引数は、(caddr_t)1 が渡されるべき
です。data 引数は、実行を再開するようにトレースされ
たプロセスに配信されるシグナル番号を与えるか、また
はシグナルを送られないなら、0 です。
PT_KILL トレースされるプロセスは、あたかも PT_CONTINUE が、
配信されるシグナルとして与えられた SIGKILL で使用さ
れたかのように、終了します。
PT_ATTACH この要求によって、プロセスは、ほかの関係のないプロ
セスの制御を得ることができ、それをトレースすること
を始めます。トレースされるプロセスからなんの協力も
必要としません。この場合に、pid は、トレースされる
プロセスのプロセス ID を指定し、他の 2 回の引数は、
無視されます。この要求は、ターゲットプロセスに、ト
レースしているプロセスと同じ実 UID がなければなら
ず、それが、setuid または setgid の実行形式を実行し
てはならないことを必要とします。(トレースしているプ
ロセスが root として実行されているなら、これらの制
限は、適用されません。) トレースしているプロセス
は、新しくトレースされるプロセスが停止するのを調
べ、次に、あたかもそれが最初からずっとトレースされ
ていたかのように、制御します。
PT_DETACH この要求は、実行を続けるために代替の場所を指定する
ことを許可せず、それが成功した後に、トレースされる
プロセスが、もはやトレースされず、実行を正常に続け
ることを除いて、PT_CONTINUE に似ています。
PT_GETREGS この要求は、addr によって指された ``struct reg''
(<machine/reg.h> で定義される) に、トレースされるプ
ロセスのマシンのレジスタを読み込みます。
PT_SETREGS この要求は、PT_GETREGS の逆です。それは、addr に
よって指された ``struct reg'' (<machine/reg.h> で定
義される) からトレースされるプロセスのマシンのレジ
スタをロードします。
PT_GETFPREGS この要求は、addr によって指された ``struct fpreg''
(<machine/reg.h> で定義される) に、トレースされるプ
ロセスの浮動小数点レジスタを読み込みます。
PT_SETFPREGS この要求は、PT_GETFPREGS の逆です。それは、addr に
よって指された ``struct fpreg'' (<machine/reg.h> で
定義される) からトレースされるプロセスの浮動小数点
レジスタをロードします。
PT_GETDBREGS この要求は、addr によって指された ``struct dbreg''
(<machine/reg.h> で定義される) に、トレースされるプ
ロセスのデバッグレジスタを読み込みます。
PT_SETDBREGS この要求は、PT_GETDBREGS の逆です。それは、addr に
よって指された ``struct dbreg'' (<machine/reg.h> で
定義される) からトレースされるプロセスのデバッグレ
ジスタをロードします。
PT_LWPINFO この要求は、トレースされるプロセスを停止する、ライ
トウェート (light-weight) プロセスとしての知られて
いる、カーネルスレッドに関する情報を取得するために
使用することができます。addr 引数は、次のように定義
される struct ptrace_lwpinfo へのポインタを指定しま
す:
struct ptrace_lwpinfo {
lwpid_t pl_lwpid;
int pl_event;
int pl_flags;
sigset_t pl_sigmask;
sigset_t pl_siglist;
siginfo_t pl_siginfo;
char pl_tdname[MAXCOMLEN + 1];
pid_t pl_child_pid;
u_int pl_syscall_code;
u_int pl_syscall_narg;
};
data 引数は、呼び出し側に知られている構造体のサイズ
に設定されます。これによって、構造体は、より古いプ
ログラムに影響せずに大きくすることができます。
struct ptrace_lwpinfo のフィールドには、次の意味が
あります:
pl_lwpid
スレッドの LWP ID
pl_event
停止を引き起こしたイベント。現在定義された
イベントは、次の通りです:
PL_EVENT_NONE 与える理由なし
PL_EVENT_SIGNAL スレッドは、保留中
(pending) のシグナルの
ために停止しました
pl_flags
観測される停止に関する追加の詳細を指定する
フラグ。現在定義されたフラグは、次の通りで
す:
PL_FLAG_SCE
スレッドは、カーネルに入れられた直
後に、システムコールのエントリのた
めに停止しました。デバッガは、現在
のプロセスの ABI にしたがってメモリ
とレジスタに格納される syscall 引数
を調べて、必要なら、それらを変更し
ます。
PL_FLAG_SCX
スレッドは、syscall がユーザモード
に戻る直前に停止されました。デバッ
ガは、ABI 定義のレジスタおよびメモ
リのシステムコールリターン値を調べ
るかもしれません。
PL_FLAG_EXEC
PL_FLAG_SCX が設定されるとき、プロ
グラムが execve(2) ファミリからシス
テムコールの実行が成功することに
よって変更された debuggee プロセス
によって実行されていることを知らせ
るために、このフラグを、さらに指定
します。
PL_FLAG_SI
struct ptrace_lwpinfo の pl_siginfo
メンバが有効な情報を含むことを示し
ます。
PL_FLAG_FORKED
プロセスが、新しい子プロセスを作成
した fork(2) への呼び出しから戻って
いることを示します。新しいロセスの
プロセス識別子は、struct
ptrace_lwpinfo の pl_child_pid メン
バで利用可能です。
PL_FLAG_CHILD
フラグは、PTRACE_FORK が有効にされ
るとき、自動的にアタッチされる新し
い子プロセスから報告される最初のイ
ベントのために設定されます。
PL_FLAG_BORN
このフラグは、PTRACE_LWP が有効にさ
れるとき、新しい LWP から報告される
最初のイベントのために設定されま
す。それは、PL_FLAG_SCX とともに報
告されます。
PL_FLAG_EXITED
このフラグは、PTRACE_LWP が有効にさ
れるとき、LWP を終了することによっ
て報告された最後のイベントのために
設定されます。このイベントは、プロ
セスの最後の LWP が終了するとき、報
告されないことに注意してください。
最後のスレッドの終了は、通常のプロ
セス終了イベントを通して報告されま
す。
PL_FLAG_VFORKED
スレッドが、新しい子プロセスを作成
する vfork(2) への呼び出しから返る
ことを示します。このフラグは、
PL_FLAG_FORKED に加えて設定されま
す。
PL_FLAG_VFORK_DONE
vfork(2) によって作成された子プロセ
スが、トレースされるプロセスでその
アドレス空間を共有することを停止し
た後に、スレッドが再開したことを示
します。
pl_sigmask
LWP の現在のシグナルマスク
pl_siglist
LWP のための現在保留中のセットのシグナル。
プロセスに配信されるシグナルは、スレッドが
配信のために選択されるまで、LWP siglist に
現れないことに注意してください。
pl_siginfo
保留中のシグナルに伴う siginfo。PL_FLAG_SI
が pl_flags に設定されているとき、
PL_EVENT_SIGNAL 停止のためだけに有効です。
pl_tdname
スレッドの名前。
pl_child_pid
新しい子プロセスのプロセス識別子。
PL_FLAG_FORKED が pl_flags に設定されている
とき、PL_EVENT_SIGNAL 停止のためだけに有効
です。
pl_syscall_code
現在のシステムコールの ABI 特有の識別子。間
接的なシステムコールのために、このフィール
ドは、間接的なシステムコールを報告すること
に注意してください。PL_FLAG_SCE または
PL_FLAG_SCX が pl_flags に設定されるときの
み有効です。
pl_syscall_narg
システムコールの識別子をカウントしない現在
のシステムコールに渡される引数の数。間接的
なシステムコールのために、このフィールド
は、間接的なシステムコールの渡される引数を
報告することに注意してください。PL_FLAG_SCE
または PL_FLAG_SCX が pl_flags に設定される
ときのみ有効です。
PT_GETNUMLWPS この要求は、トレースされたプロセスに関連している
カーネルスレッドの数を返します。
PT_GETLWPLIST 現在のスレッドのリストを取得するために、この要求を
使用することができます。タイプ lwpid_t の配列へのポ
インタは、data によって指定された配列サイズがある
addr で渡されるべきです。ptrace() からの返り値は、
書き込まれた配列エントリの数です。
PT_SETSTEP この要求は、指定されたプロセスの単一ステップ動作を
オンにします。ステッピングは、シングルステップのト
ラップが捕獲されるとき、自動的に無効にされます。
PT_CLEARSTEP この要求は、指定されたプロセスの単一ステップ動作を
オフにします。
PT_SUSPEND この要求は、指定されたスレッドをサスペンドします。
PT_RESUME この要求は、指定されたスレッドを再開します。
PT_TO_SCE この要求は、すべての将来のシステムコールの入口をト
レースし、プロセスを続けるために、PTRACE_SCE イベン
トフラグを設定します。addr と data 引数は、
PT_CONTINUE と同じように使用されます。
PT_TO_SCX この要求は、すべての将来のシステムコールの入口をト
レースし、プロセスを続けるために PTRACE_SCX イベン
トフラグを設定します。addr と data 引数は、
PT_CONTINUE と同じように使用されます。
PT_SYSCALL この要求は、すべての将来のシステムコールの入口と出
口をトレースし、プロセスを続けるために
PTRACE_SYSCALL イベントフラグを設定します。addr と
data 引数は、PT_CONTINUE と同じように使用されます。
PT_GET_SC_ARGS PL_FLAG_SCE または PL_FLAG_SCX 状態のいずれかで停止
するスレッドについて、すなわち、 syscall への入口ま
たは出口で、この要求は、syscall 引数を取り出しま
す。
引数は、addr ポインタによって指されたバッファに連続
してコピーされます。各 syscall 引数は、マシン語とし
て格納されます。カーネルは、syscall が受け付けるの
と同じくらい多くの引数としてコピーしますが、struct
ptrace_lwpinfo の pl_syscall_narg メンバを参照、合
計の data バイト以上は、コピーされません。
PT_FOLLOW_FORK この要求は、トレースされたプロセスの新しい子プロセ
スのトレースを制御します。data が 0 でないなら、
PTRACE_FORK は、トレースされるプロセスのイベントの
トレースマスクで設定されます。data が 0 であるな
ら、PTRACE_FORK は、トレースされるプロセスのイベン
トのトレースマスクからクリアされます。
PT_LWP_EVENTS この要求は、LWP の作成と破壊のトレースを制御しま
す。data が 0 でないなら、PTRACE_LWP は、トレースさ
れるプロセスのイベントのトレースマスクで設定されま
す。data が 0 であるなら、PTRACE_LWP は、トレースさ
れるプロセスのイベントのトレースマスクからクリアさ
れます。
PT_GET_EVENT_MASK この要求は、トレースされるプロセスのイベントのト
レースマスクを addr によって指される整数に読み込み
ます。整数のサイズは、data に渡されなければなりませ
ん。
PT_SET_EVENT_MASK この要求は、addr によって指される整数から、トレース
されるプロセスのイベントのトレースマスクを設定しま
す。整数のサイズは、data で渡されなければなりませ
ん。
PT_VM_TIMESTAMP この要求は、ptrace() から返り値としてトレースされた
プロセスのメモリマップの世代 (generation) 番号また
はタイムスタンプを返します。これは、VM マップが、こ
の要求が行われた最後の時から変更されたかどうか決定
するためにトレースするプロセスのための安価な方法を
提供しています。
PT_VM_ENTRY この要求は、トレースされたプロセスの VM マップのエ
ントリを繰り返すために使用されます。addr 引数は、次
の通り定義される struct ptrace_vm_entry へのポイン
タを指定します:
struct ptrace_vm_entry {
int pve_entry;
int pve_timestamp;
u_long pve_start;
u_long pve_end;
u_long pve_offset;
u_int pve_prot;
u_int pve_pathlen;
long pve_fileid;
uint32_t pve_fsid;
char *pve_path;
};
最初のエントリは、pve_entry を 0 に設定することに
よって返されます。それに続くエントリは、前の要求に
よって返された値から変更されないままの pve_entry が
返されます。エントリで繰り返えされている間に、VM
マップへの変更を検出するために pve_timestamp フィー
ルドを使用することができます。そして、トレースして
いるプロセスは、再開などのような適切なアクションを
取ることができます。エントリの pve_pathlen を 0 以
外に設定することによって、支援されたオブジェクトの
パス名は、vnode によって支援される提供されたエント
リである。pve_path によって指されたバッファに返され
ます。pve_pathlen フィールドは、(終端のヌル文字を含
んで) パス名の実際の長さに更新されます。pve_offset
フィールドは、範囲が始まる支援されたオブジェクト内
のオフセットです。範囲は、pve_start の VM 空間に位
置して pve_end まで広がっています (包括的)。
data 引数は、無視されます。
ARM マシン特有の要求
PT_GETVFPREGS スレッドの VFP マシン状態を addr によって指されるバッ
ファに返します。
data 引数は、無視されます。
PT_SETVFPREGS addr によって指されるバッファからスレッドの VFP マシン
状態を設定します。
data 引数は、無視されます。
x86 マシン特有の要求
PT_GETXMMREGS XMM FPU 状態を、引数 addr によって指されたバッファ
にコピーします。バッファは、マシン命令 FXSAVE のた
めの 32 ビットの保存バッファと同じレイアウトがあり
ます。
この要求は、ネイティブな 32 ビットシステムと amd64
カーネルの両方で i386 プログラムのためだけに有効で
す。64 ビットの amd64 プログラムのために、XMM 状態
は、PT_GETFPREGS 要求によって返された FPU 状態の一
部として報告されます。
data 引数は、無視されます。
PT_SETXMMREGS 引数 addr によって指されたバッファからのスレッドの
ための XMM FPU 状態をロードします。バッファは、マシ
ン命令 FXRSTOR のための 32 ビットロードバッファと同
じレイアウトがあります。
PT_GETXMMREGS と同様に、この要求は、i386 プログラム
のためだけに有効です。
data 引数は、無視されます。データ引数は無視されま
す。
PT_GETXSTATE_INFO XSAVE FPU 拡張が CPU によってサポートされ、ユーザ空
間のプログラムで許可されることを報告します。addr 引
数は、返された要求の情報を含んでいる、タイプ struct
ptrace_xstate_info の変数を指さなければなりません。
struct ptrace_xstate_info は、次のように定義されま
す:
struct ptrace_xstate_info {
uint64_t xsave_mask;
uint32_t xsave_len;
};
xsave_mask フィールドは、現在有効にされた拡張のビッ
トマスクです。ビットの意味は、Intel と AMD プロセッ
サの文書に定義されています。xsave_len フィールド
は、x86 の XSAVE マシン命令によって定義された形式で
現在有効にされた拡張のためのハードウェア状態を、格
納するための XSAVE 領域の長さを報告します。
data 引数の値は、struct ptrace_xstate_info のサイズ
と等しくなければなりません。
PT_GETXSTATE スレッドのための XSAVE 領域の内容を返します。addr
引数は、内容がコピーされるバッファを指し、data 引数
は、バッファのサイズを指定します。カーネルは、バッ
ファサイズによって許可されるのと同じくらい多くの内
容をコピーします。バッファのレイアウトは、XSAVE マ
シン命令のための保存領域のレイアウトによって指定さ
れます。
PT_SETXSTATE addr ポインタによって指定されたバッファからスレッド
のための XSAVE 状態をロードします。バッファサイズ
は、data 引数で渡されます。バッファは、完全な x87
FPU と XMM 状態のロードを許可するために、少なくとも
(x86/fpu.h で定義される) struct savefpu と同じくら
い大きくなければなりません。それは、
PT_GETXSTATE_INFO 要求の struct ptrace_xstate_info
から xsave_len フィールドによって報告されるように、
XSAVE 状態の長さより大きくあってはなりません。バッ
ファのレイアウトは、XRSTOR マシン命令のためのロード
領域のレイアウトと同一です。
PT_GETFSBASE %fs セグメントレジスタを使用して、セグメント化され
たメモリのアドレッシングを行うとき、使用される基本
の値を返します。addr 引数は、基本の値が格納される
unsigned long の変数を指します。
data 引数は、無視されます。
PT_GETGSBASE PT_GETFSBASE 要求に似ていますが、%gs セグメントレジ
スタのためのベースを返します。
PT_SETFSBASE addr 引数によって指された値への %fs セグメントレジ
スタのためのベースを設定します。addr は、新しいベー
スを含んでいる unsigned long 変数を指さなければなり
ません。
data 引数は、無視されます。
PT_SETGSBASE PT_SETFSBASE 要求に似ていますが、%gs セクメントレジ
スタのためのベースを設定します。
PowerPC マシン特有の要求
PT_GETVRREGS addr によって指されたバッファにスレッドの ALTIVEC マシン
状態を返します。
data 引数は、無視されます。
PT_SETVRREGS addr によって指されたバッファからスレッドの ALTIVEC マシ
ン状態を設定します。
data 引数は、無視されます。
さらに、他のマシン特有の要求が、存在します。
戻り値
ほとんどの要求は、成功すれば、0 を返し、エラーで -1 を返します。いくつか
の要求によって、ptrace() は、成功すれば、プロセスメモリから読み込まれた値
を返す PT_READ_I と PT_READ_D であるので、エラーでない値として -1 を返す
ことができます。あいまいさをなくすために、呼び出しの前に errno を 0 に設
定して、後でチェックすることができます。
現在の ptrace() の実装は、歴史的な理由のためと他のオペレーティングシステ
ムとの一貫性の両方のために、カーネルへの呼び出しの前に、常に errno を 0
に設定します。それは、前方互換性のために 0 を errno に明示的に割り当てる
ように推奨されます。
エラー
ptrace() システムコールは、次の場合に失敗します:
[ESRCH]
• 指定されたプロセス ID があるプロセスが存在しませ
ん。
[EINVAL]
• プロセスがそれ自体で PT_ATTACH の使用を試みまし
た。
• request 引数が正しい要求の 1 つではありませんでし
た。
• PT_CONTINUE への (data の) シグナル番号が 0 でも正
しいシグナル番号でもありませんでした。
• PT_GETREGS, PT_SETREGS, PT_GETFPREGS,
PT_SETFPREGS, PT_GETDBREGS または PT_SETDBREGS
が、有効なレジスタセットがないプロセスで試みられま
した。(これは、通常、システムプロセスでのみ真で
す)。
• PT_VM_ENTRY は、pve_entry のための無効の値が与えら
れました。これは、また、プロセスの VM マップへの変
更によって引き起こされるかもしれません。
• PT_LWPINFO に提供される (data の) サイズは、0 以下
か、またはカーネルに既知の ptrace_lwpinfo 構造体よ
り大きくなります。
• x86 特有の PT_GETXSTATE_INFO 要求に提供された
(data の) サイズは、struct ptrace_xstate_info のサ
イズと等しくありませんでした。
• x86 特有の PT_SETXSTATE 要求に提供された (data の)
サイズは、x87 プラス XMM 保存領域のサイズより小さ
かった。
• x86 特有の PT_SETXSTATE 要求に提供された (data の)
サイズは、PT_GETXSTATE_INFO 要求から struct
ptrace_xstate_info の xsave_len メンバに返されたも
のより大きかった。
• amd64 特有の要求 PT_SETFSBASE または PT_SETGSBASE
に提供された、基本の値は、有効なユーザアドレス空間
の外側を指しました。このエラーは、32 ビットプログ
ラムで起こりません。
[EBUSY]
• PT_ATTACH が既にトレースされていたプロセスで試みら
れました。
• 要求が、要求を行っているプロセス以外のいくつかのプ
ロセスによって、トレースされていたプロセスを操作し
ようと試みました。
• (PT_ATTACH 以外の) 要求が停止されなかったプロセス
を指定しました。
[EPERM]
• (PT_ATTACH 以外の) 要求が、まったくトレースされて
いなかったプロセスを操作しようと試みました。
• 上記の PT_ATTACH の下でリストされた要件の違反のプ
ロセスで PT_ATTACH を使用するために、試みが行われ
ました。
[ENOENT]
• PT_VM_ENTRY は、以前に返された、メモリマップの最後
のエントリです。それ以上のエントリが存在していませ
ん。
[ENAMETOOLONG]
• PT_VM_ENTRY は、バッファが十分に大きくないので、支
援されたオブジェクトのパス名を返すことができませ
ん。pve_pathlen は、戻り時に必要であった最小のバッ
ファサイズを保持しています。
関連項目
execve(2), sigaction(2), wait(2), execv(3), i386_clr_watch(3),
i386_set_watch(3)
歴史
ptrace() 関数は、Version 6 AT&T UNIX で登場しました。
FreeBSD 11.4 May 22, 2018 FreeBSD 11.4