diff options
author | jhb <jhb@FreeBSD.org> | 2016-08-15 21:10:41 +0000 |
---|---|---|
committer | jhb <jhb@FreeBSD.org> | 2016-08-15 21:10:41 +0000 |
commit | e4842c451d2fcb20d4e7734a423b4dda17c5e79b (patch) | |
tree | 5e1aaaba2757e8de80c939a791a338c87196b1dd /lib/libc/sys | |
parent | bdf6ecc5e6663cf315031bec7696e4418f02bd24 (diff) | |
download | FreeBSD-src-e4842c451d2fcb20d4e7734a423b4dda17c5e79b.zip FreeBSD-src-e4842c451d2fcb20d4e7734a423b4dda17c5e79b.tar.gz |
MFC 302900,302902,302921,303461,304009:
Add a mask of optional ptrace() events.
302900:
Add a test for user signal delivery.
This test verifies we get the correct ptrace event details when a signal
is posted to a traced process from userland.
302902:
Add a mask of optional ptrace() events.
ptrace() now stores a mask of optional events in p_ptevents. Currently
this mask is a single integer, but it can be expanded into an array of
integers in the future.
Two new ptrace requests can be used to manipulate the event mask:
PT_GET_EVENT_MASK fetches the current event mask and PT_SET_EVENT_MASK
sets the current event mask.
The current set of events include:
- PTRACE_EXEC: trace calls to execve().
- PTRACE_SCE: trace system call entries.
- PTRACE_SCX: trace syscam call exits.
- PTRACE_FORK: trace forks and auto-attach to new child processes.
- PTRACE_LWP: trace LWP events.
The S_PT_SCX and S_PT_SCE events in the procfs p_stops flags have
been replaced by PTRACE_SCE and PTRACE_SCX. PTRACE_FORK replaces
P_FOLLOW_FORK and PTRACE_LWP replaces P2_LWP_EVENTS.
The PT_FOLLOW_FORK and PT_LWP_EVENTS ptrace requests remain for
compatibility but now simply toggle corresponding flags in the
event mask.
While here, document that PT_SYSCALL, PT_TO_SCE, and PT_TO_SCX both
modify the event mask and continue the traced process.
302921:
Rename PTRACE_SYSCALL to LINUX_PTRACE_SYSCALL.
303461:
Note that not all optional ptrace events use SIGTRAP.
New child processes attached due to PTRACE_FORK use SIGSTOP instead of
SIGTRAP. All other ptrace events use SIGTRAP.
304009:
Remove description of P_FOLLOWFORK as this flag was removed.
Diffstat (limited to 'lib/libc/sys')
-rw-r--r-- | lib/libc/sys/ptrace.2 | 219 |
1 files changed, 178 insertions, 41 deletions
diff --git a/lib/libc/sys/ptrace.2 b/lib/libc/sys/ptrace.2 index 10ad660..14ce6dd 100644 --- a/lib/libc/sys/ptrace.2 +++ b/lib/libc/sys/ptrace.2 @@ -2,7 +2,7 @@ .\" $NetBSD: ptrace.2,v 1.2 1995/02/27 12:35:37 cgd Exp $ .\" .\" This file is in the public domain. -.Dd December 29, 2015 +.Dd July 28, 2016 .Dt PTRACE 2 .Os .Sh NAME @@ -58,8 +58,9 @@ The signal may be a normal process signal, generated as a result of traced process behavior, or use of the .Xr kill 2 system call; alternatively, it may be generated by the tracing facility -as a result of attaching, system calls, or stepping by the tracing -process. +as a result of attaching, stepping by the tracing +process, +or an event in the traced process. The tracing process may choose to intercept the signal, using it to observe process behavior (such as .Dv SIGTRAP ) , @@ -69,6 +70,121 @@ The system call is the mechanism by which all this happens. .Pp +A traced process may report additional signal stops corresponding to +events in the traced process. +These additional signal stops are reported as +.Dv SIGTRAP +or +.Dv SIGSTOP +signals. +The tracing process can use the +.Dv PT_LWPINFO +request to determine which events are associated with a +.Dv SIGTRAP +or +.Dv SIGSTOP +signal. +Note that multiple events may be associated with a single signal. +For example, events indicated by the +.Dv PL_FLAG_BORN , +.Dv PL_FLAG_FORKED , +and +.Dv PL_FLAG_EXEC +flags are also reported as a system call exit event +.Pq Dv PL_FLAG_SCX . +The signal stop for a new child process enabled via +.Dv PTRACE_FORK +will report a +.Dv SIGSTOP +signal. +All other additional signal stops use +.Dv SIGTRAP . +.Pp +Each traced process has a tracing event mask. +An event in the traced process only reports a +signal stop if the corresponding flag is set in the tracing event mask. +The current set of tracing event flags include: +.Bl -tag -width ".Dv PTRACE_SYSCALL" +.It Dv PTRACE_EXEC +Report a stop for a successful invocation of +.Xr execve 2 . +This event is indicated by the +.Dv PL_FLAG_EXEC +flag in the +.Va pl_flags +member of +.Vt "struct ptrace_lwpinfo" . +.It Dv PTRACE_SCE +Report a stop on each system call entry. +This event is indicated by the +.Dv PL_FLAG_SCE +flag in the +.Va pl_flags +member of +.Vt "struct ptrace_lwpinfo" . +.It Dv PTRACE_SCX +Report a stop on each system call exit. +This event is indicated by the +.Dv PL_FLAG_SCX +flag in the +.Va pl_flags +member of +.Vt "struct ptrace_lwpinfo" . +.It Dv PTRACE_SYSCALL +Report stops for both system call entry and exit. +.It Dv PTRACE_FORK +This event flag controls tracing for new child processes of a traced process. +.Pp +When this event flag is enabled, +new child processes will enable tracing and stop before executing their +first instruction. +The new child process will include the +.Dv PL_FLAG_CHILD +flag in the +.Va pl_flags +member of +.Vt "struct ptrace_lwpinfo" . +The traced process will report a stop that includes the +.Dv PL_FLAG_FORKED +flag. +The process ID of the new child process will also be present in the +.Va pl_child_pid +member of +.Vt "struct ptrace_lwpinfo" . +Note that new child processes will be attached with the default +tracing event mask; +they do not inherit the event mask of the traced process. +.Pp +When this event flag is not enabled, +new child processes will execute without tracing enabled. +.It Dv PTRACE_LWP +This event flag controls tracing of LWP +.Pq kernel thread +creation and destruction. +When this event is enabled, +new LWPs will stop and report an event with +.Dv PL_FLAG_BORN +set before executing their first instruction, +and exiting LWPs will stop and report an event with +.Dv PL_FLAG_EXITED +set before completing their termination. +.Pp +Note that new processes do not report an event for the creation of their +initial thread, +and exiting processes do not report an event for the termination of the +last thread. +.El +.Pp +The default tracing event mask when attaching to a process via +.Dv PT_ATTACH , +.Dv PT_TRACE_ME , +or +.Dv PTRACE_FORK +includes only +.Dv PTRACE_EXEC +events. +All other event flags are disabled. +.Pp The .Fa request argument specifies what operation is being performed; the meaning of @@ -368,21 +484,20 @@ The process identifier of the new process is available in the member of .Vt "struct ptrace_lwpinfo" . .It PL_FLAG_CHILD -The flag is set for first event reported from a new child, which is -automatically attached due to -.Dv PT_FOLLOW_FORK -enabled. +The flag is set for first event reported from a new child which is +automatically attached when +.Dv PTRACE_FORK +is enabled. .It PL_FLAG_BORN -This flag is set for the first event reported from a new LWP when LWP -events are enabled via -.Dv PT_LWP_EVENTS . +This flag is set for the first event reported from a new LWP when +.Dv PTRACE_LWP +is enabled. It is reported along with -.Dv PL_FLAG_SCX -and is always reported if LWP events are enabled. +.Dv PL_FLAG_SCX . .It PL_FLAG_EXITED This flag is set for the last event reported by an exiting LWP when -LWP events are enabled via -.Dv PT_LWP_EVENTS . +.Dv PTRACE_LWP +is enabled. Note that this event is not reported when the last LWP in a process exits. The termination of the last thread is reported via a normal process exit event. @@ -456,50 +571,72 @@ This request will suspend the specified thread. .It PT_RESUME This request will resume the specified thread. .It PT_TO_SCE -This request will trace the specified process on each system call entry. +This request will set the +.Dv PTRACE_SCE +event flag to trace all future system call entries and continue the process. +The +.Fa addr +and +.Fa data +arguments are used the same as for +.Dv PT_CONTINUE. .It PT_TO_SCX -This request will trace the specified process on each system call exit. +This request will set the +.Dv PTRACE_SCX +event flag to trace all future system call exits and continue the process. +The +.Fa addr +and +.Fa data +arguments are used the same as for +.Dv PT_CONTINUE. .It PT_SYSCALL -This request will trace the specified process -on each system call entry and exit. +This request will set the +.Dv PTRACE_SYSCALL +event flag to trace all future system call entries and exits and continue +the process. +The +.Fa addr +and +.Fa data +arguments are used the same as for +.Dv PT_CONTINUE. .It PT_FOLLOW_FORK This request controls tracing for new child processes of a traced process. If .Fa data is non-zero, -then new child processes will enable tracing and stop before executing their -first instruction. +.Dv PTRACE_FORK +is set in the traced process's event tracing mask. If .Fa data -is zero, then new child processes will execute without tracing enabled. -By default, tracing is not enabled for new child processes. -Child processes do not inherit this property. -The traced process will set the -.Dv PL_FLAG_FORKED -flag upon exit from a system call that creates a new process. +is zero, +.Dv PTRACE_FORK +is cleared from the traced process's event tracing mask. .It PT_LWP_EVENTS This request controls tracing of LWP creation and destruction. If .Fa data is non-zero, -then LWPs will stop to report creation and destruction events. +.Dv PTRACE_LWP +is set in the traced process's event tracing mask. If .Fa data is zero, -then LWP creation and destruction events will not be reported. -By default, tracing is not enabled for LWP events. -Child processes do not inherit this property. -New LWPs will stop to report an event with -.Dv PL_FLAG_BORN -set before executing their first instruction. -Exiting LWPs will stop to report an event with -.Dv PL_FLAG_EXITED -set before completing their termination. -.Pp -Note that new processes do not report an event for the creation of their -initial thread, -and exiting processes do not report an event for the termination of the -last thread. +.Dv PTRACE_LWP +is cleared from the traced process's event tracing mask. +.It PT_GET_EVENT_MASK +This request reads the traced process's event tracing mask into the +integer pointed to by +.Fa addr . +The size of the integer must be passed in +.Fa data . +.It PT_SET_EVENT_MASK +This request sets the traced process's event tracing mask from the +integer pointed to by +.Fa addr . +The size of the integer must be passed in +.Fa data . .It PT_VM_TIMESTAMP This request returns the generation number or timestamp of the memory map of the traced process as the return value from |