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.

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