diff options
author | nate <nate@FreeBSD.org> | 1996-01-20 17:35:25 +0000 |
---|---|---|
committer | nate <nate@FreeBSD.org> | 1996-01-20 17:35:25 +0000 |
commit | c041eb5d460a2a1603be7bf35c3bb6435af49701 (patch) | |
tree | 57d85ba786703fc9e51515d5bc178a594909c03b /lib/libc/sys/ptrace.2 | |
parent | adc7000016eb37741d426b9e5362a1894b12093a (diff) | |
download | FreeBSD-src-c041eb5d460a2a1603be7bf35c3bb6435af49701.zip FreeBSD-src-c041eb5d460a2a1603be7bf35c3bb6435af49701.tar.gz |
ptrace(2) manpage
Diffstat (limited to 'lib/libc/sys/ptrace.2')
-rw-r--r-- | lib/libc/sys/ptrace.2 | 395 |
1 files changed, 395 insertions, 0 deletions
diff --git a/lib/libc/sys/ptrace.2 b/lib/libc/sys/ptrace.2 new file mode 100644 index 0000000..69477e9 --- /dev/null +++ b/lib/libc/sys/ptrace.2 @@ -0,0 +1,395 @@ +.\" $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 +.Dt PTRACE 2 +.Os NetBSD 1.0BETA +.Sh NAME +.Nm ptrace +.Nd process tracing and debugging +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <sys/ptrace.h> +.Ft int +.Fn ptrace "int request" "pid_t pid" "caddr_t addr" "int data" +.Sh DESCRIPTION +.Fn ptrace +provides tracing and debugging facilities. It allows one process (the +.Em tracing +process) to control another (the +.Em traced +process). Most of the time, the traced process runs normally, but when +it receives a signal +.Po +see +.Xr sigaction 2 +.Pc , +it stops. The tracing process is expected to notice this via +.Xr wait 2 +or the delivery of a +.Dv SIGCHLD +signal, examine the state of the stopped process, and cause it to +terminate or continue as appropriate. +.Fn ptrace +is the mechanism by which all this happens. +.Pp +The +.Fa request +argument 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 +calls are made by the tracing process, and the +.Fa pid +argument specifies the process ID of the traced process. +.Fa request +can be: +.Bl -tag -width 12n +.It Dv PT_TRACE_ME +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 +the child, it will probably be rather confused by the results; once the +traced process stops, it cannot be made to continue except via +.Eo \& +.Fn ptrace +.Ec \&.) +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. +.It Dv PT_READ_I , Dv PT_READ_D +These requests read a single +.Li int +of data from the traced process' address space. Traditionally, +.Fn ptrace +has allowed for machines with distinct address spaces for instruction +and data, which is why there are two requests: conceptually, +.Dv PT_READ_I +reads from the instruction space and +.Dv PT_READ_D +reads from the data space. In the current NetBSD implementation, these +two requests are completely identical. The +.Fa addr +argument specifies the address (in the traced process' virtual address +space) at which the read is to be done. This address does not have to +meet any alignment constraints. The value read is returned as the +return value from +.Eo \& +.Fn ptrace +.Ec . +.It Dv PT_WRITE_I , Dv PT_WRITE_D +These requests parallel +.Dv PT_READ_I +and +.Dv PT_READ_D , +except that they write rather than read. The +.Fa data +argument supplies the value to be written. +.It Dv PT_READ_U +This request reads an +.Li int +from the traced process' user structure. The +.Fa addr +argument specifies the location of the int relative to the base of the +user structure; it will usually be an integer value cast to +.Li caddr_t +either explicitly or via the presence of a prototype for +.Eo \& +.Fn ptrace +.Ec . +Unlike +.Dv PT_READ_I +and +.Dv PT_READ_D , +.Fa addr +must be aligned on an +.Li int +boundary. The value read is returned as the return value from +.Eo \& +.Fn ptrace +.Ec . +.It Dv PT_WRITE_U +This request writes an +.Li int +into the traced process' user structure. +.Fa addr +specifies the offset, just as for +.Dv PT_READ_U , +and +.Fa data +specifies the value to be written, just as for +.Dv PT_WRITE_I +and +.Dv PT_WRITE_D . +.It Dv PT_CONTINUE +The traced process continues execution. +.Fa addr +is an address specifying the place where execution is to be resumed (a +new value for the program counter), or +.Li (caddr_t)1 +to indicate that execution is to pick up where it left off. +.Fa data +provides a signal number to be delivered to the traced process as it +resumes execution, or 0 if no signal is to be sent. +.It Dv PT_KILL +The traced process terminates, as if +.Dv PT_CONTINUE +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 +.Fn ptrace +to return +.Li -1 +as a non-error value; to disambiguate, +.Va errno +can be set to 0 before the call and checked afterwards. The possible +errors are: +.Bl -tag -width 4n +.It Bq Er ESRCH +No process having the specified process ID exists. +.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. +.It +The +.Fa addr +to +.Dv PT_READ_U +or +.Dv PT_WRITE_U +was not +.Li int Ns \&-aligned. +.It +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 ) +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" . |