1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
|
.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
.\" Copyright (c) 1993 Michael Haardt
.\" (u31b3hs@pool.informatik.rwth-aachen.de),
.\" Fri Apr 2 11:32:09 MET DST 1993
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
.\" USA.
.\"
.\" Modified Fri Jul 23 23:47:18 1993 by Rik Faith <faith@cs.unc.edu>
.\" Modified Fri Jan 31 16:46:30 1997 by Eric S. Raymond <esr@thyrsus.com>
.\"
.TH PTRACE 2 "23 July 1993" "Linux 0.99.11" "Linux Programmer's Manual"
.SH NAME
ptrace \- process trace
.SH SYNOPSIS
.B #include <sys/ptrace.h>
.sp
.BI "int ptrace(int " request ", int " pid ", int " addr ", int " data );
.SH DESCRIPTION
.B 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
.BR 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.
.LP
The value of the \fIrequest\fP argument determines the precise action of
the system call:
.TP
PTRACE_TRACEME
This process is to be traced by its parent. The parent should be expecting to
trace the child.
.TP
PTRACE_PEEKTEXT, PTRACE_PEEKDATA
Read word at location
.IR addr .
.TP
PTRACE_PEEKUSR
Read word at location
.I addr
in the
.B USER
area.
.TP
PTRACE_POKETEXT, PTRACE_POKEDATA
Write word at location
.IR addr .
.TP
PTRACE_POKEUSR
Write word at location
.I addr
in the
.B USER
area.
.TP
PTRACE_SYSCALL, PTRACE_CONT
Restart after signal.
.TP
PTRACE_KILL
Send the child a
.B SIGKILL
to make it exit.
.TP
PTRACE_SINGLESTEP
Set the trap flag for single stepping.
.TP
PTRACE_ATTACH
Attach to the process specified in
.IR pid .
.TP
PTRACE_DETACH
Detach a process that was previously attached.
.SH NOTES
.BR init ,
the process with process ID 1, may not use this function.
.SH "RETURN VALUE"
On success, zero is returned. On error, \-1 is returned, and
.I errno
is set appropriately.
.SH ERRORS
.TP 0.8i
.B EPERM
The specified process (i.e.,
.BR init ),
cannot be traced, or is already being traced.
.TP
.B ESRCH
The specified process does not exist.
.TP
.B EIO
.I Request
is not valid.
.SH "CONFORMING TO"
SVr4, SVID EXT, AT&T, X/OPEN, BSD 4.3
.SH "SEE ALSO"
.BR gdb (1),
.BR exec (3),
.BR signal (2),
.BR wait (2)
|
