.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
.\" Copyright (c) 1993 Michael Haardt
.\" (michael@moria.de),
.\" Fri Apr  2 11:32:09 MET DST 1993
.\"
.\" changes Copyright 1999 Mike Coleman (mkc@acm.org)
.\" -- major revision to fully document ptrace semantics per recent Linux
.\"    kernel (2.2.10) and glibc (2.1.2)
.\" Sun Nov  7 03:18:35 CST 1999
.\"
.\" 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., 59 Temple Place, Suite 330, Boston, MA 02111,
.\" 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>
.\" Modified Thu Oct  7 17:28:49 1999 by Andries Brouwer <aeb@cwi.nl>
.\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
.\"     Added notes on capability requirements
.\"
.\" 2006-03-24, Chuck Ebbert <76306.1226@compuserve.com>
.\"    Added    PTRACE_SETOPTIONS, PTRACE_GETEVENTMSG, PTRACE_GETSIGINFO,
.\"        PTRACE_SETSIGINFO, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP
.\"    (Thanks to Blaisorblade, Daniel Jacobowitz and others who helped.)
.\"
.\" Japanese Version Copyright (c) 1997-1999 HANATAKA Shinya
.\"         all rights reserved.
.\" Translated 1999-11-20, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
.\" Updated 2003-10-11, Kentaro Shirakata <argrath@ub32.org>
.\" Updated 2006-07-23, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.28
.\" Updated 2007-01-07, Akihiro MOTOKI, LDP v2.43
.\" Updated 2007-05-01, Akihiro MOTOKI, LDP v2.46
.\"
.\"WORD:	child process		ҥץ
.\"WORD:	parent process		ƥץ
.\"WORD:	core image		ꡦ᡼
.\"WORD:	break point		֥졼ݥ
.\"WORD:	single step		󥰥롦ƥå׼¹
.\"WORD:	trap flag		ȥåסե饰
.\"WORD:	attach			³
.\"WORD:	detach			ʬΥ
.\"WORD:	process ID		ץID
.\"
.TH PTRACE 2 2007-11-15 "Linux" "Linux Programmer's Manual"
.SH ̾
ptrace \- ץΥȥ졼
.SH 
.nf
.B #include <sys/ptrace.h>
.sp
.BI "long ptrace(enum __ptrace_request " request ", pid_t " pid ", "
.BI "            void *" addr ", void *" data );
.fi
.SH 
.BR ptrace ()
ƥॳϡƥץ̤Υץμ¹Ԥδƻ/
Ԥäꡢ᡼ (core image) 쥸Ĵ/ѹ
Ԥäꤹʤ󶡤롣
.BR ptrace ()
ϡ˥֥졼ݥȤˤǥХå䥷ƥॳΥȥ졼
ΤѤ롣
.LP
ȥ졼򳫻Ϥˤϡޤƥץ
.BR fork (2)
ƤӽФ줿ҥץ
.B PTRACE_TRACEME
Ԥ³ (ŵŪˤ)
.BR exec (3)
Ԥʤ
̤ˡȤƤϡ
ƥץ¸ΥץФ
.B PTRACE_ATTACH
Ѥȥ졼򳫻Ϥ롣
.LP
ȥ졼μ¹桢ҥץϥʥ뤬뤿Ӥˡ
ȤΥʥ뤬̵뤹٤ΤǤäƤߤ
.RB ( SIGKILL
㳰ǡ̾ɤθ̤⤿餹)
ƥץˤϼ
.BR wait (2)
Τ졢ߤƤ֤˻ҥץĴ٤꽤ꤹ뤳ȤǤ롣
ƿƥץϻҥץμ¹ԤƳ뤬줿
ʥ̵뤹뤳ȤǤ (뤤̤Υʥ
뤳ȤǤ) 
.LP
ƥץȥ졼λݤˤϡ
.B PTRACE_KILL
Ѥƻҥץλ뤳ȤǤ뤷
.B PTRACE_DETACH
Ѥ̾Υȥ졼ʤΥ⡼ɤˤơ
¹Ԥ³뤳ȤǤ롣
.LP
\fIrequest\fP ͤΥƥॳưꤹ:
.TP
.B PTRACE_TRACEME
Υץƥץˤäƥȥ졼뤳Ȥɽ
Υץ
.RB ( SIGKILL
ʳ) ʥ뤬ȡ
ץߤƥץ
.BR wait (2)
̤Τ롣
ޤʹߤϤΥץ
.BR execve (2)
ƤӽФ٤
.B SIGTRAP
褦ˤʤ롣
ˤäơƥץ
ץब¹Ԥ򳫻Ϥ椹뤳ȤǤ롣
ƥץץȥ졼Ĥ꤬ʤˤϡ
餯Υץ׵Ԥ٤ǤϤʤ
(\fIpid\fP, \fIaddr\fP, \fIdata\fP ̵뤵롣)
.LP
嵭׵ϻҥץԤʤΤǤ롣
ĤϿƥץԤʤΤǤ롣
ʲ׵Ǥϡ\fIpid\fP оݤȤʤ
ҥץꤹ롣
.B PTRACE_KILL
׵Ԥʤˤ
ҥץߤƤʤФʤʤ
.TP
.BR PTRACE_PEEKTEXT ", " PTRACE_PEEKDATA
ҥץΥ
.I addr
ΰ֤ 1 ɤɤ߽Фɤ߽Фɤ
.BR ptrace ()
֤ͤȤ֤롣 Linux Ǥϥƥ (text) ȥǡ (data) 
Ʊɥ쥹֤Ѥ뤿ᡢ 2 Ĥ׵ϸߤΤȤ
ƱΤǤ롣 ( \fIdata\fP ̵뤵롣)
.TP
.B PTRACE_PEEKUSER
.\" PTRACE_PEEKUSR in kernel source, but glibc uses PTRACE_PEEKUSER,
.\" and that is the name that seems common on other systems.
ҥץ USER ΰΥեå
.I addr
ΰ֤ 1 ɤɤ߹ࡣUSER ΰˤϤΥץ
쥸 (registers) ʤɤξݻƤ롣
(\fI<linux/user.h>\fP  \fI<sys/user.h>\fP
򻲾)ɤ߹ɤ
.BR ptrace ()
η̤Ȥ֤롣
ƤϥեåȤϥɶˤʤФʤʤ
ƥˤäƤϤɬפϤʤ
(\fIdata\fP ̵뤵롣 )
.TP
.BR PTRACE_POKETEXT ", " PTRACE_POKEDATA

