[src/trunk]: src/lib/libc/sys Update the ptrace(2) documentation

[kamil <kamil%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/99f40f4d9572
branches:  trunk
changeset: 999211:99f40f4d9572
user:      kamil <kamil%NetBSD.org@localhost>
date:      Sat May 25 04:25:14 2019 +0000

description:
Update the ptrace(2) documentation

Document that TRAP_EXEC can be returned for PT_SYSCALL.
Document truncated byte transfers.

diffstat:

 lib/libc/sys/ptrace.2 |  35 +++++++++++++++++++++++++++++------
 1 files changed, 29 insertions(+), 6 deletions(-)

diffs (79 lines):

diff -r 1693266618ed -r 99f40f4d9572 lib/libc/sys/ptrace.2
--- a/lib/libc/sys/ptrace.2     Sat May 25 03:25:08 2019 +0000
+++ b/lib/libc/sys/ptrace.2     Sat May 25 04:25:14 2019 +0000
@@ -1,7 +1,7 @@
-.\"    $NetBSD: ptrace.2,v 1.69 2018/05/01 16:37:23 kamil Exp $
+.\"    $NetBSD: ptrace.2,v 1.70 2019/05/25 04:25:14 kamil Exp $
 .\"
 .\" This file is in the public domain.
-.Dd May 1, 2018
+.Dd May 25, 2019
 .Dt PTRACE 2
 .Os
 .Sh NAME
@@ -56,10 +56,6 @@
 .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.
@@ -220,6 +216,11 @@
 .Eo \&
 .Fn ptrace
 .Ec .
+.Pp
+These operations return success on incomplete and cancelled byte transfers.
+New software shall use
+.Dv PT_IO
+as it allows to check whether a byte transfer was completed.
 .It Dv PT_WRITE_I , Dv PT_WRITE_D
 These requests parallel
 .Dv PT_READ_I
@@ -229,6 +230,10 @@
 The
 .Fa data
 argument supplies the value to be written.
+.Pp
+New software shall use
+.Dv PT_IO
+as it allows to check whether an operation was completed.
 .It Dv PT_CONTINUE
 The traced process continues execution.
 .Fa addr
@@ -349,6 +354,15 @@
 .Li \-1
 and set
 .Va errno .
+.Pp
+This interface returns success for partial and cancelled byte transfers.
+For an interrupted transfer, a user shall check whether occurred at least
+a single of the following two conditions:
+.Dv piod_len == 0
+and set
+.Va errno .
+Successful but incomplete byte transfers shall be restarted in the place
+where they were stopped.
 .It Dv PT_DUMPCORE
 Makes the process specified in the
 .Fa pid
@@ -799,6 +813,15 @@
 .Dv PT_SETFPREGS
 was attempted on a process with no valid register set.
 (This is normally true only of system processes.)
+.It
+A process attempted to set Program Counter to 0 in
+.Dv PT_CONTINUE ,
+.Dv PT_SYSCALL
+or
+.Dv PT_DETACH
+with
+.Dv vm.user_va0_disable
+set to 1.
 .El
 .It Bq Er EPERM
 .Bl -bullet -compact