- FreeBSD'ized the ptrace manpage by removing non-FreeBSD specific portions.

- install ptrace.2

2 files changed, 16 insertions, 214 deletions

diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc
index dc65844..f115d3d 100644
--- a/lib/libc/sys/Makefile.inc
+++ b/lib/libc/sys/Makefile.inc
@@ -91,9 +91,10 @@ MAN2+=	sys/accept.2 sys/access.2 sys/acct.2 sys/adjtime.2 sys/bind.2 \
 	sys/ktrace.2 sys/link.2 sys/listen.2 sys/lseek.2 sys/mkdir.2 \
 	sys/mkfifo.2 sys/mknod.2 sys/madvise.2 sys/mincore.2 sys/mlock.2 \
 	sys/mmap.2 sys/mount.2 sys/mprotect.2 sys/msync.2 sys/munmap.2 \
-	sys/nfssvc.2 sys/open.2 sys/pathconf.2 sys/pipe.2 sys/profil.2 \
-	sys/quotactl.2 sys/read.2 sys/readlink.2 sys/reboot.2 sys/recv.2 \
-	sys/rename.2 sys/revoke.2 sys/rmdir.2 sys/rtprio.2 sys/select.2 \
+	sys/ptrace.2 sys/nfssvc.2 sys/open.2 sys/pathconf.2 sys/pipe.2 \
+	sys/profil.2 sys/quotactl.2 sys/read.2 sys/readlink.2 sys/reboot.2 \
+	sys/recv.2 sys/rename.2 sys/revoke.2 sys/rmdir.2 sys/rtprio.2 \
+	sys/select.2 \
 	sys/semctl.2 sys/semget.2 sys/semop.2 \
 	sys/send.2 sys/setgroups.2 \
 	sys/setpgid.2 sys/setregid.2 sys/setreuid.2 \
diff --git a/lib/libc/sys/ptrace.2 b/lib/libc/sys/ptrace.2
index 69477e9..20ee4d9 100644
--- a/lib/libc/sys/ptrace.2
+++ b/lib/libc/sys/ptrace.2
@@ -1,9 +1,10 @@
+.\"	$Id$
 .\"	$NetBSD: ptrace.2,v 1.2 1995/02/27 12:35:37 cgd Exp $
 .\"
 .\" This file is in the public domain.
-.Dd November 7, 1994
+.Dd January 20, 1996
 .Dt PTRACE 2
-.Os NetBSD 1.0BETA
+.Os FreeBSD 2
 .Sh NAME
 .Nm ptrace
 .Nd process tracing and debugging
@@ -144,156 +145,6 @@ The traced process terminates, as if
 had been used with
 .Dv SIGKILL
 given as the signal to be delivered.