.I data
ҥץΥ
.I addr
ΰ֤إԡ롣ƱͤˡߤΤȤĤ
׵ƱΤǤ롣
.TP
.B PTRACE_POKEUSER
.\" PTRACE_POKEUSR in kernel source, but glibc uses PTRACE_POKEUSER,
.\" and that is the name that seems common on other systems.

.I data
ҥץ USER ΰΥեå
.I addr
ΰ֤˥ԡ롣
Ʊͤˡ̾եåȤϥɶˤʤФʤʤ
ͥδ (integrity) ݻ뤿ᡢ
ѹƤˤäƤ USER ΰѹ϶ػߤƤ롣
.TP
.BR PTRACE_GETREGS ", " PTRACE_GETFPREGS
줾졢ҥץѥ쥸ư쥸ƥץ
\fIdata\fP ΰ֤˥ԡ롣 data ν񼰤˴ؤƤ
\fI<linux/user.h>\fP 򻲾Ȥ뤳ȡ(\fIaddr\fP ̵뤵롣)
.TP
.BR PTRACE_GETSIGINFO " (Linux 2.3.99-pre6 ʹ)"
ߤθȤʤäʥ˴ؤ롣
\fIsiginfo_t\fP ¤
.RB ( sigaction (2)
) ҥץƥץ \fIdata\fP ΰ֤˥ԡ롣
(\fIaddr\fP ̵뤵롣)
.TP
.BR PTRACE_SETREGS ", " PTRACE_SETFPREGS
줾졢ҥץѥ쥸ư쥸
ƥץ \fIdate\fP ΰ֤饳ԡ롣
.B PTRACE_POKEUSER
Ʊͤˡѥ쥸ˤäƤ
ѹػߤƤ礬롣 (\fIaddr\fP ̵뤵롣)
.TP
.BR PTRACE_SETSIGINFO " (Linux 2.3.99-pre6 ʹ)"
ʥꤹ롣
\fIsiginfo_t\fP ¤ΤƥץΥǡ \fIdata\fP ΰ֤
ҥץ˥ԡ롣
νԤȤǤΤϡҥץ̾Ϥ
ȥ졼ª줿ʥˤĤƤǤ롣
̾Υʥ
.BR ptrace ()
Ȥȯ륷ʥʬΤ񤷤⤷ʤ
(\fIaddr\fP ̵뤵롣)
.TP
.BR PTRACE_SETOPTIONS " (Linux 2.4.6 ʹ; ХξϤˤٹ⻲)"
ƥץ \fIdata\fP ˴Ť ptrace Υץꤹ
(\fIaddr\fP ̵뤵)
\fIdata\fP ϥץΥӥåȥޥȤƲᤵ졢
ץˤϰʲΥե饰Ǥ:
.RS
.TP
.BR PTRACE_O_TRACESYSGOOD " (Linux 2.4.6 ʹ)"
ƥॳΥȥåפ줿ȤˡʥֹΥӥå 7
ꤹ (ʤ\fI(SIGTRAP | 0x80)\fP )
ˤꡢȥ졼̾Υȥåפȥƥॳˤȥåפ
̤䤹ʤ롣
.RB ( PTRACE_O_TRACESYSGOOD
ϤɤΥƥǤưʤǽ롣)
.TP
.BR PTRACE_O_TRACEFORK " (Linux 2.5.46 ʹ)"

