PTRACE
Section: Linux Programmer's Manual (2)
Updated: 23 July 1993
Index
Return to Main Contents
NAME
ptrace - process trace
SYNOPSIS
#include <sys/ptrace.h>
int ptrace(int request, int pid, int addr, int data);
DESCRIPTION
Ptrace
provides a means by which a parent process may control the execution of a
child process, and examine and change its core image. Its primary use is
for the implementation of breakpoint debugging. A traced process runs
until a signal occurs. Then it stops and the parent will be notified with
wait(2).
When the process is in the stopped state, its memory can be read and
written. The parent can also cause the child to continue execution, with
optional ignoring the signal which caused stopping.
The value of the request argument determines the precise action of
the system call:
- PTRACE_TRACEME
-
This process is to be traced by its parent. The parent should be expecting to
trace the child.
- PTRACE_PEEKTEXT, PTRACE_PEEKDATA
-
Read word at location
addr.
- PTRACE_PEEKUSR
-
Read word at location
addr
in the
USER
area.
- PTRACE_POKETEXT, PTRACE_POKEDATA
-
Write word at location
addr.
- PTRACE_POKEUSR
-
Write word at location
addr
in the
USER
area.
- PTRACE_SYSCALL, PTRACE_CONT
-
Restart after signal.
- PTRACE_KILL
-
Send the child a
SIGKILL
to make it exit.
- PTRACE_SINGLESTEP
-
Set the trap flag for single stepping.
- PTRACE_ATTACH
-
Attach to the process specified in
pid.
- PTRACE_DETACH
-
Detach a process that was previously attached.
NOTES
init,
the process with process ID 1, may not use this function.
RETURN VALUE
On success, zero is returned. On error, -1 is returned, and
errno
is set appropriately.
ERRORS
- EPERM
-
The specified process (i.e.,
init),
cannot be traced, or is already being traced.
- ESRCH
-
The specified process does not exist.
- EIO
-
Request
is not valid.
CONFORMING TO
SVID EXT, AT&T, X/OPEN, BSD 4.3
SEE ALSO
gdb(1), exec(2), signal(2), wait(2)
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- NOTES
-
- RETURN VALUE
-
- ERRORS
-
- CONFORMING TO
-
- SEE ALSO
-
This document was created by
man2html,
using the manual pages.
Time: 12:25:08 GMT, March 22, 2025