diff options
Diffstat (limited to 'lib/libc/sys/ptrace.2')
| -rw-r--r-- | lib/libc/sys/ptrace.2 | 330 |
1 files changed, 330 insertions, 0 deletions
diff --git a/lib/libc/sys/ptrace.2 b/lib/libc/sys/ptrace.2 new file mode 100644 index 0000000..7b08791 --- /dev/null +++ b/lib/libc/sys/ptrace.2 @@ -0,0 +1,330 @@ +.\" $FreeBSD$ +.\" $NetBSD: ptrace.2,v 1.2 1995/02/27 12:35:37 cgd Exp $ +.\" +.\" This file is in the public domain. +.Dd January 20, 1996 +.Dt PTRACE 2 +.Os +.Sh NAME +.Nm ptrace +.Nd process tracing and debugging +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In 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 +(see +.Xr sigaction 2 ) , +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 +.Fn ptrace . ) +When a process has used this request and calls +.Xr execve 2 +or any of the routines built on it +(such as +.Xr execv 3 ) , +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 +.Vt int +of data from the traced process's 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 +.Fx +implementation, these two requests are completely identical. +The +.Fa addr +argument specifies the address +(in the traced process's 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 +.Fn ptrace . +.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_IO +This request allows reading and writing arbitrary amounts of data in +the traced process's address space. +The +.Fa addr +argument specifies a pointer to a +.Vt "struct ptrace_io_desc" , +which is defined as follows: +.Bd -literal +struct ptrace_io_desc { + int piod_op; /* I/O operation */ + void *piod_offs; /* child offset */ + void *piod_addr; /* parent offset */ + size_t piod_len; /* request length */ +}; + +/* + * Operations in piod_op. + */ +#define PIOD_READ_D 1 /* Read from D space */ +#define PIOD_WRITE_D 2 /* Write to D space */ +#define PIOD_READ_I 3 /* Read from I space */ +#define PIOD_WRITE_I 4 /* Write to I space */ +.Ed +.Pp +The +.Fa data +argument is ignored. +The actual number of bytes read or written is stored in +.Va piod_len +upon return. +.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 +.Po Vt caddr_t Pc Ns 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_STEP +The traced process is single stepped one instruction. +.Fa addr +should be passed +.Po Vt caddr_t Pc Ns 1 . +.Fa data +is not used. +.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. +.It Dv PT_GETREGS +This request reads the traced process's machine registers into the +.Do +.Vt "struct reg" +.Dc +(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's machine registers from the +.Do +.Vt "struct reg" +.Dc +(defined in +.Aq Pa machine/reg.h ) +pointed to by +.Fa addr . +.It Dv PT_GETFPREGS +This request reads the traced process's floating-point registers into +the +.Do +.Vt "struct fpreg" +.Dc +(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's floating-point registers from the +.Do +.Vt "struct fpreg" +.Dc +(defined in +.Aq Pa machine/reg.h ) +pointed to by +.Fa addr . +.It Dv PT_GETDBREGS +This request reads the traced process's debug registers into +the +.Do +.Vt "struct dbreg" +.Dc +(defined in +.Aq Pa machine/reg.h ) +pointed to by +.Fa addr . +.It Dv PT_SETDBREGS +This request is the converse of +.Dv PT_GETDBREGS ; +it loads the traced process's debug registers from the +.Do +.Vt "struct dbreg" +.Dc +(defined in +.Aq Pa machine/reg.h ) +pointed to by +.Fa addr . +.El +.Pp +Additionally, machine-specific requests can exist. +.Sh RETURN VALUES +Some requests can cause +.Fn ptrace +to return +\-1 +as a non-error value; to disambiguate, +.Va errno +can be set to 0 before the call and checked afterwards. +.Sh ERRORS +The +.Fn ptrace +function may fail if: +.Bl -tag -width Er +.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. +.It +The signal number +(in +.Fa data ) +to +.Dv PT_CONTINUE +was neither 0 nor a legal signal number. +.It +.Dv PT_GETREGS , +.Dv PT_SETREGS , +.Dv PT_GETFPREGS , +.Dv PT_SETFPREGS , +.Dv PT_GETDBREGS , +or +.Dv PT_SETDBREGS +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 +.El +.Sh SEE ALSO +.Xr execve 2 , +.Xr sigaction 2 , +.Xr wait 2 , +.Xr execv 3 , +.Xr i386_clr_watch 3 , +.Xr i386_set_watch 3 +.Sh HISTORY +A +.Fn ptrace +function call appeared in +.At v7 . |