-.It Dv PT_ATTACH
-This request allows a process to gain control of an otherwise unrelated
-process and begin tracing it.  It does not need any cooperation from
-the to-be-traced process.  In this case,
-.Fa pid
-specifies the process ID of the to-be-traced process, and the other two
-arguments are ignored.  This request requires that the target process
-must have the same real UID as the tracing process, and that it must
-not be executing a setuid or setgid executable.  (If the tracing
-process is running as root, these restrictions do not apply.)  The
-tracing process will see the newly-traced process stop and may then
-control it as if it had been traced all along.
-.It Dv PT_DETACH
-This request is like PT_CONTINUE, except that it does not allow
-specifying an alternate place to continue execution, and after it
-succeeds, the traced process is no longer traced and continues
-execution normally.
-.El
-.Pp
-Additionally, machine-specific requests can exist.  On the SPARC, these
-are:
-.Bl -tag -width 12n
-.It Dv PT_GETREGS
-This request reads the traced process' machine registers into the
-.Dq Li "struct reg"
-(defined in
-.Aq Pa machine/reg.h )
-pointed to by
-.Fa addr .
-.It Dv PT_SETREGS
-This request is the converse of
-.Dv PT_GETREGS ;
-it loads the traced process' machine registers from the
-.Dq Li "struct reg"
-(defined in
-.Aq Pa machine/reg.h )
-pointed to by
-.Fa addr .
-.It Dv PT_GETFPREGS
-This request reads the traced process' floating-point registers into
-the
-.Dq Li "struct fpreg"
-(defined in
-.Aq Pa machine/reg.h )
-pointed to by
-.Fa addr .
-.It Dv PT_SETFPREGS
-This request is the converse of
-.Dv PT_GETFPREGS ;
-it loads the traced process' floating-point registers from the
-.Dq Li "struct fpreg"
-(defined in
-.Aq Pa machine/reg.h )
-pointed to by
-.Fa addr .
-.It Dv PT_SYSCALL
-This request is like
-.Dv PT_CONTINUE
-except that the process will stop next time it executes any system
-call.  Information about the system call can be examined with
-.Dv PT_READ_U
-and potentially modified with
-.Dv PT_WRITE_U
-through the
-.Li u_kproc.kp_proc.p_md
-element of the user structure (see below).  If the process is continued
-with another
-.Dv PT_SYSCALL
-request, it will stop again on exit from the syscall, at which point
-the return values can be examined and potentially changed.  The
-.Li u_kproc.kp_proc.p_md
-element is of type
-.Dq Li "struct mdproc" ,
-which should be declared by including
-.Aq Pa sys/param.h ,
-.Aq Pa sys/user.h ,
-and
-.Aq Pa machine/proc.h ,
-and contains the following fields (among others):
-.Bl -item -compact -offset indent
-.It
-.Li syscall_num
-.It
-.Li syscall_nargs
-.It
-.Li syscall_args[8]
-.It
-.Li syscall_err
-.It
-.Li syscall_rv[2]
-.El
-When a process stops on entry to a syscall,
-.Li syscall_num
-holds the number of the syscall,
-.Li syscall_nargs
-holds the number of arguments it expects, and
-.Li syscall_args
-holds the arguments themselves.  (Only the first
-.Li syscall_nargs
-elements of
-.Li syscall_args
-are guaranteed to be useful.)  When a process stops on exit from a
-syscall,
-.Li syscall_num
-is
-.Eo \&
-.Li -1
-.Ec ,
-.Li syscall_err
-holds the error number
-.Po
-see
-.Xr errno 2
-.Pc ,
-or 0 if no error occurred, and
-.Li syscall_rv
-holds the return values.  (If the syscall returns only one value, only
-.Li syscall_rv[0]
-is useful.)  The tracing process can modify any of these with
-.Dv PT_WRITE_U ;
-only some modifications are useful.
-.Pp
-On entry to a syscall,
-.Li syscall_num
-can be changed, and the syscall actually performed will correspond to
-the new number (it is the responsibility of the tracing process to fill
-in
-.Li syscall_args
-appropriately for the new call, but there is no need to modify
-.Eo \&
-.Li syscall_nargs
-.Ec ).
-If the new syscall number is 0, no syscall is actually performed;
-instead,
-.Li syscall_err
-and
-.Li syscall_rv
-are passed back to the traced process directly (and therefore should be
-filled in).  If the syscall number is otherwise out of range, a dummy
-syscall which simply produces an
-.Er ENOSYS
-error is effectively performed.
-.Pp
-On exit from a syscall, only
-.Li syscall_err
-and
-.Li syscall_rv
-can usefully be changed; they are set to the values returned by the
-syscall and will be passed back to the traced process by the normal
-syscall return mechanism.
 .El
 .Sh ERRORS
 Some requests can cause
@@ -306,14 +157,13 @@ can be set to 0 before the call and checked afterwards.  The possible
 errors are:
 .Bl -tag -width 4n
 .It Bq Er ESRCH
+.Bl -bullet -compact
+.It
 No process having the specified process ID exists.
+.El
 .It Bq Er EINVAL
 .Bl -bullet -compact
 .It
-A process attempted to use
-.Dv PT_ATTACH
-on itself.
-.It
 The
 .Fa request
 was not one of the legal requests.
@@ -331,65 +181,16 @@ The signal number (in
 .Fa data )
 to
 .Dv PT_CONTINUE
-or
-.Dv PT_SYSCALL
 was neither 0 nor a legal signal number.
-.It
-.Dv PT_GETREGS ,
-.Dv PT_SETREGS ,
-.Dv PT_GETFPREGS ,
-or
-.Dv PT_SETFPREGS
-was attempted on a process with no valid register set.  (This is
-normally true only of system processes.)
-.El
-.It Bq Er EBUSY
-.Bl -bullet -compact
-.It
-.Dv PT_ATTACH
-was attempted on a process that was already being traced.
-.It
-A request attempted to manipulate a process that was being traced by
-some process other than the one making the request.
-.It
-A request (other than
-.Dv PT_ATTACH )
-specified a process that wasn't stopped.
 .El
 .It Bq Er EPERM
 .Bl -bullet -compact
 .It
-A request (other than
-.Dv PT_ATTACH )
+A request
 attempted to manipulate a process that wasn't being traced at all.
-.It
-An attempt was made to use
-.Dv PT_ATTACH
-on a process in violation of the requirements listed under
-.Dv PT_ATTACH
-above.
 .El
-.Sh BUGS
-On the SPARC, the PC is set to the provided PC value for
-.Dv PT_CONTINUE
-and similar calls, but the NPC is set willy-nilly to 4 greater than the
-PC value.  Using
-.Dv PT_GETREGS
-and
-.Dv PT_SETREGS
-to modify the PC, passing
-.Li (caddr_t)1
-to
-.Eo \&
-.Fn ptrace
-.Ec ,
-should be able to sidestep this.
-.Pp
-Single-stepping is not available.
-.Pp
-When using
-.Dv PT_SYSCALL ,
-there is no easy way to tell whether the traced process stopped because
-it made a syscall or because a signal was sent at a moment that it just
-happened to have valid-looking garbage in its
-.Dq Li "struct mdproc" .
+.Sh SEE ALSO
+.Xr sigaction 2
+.Xr wait 2
+.Xr execve 2
+.Xr execv 3