.BR fork (2)
ƤӽФ \fISIGTRAP | PTRACE_EVENT_FORK\ <<\ 8\fP 
ҥץưߤ
 fork 줿ץΥȥ졼ưŪ˳Ϥ
.B SIGSTOP
ǤΥץμ¹Ԥ򳫻Ϥ롣
ץ PID 
.B PTRACE_GETEVENTMSG
ǼǤ롣
.TP
.BR PTRACE_O_TRACEVFORK " (Linux 2.5.46 ʹ)"

.BR vfork (2)
ƤӽФ \fISIGTRAP | PTRACE_EVENT_VFORK\ <<\ 8\fP 
ҥץưߤ
 vfork 줿ץΥȥ졼ưŪ˳Ϥ
.B SIGSTOP
ǤΥץμ¹Ԥ򳫻Ϥ롣
ץ PID 
.B PTRACE_GETEVENTMSG
ǼǤ롣
.TP
.BR PTRACE_O_TRACECLONE " (Linux 2.5.46 ʹ)"

.BR clone (2)
ƤӽФ \fISIGTRAP | PTRACE_EVENT_CLONE\ << \8\fP 
ҥץưߤ
 clone Ǻ줿ץΥȥ졼ưŪ˳Ϥ
.B SIGSTOP
ǥץμ¹Ԥ򳫻Ϥ롣
ץ PID 
.B PTRACE_GETEVENTMSG
ǼǤ롣
ΥץƤ
.BR clone (2)
ޤ櫓ǤϤʤ
ҥץ
.B CLONE_VFORK
ե饰դ
.BR clone (2)
ƤӽФ硢
.B PTRACE_O_TRACEVFORK
ꤵƤ
.B PTRACE_EVENT_VFORK
롣
ޤҥץλʥ
.B SIGCHLD
ꤷ
.BR clone (2)
ƤӽФϡ
.B PTRACE_O_TRACEFORK
ꤵƤ
.B PTRACE_EVENT_FORK
롣
.TP
.BR PTRACE_O_TRACEEXEC " (Linux 2.5.46 ʹ)"

.BR execve (2)
ƤӽФ
\fISIGTRAP | PTRACE_EVENT_EXEC\ <<\ 8\fP
ǻҥץưߤ롣
.TP
.BR PTRACE_O_TRACEVFORKDONE " (Linux 2.5.60 ʹ)"

.BR vfork (2)
ƤӽФ
\fISIGTRAP | PTRACE_EVENT_VFORK_DONE\ <<\ 8\fP
ǻҥץưߤ롣
.TP
.BR PTRACE_O_TRACEEXIT " (Linux 2.5.60 ʹ)"
λ (exit)  \fISIGTRAP | PTRACE_EVENT_EXIT\ <<\ 8\fP
ǻҥץưߤ롣ҥץνλơ
.B PTRACE_GETEVENTMSG
ǼǤ롣
ߤϥ쥸ޤȲǽǤץλν˹Ԥ졢
ȥ졼ϤɤǽλȯΤ뤳ȤǤ롣
̾νλ (exit notification) ϥץνλλ
Ԥ롣ƥȤ򻲾Ȥ뤳ȤϤǤˤؤ餺
ȥ졼Ϥλ齪λߤ뤳ȤϤǤʤ
.RE
.TP
.BR PTRACE_GETEVENTMSG " (Linux 2.5.46 ʹ)"
ȯФ ptrace ٥Ȥ˴ؤå
.RI ( "unsigned long"
) 롣
åϿƥץ \fIdata\fP ΰ֤˳Ǽ롣
Ƥϡ
.B PTRACE_EVENT_EXIT
ξϻҥץνλơǤꡢ
.BR PTRACE_EVENT_FORK ,
.BR PTRACE_EVENT_VFORK ,
.B PTRACE_EVENT_CLONE
ξϿץ PID Ǥ롣
Linux 2.6.18 ʹߤǤϡץ PID 
.B PTRACE_EVENT_VFORK_DONE
Ǥ롣
(\fIaddr\fP ̵뤵롣)
.TP
.B PTRACE_CONT
ߤҥץμ¹ԤƳ롣
\fIdata\fP Ǥʤ
.B SIGSTOP
ǤʤС
ҥץ륷ʥȲᤵ롣

