diff options
Diffstat (limited to 'lib/libc/sys/ptrace.2')
-rw-r--r-- | lib/libc/sys/ptrace.2 | 395 |
1 files changed, 0 insertions, 395 deletions
diff --git a/lib/libc/sys/ptrace.2 b/lib/libc/sys/ptrace.2 deleted file mode 100644 index 69477e9796f3a..0000000000000 --- a/lib/libc/sys/ptrace.2 +++ /dev/null @@ -1,395 +0,0 @@ -.\" $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" . |