Standard C Library Functions ptrace(3C)
NAME
ptrace - allows a parent process to control the execution of
a child process
SYNOPSIS
#include
#include
int ptrace(int request, pidt pid, int addr, int data);
DESCRIPTION
The ptrace() function allows a parent process to control the
execution of a child process. Its primary use is for the
implementation of breakpoint debugging. The child process
behaves normally until it encounters a signal (see
signal.h(3HEAD)), at which time it enters a stopped state
and its parent is notified by the wait(3C) function. 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(3C)). 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. These two
SunOS 5.11 Last change: 22 Mar 2004 1
Standard C Library Functions ptrace(3C)
requests fail if addr is not the start address of a
word, in which case -1 is returned to the parent
process and the parent's errno is set to EIO.
3 With this request, the word at location addr in the
child's user area in the system's address space (see
) is returned to the parent process. The
data argument is ignored. This request fails if addr
is not the start address of a word or is outside the
user area, in which case -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. These two requests fail if addr is not
the start address of a word. On failure -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, all pending signals
including the one that caused the child to stop are
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 argu-
ment must be equal to 1 for this request. On suc-
cess, the value of data is returned to the parent.
This request fails if data is not 0 or a valid sig-
nal number, in which case -1 is returned to the
parent process and the parent's errno is set to EIO.
SunOS 5.11 Last change: 22 Mar 2004 2
Standard C Library Functions ptrace(3C)
8 This request causes the child to terminate with the
same consequences as exit(2).
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 an interrupt 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 calls to one of the exec fam-
ily of functions (see exec(2)). If a traced process calls
one of these functions, it stops before executing the first
instruction of the new image showing signal SIGTRAP.
ERORS
The ptrace() function will fail if:
EIO The request argument is an illegal number.
EPERM The calling process does not have appropriate
privileges to control the calling process. See
proc(4).
ESRCH The pid argument identifies a child that does not
exist or has not executed a ptrace() call with
request 0.
USAGE
The ptrace() function is available only with the 32-bit ver-
sion of libc(3LIB). It is not available with the 64-bit ver-
sion of this library.
The /proc debugging interfaces should be used instead of
ptrace(), which provides quite limited debugger support and
is itself implemented using the /proc interfaces. There is
no actual ptrace() system call in the kernel. See proc(4)
for descriptions of the /proc debugging interfaces.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 22 Mar 2004 3
Standard C Library Functions ptrace(3C)
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Standard
MT-Level MT-Safe
SEE ALSO
exec(2), exit(2), libc(3LIB), signal(3C), signal.h(3HEAD),
wait(3C), proc(4), attributes(5)
SunOS 5.11 Last change: 22 Mar 2004 4
|