.B SIGSTOP
ξϥʥʤ
Ȥȡ㤨Сƥץ
ҥץ줿ʥºݤ뤫ɤ
椹뤳ȤǤ롣(\fIaddr\fP ̵뤵롣)
.TP
.BR PTRACE_SYSCALL ", " PTRACE_SINGLESTEP
.B PTRACE_CONT
ƱͤߤҥץƳ롣
.B PTRACE_SYSCALL
ξϻҥץ
˥ƥॳ뤫ƥॳ뤫ȴ뤫ˡ
.B PTRACE_SINGLESTEP
ξ 1 ̿ (instruction) ¹Ԥߤ
(̾ɤꡢҥץϥʥäˤߤ)
ƥץ鸫ȡҥץ
.B SIGTRAP
ߤ褦˸롣Τᡢ㤨
.B PTRACE_SYSCALL
Ȥȡ1ܤߤǰĴ٤
.B PTRACE_SYSCALL
¹Ԥ 2ܤߤǥƥॳ֤ͤĴ٤롢
Ȥ褦ʤȤǤ롣(\fIaddr\fP ̵뤵롣)
.TP
.BR PTRACE_SYSEMU ", " PTRACE_SYSEMU_SINGLESTEP " (Linux 2.6.14 ʹ)"
.B PTRACE_SYSEMU
ϡ¹ԤƳΥƥॳߤ롣
ƥॳϼ¹Ԥʤ
.B PTRACE_SYSEMU_SINGLESTEP
ƱͤƥॳǤʤˤ
1 ̿ (singlestep) ¹ԤǤߤ롣
Υ User Mode Linux Τ褦˻ҥץΥƥॳ
ߥ졼Ȥ褦ȤץǻѤ롣
(\fIaddr\fP  \fIdata\fP ̵뤵롣
ƤΥƥǥݡȤƤ櫓ǤϤʤ)
.TP
.B PTRACE_KILL
ҥץ
.B SIGKILL
꽪λ롣(\fIaddr\fP  \fIdata\fP ̵뤵롣)
.TP
.B PTRACE_ATTACH
.I pid
ǻꤵ줿ץ³ (attach) ƤӽФΥץ
ҥץȤƥȥ졼Ǥ褦ˤ롣ҥץ
.B PTRACE_TRACEME
Τ褦˿񤦡ƤӽФΥץϤΤۤȤɤŪˤơ
λҥץμºݤοƤˤʤ (㤨СҥץΥ٥Ȥ
ΤȤäꡢ
.BR ps (1)
ǿƤȤɽ줿ꤹ)ҥץ
.BR getppid (2)
¹Ԥˤϸοƥץ PID ֤롣
ҥץˤ
.B SIGSTOP
뤬θƤӽФλޤǤ
ɬߤȤϸ¤ʤҥץߤԤĤˤ
.BR wait (2)
Ѥ뤳ȡ(\fIaddr\fP  \fIdata\fP ̵뤵롣)
.TP
.B PTRACE_DETACH
.B PTRACE_CONT
ƱͤߤҥץƳ롣
ޤΥץʬΥ (detach) Ԥ
.B PTRACE_ATTACH
ǤοƤڤ괹ˤ̤
.B PTRACE_TRACEME
θ̤äտޤΤǤϤʤ
Linux Ǥϡȥ졼ƤҥץϤɤΤ褦ˡǥȥ졼
Ϥ줿ȤƤ⡢ˡʬΥ (detach) 뤳ȤǤ롣
(\fIaddr\fP ̵뤵롣)
.SH ֤
ȡ
.B PTRACE_PEEK*
ξ׵ᤷǡ֤
ʳξ 0 ֤
顼ξ \-1 ֤
.I errno
Ŭڤꤵ롣
.B PTRACE_PEEK*
֤ͤ⡡\-1 ˤʤ뤳Ȥ뤿ᡢ
Τ褦׵ξˤϡƤӽФ
.I errno
Ĵ١顼ȯΤɤȽǤʤФʤʤ
.SH 顼
.TP
.B EBUSY
(i386 Τ) ǥХå쥸γݤޤϲǥ顼ȯ
.TP
.B EFAULT
ƥץޤϻҥץΥΰɤ߽񤭤褦Ȥ
餯ΰ褬ޥåԥ󥰤Ƥʤ
ΰؤΥƤʤǤ롣
ԱʤȤˡLinux ǤϤΤ褦ʥ顼ξ硢¿쾯ʤ
Ū
.B EIO
֤
.B EFAULT
֤ꤹ뤳Ȥ롣
.TP
.B EINVAL
ʥץꤷ褦Ȥ
.TP
.B EIO
\fIrequest\fP Ǥ롣
ޤϡƥץޤϻҥץΥ
ΰɤ߽񤭤褦Ȥ
ޤϡɶȿä
ޤϡ¹ԺƳ׵ʥʥꤷ
.TP
.B EPERM
ꤷץȥ졼뤳ȤǤʤϿƥץ
ɬפʸ (ɬפʥѥӥƥ
.BR CAP_SYS_PTRACE )
äƤʤȤξ礬롣
ʬ䤹ͳ󤲤ʤ顢
롼ȤǤʤץϥʥʤץϥȥ졼Ǥʤ
set-user-ID/set-group-ID ץ¹ԤƤץϥȥ졼Ǥʤ
ޤϡץϤǤ˥ȥ졼Ǥ롢
ޤ
.BR init (8)
ץ (PID  1) Ǥ롣
.TP
.B ESRCH
ꤷץ¸ߤʤ
ޤϡꤷץϸƤӽФץ
ߥȥ졼λҥץǤϤʤ
ޤϡꤷץߤƤʤ (ߤƤ뤳Ȥɬפ׵ξ)
.SH 
SVr4, 4.3BSD
.SH 
.BR ptrace ()
ΰϾΤ褦ʥץȥפ˴ŤƲᤵ뤬
glibc ǤϡߤΤȤ
.BR ptrace ()
 \fIrequest\fP βĹؿȤ
