'\"macro stdmacro
.if n .pH g2.ptrace @(#)ptrace	40.16 of 11/30/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} ptrace 2 "" "\&"
.if \nX=1 .ds x} ptrace 2 ""
.if \nX=2 .ds x} ptrace 2 "" "\&"
.if \nX=3 .ds x} ptrace "" "" "\&"
.TH \*(x}
.SH NAME
\f4ptrace\f1 \- process trace
.SH SYNOPSIS
\f4#include <unistd.h>
.br
\f4#include <sys/types.h>\f1
.PP
\f4int ptrace(int request, pid_t pid, int addr, int data);\f1
.SH DESCRIPTION
\f4ptrace\fP
allows a parent process
to control the execution of a child process.
Its primary use is for the implementation of breakpoint debugging [see
\f4sdb\fP(1)].
The child process behaves normally until it encounters a signal [see
\f4signal\fP(5)], at which time it enters a stopped state
and its parent is notified via the
\f4wait\fP(2) system call.
When the child is in the stopped state,
its parent can examine and modify its ``core image'' using
\f4ptrace\fP.
Also, the parent can cause the child either to terminate
or continue, with the possibility of ignoring the signal that caused it to
stop.
.PP
The
.I request\^
argument determines the action to be taken by
\f4ptrace\fP
and is one of the following:
.RS 2n
.TP
\f40\fP
This request
must be issued by the child process if it is to be traced by its parent.
It turns on the child's trace flag that stipulates that the child should be
left in a stopped state on receipt of
a signal rather than the state specified by
.IR func 
[see
\f4signal\fP(2)].
The
.IR pid ,
.IR addr ,
and
.I data
arguments are ignored, and a return value is not defined for this request.
Peculiar results ensue if the parent does not expect to trace the child.
.RE
.PP
The remainder of the requests can only be used by the parent process.
For each,
.I pid\^
is the process
.SM ID
of the child.
The child must be in a stopped state before these requests are made.
.RS 2n
.TP
\f4\&1, 2\f1
With these requests, the word at location
.I addr\^
in the address space of the child is returned to the parent process.
If instruction and data
space are separated,
request
\f4\&1\f1
returns a word from instruction space, and
request
\f4\&2\f1
returns a word from data space.
If instruction and data
space are not separated,
either request
\f4\&1\f1
or request
\f4\&2\f1
may be used with equal results.
The
.I data\^
argument is ignored.
These two requests fail if
.I addr\^
is not the start address of a word, in which case a value of \-1 is
returned to the parent process and the parent's
\f4errno\fP
is set to
\f4EIO\fP.
.TP
\f4\&3\f1
With this request, the word at location
.I addr\^
in the child's
user
area in the system's address space [see
\f4<sys/user.h>\f1]
is returned to the parent process.
The
.I data\^
argument is ignored.
This request fails if
.I addr\^
is not the start address of a word or is outside the
user
area, in which case a value of \-1 is returned to the parent process and
the parent's
\f4errno\fP
is set to
\f4EIO\fP.
.TP
\f4\&4, 5\f1
With these requests, the value given by the
.I data\^
argument is written into the address space of the child at location
.IR addr .
If instruction and data
space are separated,
request \f4\&4\f1 writes a word into instruction space, and
request \f4\&5\f1 writes a word into data space.
If instruction and data
space are not separated,
either request \f4\&4\f1 or request \f4\&5\f1 may be used with equal results.
On success, the value written into the address space of the
child is returned to the parent.
These two requests fail if
.I addr\^
is not the start address of a word.
On failure a value of \-1 is returned to the parent
process and the parent's
\f4errno\fP
is set to
\f4EIO\fP.
.TP
\f4\&6\f1
With this request, a few entries in the child's
user
area can be written.
.I data\^
gives the value that is to be written and
.I addr\^
is the location of the entry.
The few entries that can be written are
the general registers and
the condition codes of the Processor Status Word.
.TP
\f4\&7\f1
This request causes the child to resume execution.
If the
.I data\^
argument is 0, all pending signals including the one that caused the child to
stop are canceled before it resumes execution.
If the
.I data\^
argument is a valid signal number, the child resumes execution as if it had
incurred that signal, and any other pending signals are canceled.
The
.I addr\^
argument must be equal to 1 for this request.
On success, the  value of
.I data\^
is returned to the parent.
This request fails if
.I data\^
is not 0 or a valid signal number, in which case a value of \-1 is returned
to the parent process and the parent's
\f4errno\fP
is set to
\f4EIO\fP.
.TP
\f4\&8\f1
This request causes the child to terminate with the same consequences as
\f4exit\fP(2).
.TP
\f4\&9\f1
This request sets the trace bit in the Processor Status Word of the child
and then executes the same
steps as listed above for request
\f4\&7\f1.
The trace bit causes an interrupt on completion of one machine instruction.
This effectively allows single stepping of the child.
.RE
.PP
To forestall possible fraud,
\f4ptrace\fP
inhibits the set-user-\s-1ID\s0 facility
on subsequent
\f4exec\fP(2)
calls.
If a traced process calls
\f4exec\fP(2),
it stops before executing the first instruction of the new image
showing signal
\f4SIGTRAP\f1.
\f4ptrace\fP
in general fails if one or more of the following are true:
.RS 2n
.TP 10
\f4EIO\fP
.I request\^
is an illegal number.
.TP
\f4ESRCH\fP
.I pid\^
identifies a child that does not exist or has not executed a
\f4ptrace\fP
with request
\f4\&0\f1.
.TP
\f4EPERM\fP
the involking subject does not have the appropriate MAC privilages.
.RE
.SH SEE ALSO
\f4sdb\fP(1), \f4exec\fP(2), \f4signal\fP(2), \f4wait\fP(2).
.\"	@(#)ptrace.2	6.3 of 4/2/84
.Ee
