ptrace(S)
ptrace --
process trace
Synopsis
#include <unistd.h>
#include <sys/types.h>
#include <ptrace.h>
int ptrace(int request, pid_t pid, int addr, int data);
Description
ptrace allows a parent process
to control the execution of a child process.
ptrace is obsolete and will be removed in a future release;
the /proc filesystem
[see
proc(F)]
provides a cleaner and more powerful interface
for one process to control another.
In this release, ptrace is emulated using /proc.
The ``user area'' accessed by requests 3 and 6
is an artificial one described in ptrace.h.
Previous releases used the kernel's internal struct user
from sys/user.h.
When ptrace is used,
the child process behaves normally until it encounters a signal
[see
signal(M)],
at which time it enters a stopped state and its parent is notified via the
wait(S)
system call.
When the child is in the stopped state,
its parent can examine and modify its ``core image'' using ptrace.
Also, the parent can cause the child either to terminate
or continue, with the possibility of ignoring the signal that caused it to
stop.
The request argument determines the action to be taken by ptrace
and is one of the following:
0-
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
func
[see
signal(S)].
The
pid,
addr,
and
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.
The remainder of the requests can only be used by the parent process.
For each, pid is the process ID of the child.
The child must be in a stopped state before these requests are made.
1, 2-
With these requests, the word at location
addr
in the address space of the child is returned to the parent process.
If instruction and data space are separated, request
1
returns a word from instruction space, and request
2
returns a word from data space.
If instruction and data space are not separated,
either request 1 or request 2
may be used with equal results.
The data argument is ignored.
3-
With this request, the word at location
addr
in the child's ``user area''
[see ptrace.h]
is returned to the parent process.
The data argument is ignored.
This request fails if
addr
is outside the user area,
in which case a value of -1 is returned to the parent process and
the parent's errno is set to EIO.
4, 5-
With these requests, the value given by the
data
argument is written into the address space of the child at location
addr.
If instruction and data
space are separated,
request 4 writes a word into instruction space, and
request 5 writes a word into data space.
If instruction and data space are not separated,
either request 4 or request 5 may be used with equal results.
On success, the value written into the address space of the
child is returned to the parent.
On failure a value of -1 is returned to the parent
process and the parent's errno is set to EIO.
6-
With this request, a few entries in the child's
user area can be written.
data gives the value that is to be written and
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.
7-
This request causes the child to resume execution.
If the data
argument is 0, the signal that caused the child to stop
is canceled before it resumes execution.
If the 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 addr argument must be equal to 1 for this request.
On success, the value of data is returned to the parent.
This request fails if 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 errno is set to EIO.
8-
This request causes the child to terminate with the same consequences as
exit(S).
9-
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
7.
The trace bit causes a SIGTRAP signal
on completion of one machine instruction.
This effectively allows single stepping of the child.
To forestall possible fraud, ptrace
inhibits the set-user-ID facility
on subsequent
exec(S)
calls.
If a traced process calls
exec(S),
it stops before executing the first instruction of the new image
showing signal SIGTRAP.
Return values
Upon successful completion, return values are specific
to the request type.
Upon failure, the ptrace returns a
value of -1 and sets errno to indicate an error.
Errors
In the following conditions, ptrace fails and sets errno to:
EIO-
request is an illegal number.
ESRCH-
pid identifies a child that does not exist or has not executed a
ptrace
with request
0.
References
debug(C),
exec(S),
proc(F),
signal(S),
wait(S)
© 2005 The SCO Group, Inc. All rights reserved.
SCO OpenServer Release 6.0.0 - 01 June 2005