Ƥ롣
ɬפʤлĤΰϾάǽǤ뤳Ȥ̣뤬

.BR gcc (1)
ʸƤʤưѤƤ뤳Ȥˤʤ롣
.LP
.BR init (8)
ʤ PID  1 Υץϥȥ졼뤳ȤǤʤ
.LP
 USER ΰƤ֤ OS ȡƥ㤴Ȥ
˰¸롣
.LP
֥ (word) פ礭 OS ˤäƷޤ롣
(㤨С32 ӥåȤ Linux Ǥ 32 ӥåȤǤ롢ʤɡ)
.LP
ȥ졼뤳Ȥˤäƥȥ졼ץư˺٤ʰ㤤
뤳Ȥ롣㤨Сץ
.B PTRACE_ATTACH
ˤä³줿ˤϡΥץߤǤοƤ
.BR wait (2)
ȤäΤ뤳ȤǤƤΨ褯
Τ򿿻ˡʤ
.LP
ƥץ
.B PTRACE_EVENT_*
åȤ줿٥Ȥ硢
ҥץ̤̾ΥʥԤ֤ˤʤ
Ĥޤꡢƥץ
ʥˤ
.BR ptrace (PTRACE_CONT)
Ԥäꡢ
.BR ptrace (PTRACE_KILL)
ԤäǤʤȤȤǤ롣
Υåμϡҥץλ (kill) Τˡ
ʥ
.B SIGKILL
ꤷ
.BR kill (2)
Ԥˡ˻ѤǤ롣
.LP
Υޥ˥奢ϸߤ Linux ˤ
.BR ptrace ()
ưˤĤƵҤƤ롣¾ Unix Ǥ
ưۤʤ롣
ʤ
.BR ptrace ()
Ȥ OS 䥢ƥ˰¸Τˤʤ롣
.LP
SunOS Υޥ˥奢롦ڡˤ
.BR ptrace ()
ϡäԲIJפȵҤƤꡢޤǤ롣
Solaris 2 Ǥ proc ١
ǥХåΥ󥿡եȤ
.BR ptrace ()
ξ̸ߴؿ졢궯ϤǰΤΤȤʤäƤ롣
.SH Х
ͥ 2.6 Υإå󥹥ȡ뤵줿ۥȤǤϡ
.B PTRACE_SETOPTIONS
ϥͥ 2.4 ΥإåȤϰۤʤͤ롣
Τᡢͥ 2.6 Υإåǥѥ뤵줿ץꥱ
ͥ 2.4 Ǥưʤ
ϡ
.B PTRACE_SETOPTIONS
Ƥݤϡ
.B PTRACE_SETOPTIONS

.B PTRACE_OLDSETOPTIONS
ľȤнǤ롣
.SH Ϣ
.BR gdb (1),
.BR strace (1),
.BR execve (2),
.BR fork (2),
.BR signal (2),
.BR wait (2),
.BR exec (3),
.BR capabilities (7)