Module Name: src
Committed By: kamil
Date: Sat Jan 7 05:51:14 UTC 2017
Modified Files:
src/lib/libc/sys: ptrace.2
Log Message:
Add more notes explaining how debuggers work on NetBSD
Explain:
- execve(2) handling and behavior, SIGTRAP & TRAP_EXEC
- reference PaX MPROTECT restrictions for debuggers
- software breakpoints handling and behavior, SIGTRAP & TRAP_BKPT
- single step behavior, SIGTRAP & TRAP_TRACE
- list predefined MI symbols for help debuggers in port specific headers
- explain that PT_TRACE_ME does not send a SIGSTOP signal
Sponsored by <The NetBSD Foundation>
To generate a diff of this commit:
cvs rdiff -u -r1.49 -r1.50 src/lib/libc/sys/ptrace.2
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/lib/libc/sys/ptrace.2
diff -u src/lib/libc/sys/ptrace.2:1.49 src/lib/libc/sys/ptrace.2:1.50
--- src/lib/libc/sys/ptrace.2:1.49 Sat Jan 7 03:41:25 2017
+++ src/lib/libc/sys/ptrace.2 Sat Jan 7 05:51:14 2017
@@ -1,4 +1,4 @@
-.\" $NetBSD: ptrace.2,v 1.49 2017/01/07 03:41:25 kamil Exp $
+.\" $NetBSD: ptrace.2,v 1.50 2017/01/07 05:51:14 kamil Exp $
.\"
.\" This file is in the public domain.
.Dd January 7, 2016
@@ -43,12 +43,86 @@ terminate or continue as appropriate.
.Fn ptrace
is the mechanism by which all this happens.
.Pp
+When a process that is traced by a debugger request and calls
+.Xr execve 2
+or any of the routines built on it
+.Po
+such as
+.Xr execv 3
+.Pc ,
+it will stop before executing the first instruction of the new image and emit
+.Dv SIGRAP
+with
+.Dv si_code
+set to
+.Dv TRAP_EXEC .
+If a program is traced with the
+.Dv PT_SYSCALL
+option enabled,
+this event notifier is disabled.
+If a traced program calls
+.Xr execve 2
+any setuid or setgid bits on the executable being executed will be ignored.
+.Pp
+Program (software) breakpoints are reported with
+.Dv SIGTRAP
+and the
+.Dv si_code
+value set to
+.Dv TRAP_BKPT .
+These breakpoints are machine specific instructions that interrput the process.
+In order to put a trap by a tracer into the tracee's program,
+debugger must violate the
+.Dv PaX MPROTECT
+restrictions.
+For details check the
+.Dv security.pax.mprotect.ptrace
+option described in
+.Xr sysctl 7 .
+When a tracee is interrputed by a trap,
+the trap is not removed by the kernel and it must be handled by a debugger.
+.Pp
+If a program is traced with single steps
+.Dv ( PT_STEP )
+it reports each step with
+.Dv SIGTRAP
+with
+.Dv si_code
+set to
+.Dv TRAP_TRACE .
+.Pp
+A debugger might reuse a port specific symbols,
+to help writing portable code as described in the port specific part of the
+.In sys/ptrace.h
+header.
+Among these symbols,
+there are:
+.Bl -dash -tag
+.It
+.Dv PTRACE_REG_PC
+.It
+.Dv PTRACE_REG_SET_PC
+.It
+.Dv PTRACE_REG_SP
+.It
+.Dv PTRACE_REG_INTRV
+.It
+.Dv PTRACE_BREAKPOINT
+.It
+.Dv PTRACE_BREAKPOINT_SIZE
+.It
+.Dv PTRACE_BREAKPOINT_ADJ
+.El
+.Pp
The
.Fa request
-argument specifies what operation is being performed; the meaning of
+argument
+of
+.Nm
+specifies what operation is being performed; the meaning of
the rest of the arguments depends on the operation, but except for one
special case noted below, all
-.Fn ptrace
+.Nm
calls are made by the tracing process, and the
.Fa pid
argument specifies the process ID of the traced process.
@@ -59,20 +133,14 @@ can be:
This request is the only one used by the traced process; it declares
that the process expects to be traced by its parent.
All the other arguments are ignored.
-(If the parent process does not expect to trace
+If the parent process does not expect to trace
the child, it will probably be rather confused by the results; once the
traced process stops, it cannot be made to continue except via
-.Fn ptrace . )
-When a process has used this request and calls
-.Xr execve 2
-or any of the routines built on it
-.Po
-such as
-.Xr execv 3
-.Pc ,
-it will stop before executing the first instruction of the new image.
-Also, any setuid or setgid bits on the executable being executed will
-be ignored.
+.Fn ptrace .
+.Pp
+This call does not stop the process neither emit
+.Dv SIGSTOP
+to parent.
.It Dv PT_READ_I , Dv PT_READ_D
These requests read a single
.Li int
@@ -138,8 +206,14 @@ must have the same real UID as the traci
not be executing a setuid or setgid executable.
(If the tracing process is running as root,
these restrictions do not apply.)
+.Pp
The tracing process will see the newly-traced process stop and may then
control it as if it had been traced all along.
+It means that the
+.Dv SIGSTOP
+signal is emitted to tracer.
+It is different behavior to the one from
+.Dv PT_TRACE_ME .
.Pp
Three other restrictions apply to all tracing processes, even those
running as root.
@@ -360,7 +434,7 @@ argument should be set to
.Li sizeof(struct ptrace_siginfo) .
.Pp
In order to pass faked signal to the tracee,
-the siginal type must match the signal passed to process with
+the signal type must match the signal passed to process with
.Dv PT_CONTINUE ,
.Dv PT_DETACH
or
