diff options
author | nate <nate@FreeBSD.org> | 1996-01-20 17:56:06 +0000 |
---|---|---|
committer | nate <nate@FreeBSD.org> | 1996-01-20 17:56:06 +0000 |
commit | 4828417ff5a81da7a9c824f25ce0a3a29d7367ee (patch) | |
tree | 8ac6da5ae74df5dcb0d00b39668eda476cfe4f0c /lib/libc/sys/ptrace.2 | |
parent | 8a475453bc76ca311e108edfd8d01e13280b1a62 (diff) | |
download | FreeBSD-src-4828417ff5a81da7a9c824f25ce0a3a29d7367ee.zip FreeBSD-src-4828417ff5a81da7a9c824f25ce0a3a29d7367ee.tar.gz |
- FreeBSD'ized the ptrace manpage by removing non-FreeBSD specific portions.
- install ptrace.2
Diffstat (limited to 'lib/libc/sys/ptrace.2')
-rw-r--r-- | lib/libc/sys/ptrace.2 | 223 |
1 files changed, 12 insertions, 211 deletions
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 |