.\" 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@gmx.net>
.\"     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
.\"
.\"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 2006-03-24 "Linux 2.6.16" "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)
ƤӽФ줿ҥץ PTRACE_TRACEME Ԥ
³ (ŵŪˤ)
.BR exec (3)
Ԥʤ
̤ˡȤƤϡ
ƥץ¸ΥץФ PTRACE_ATTACH Ѥ
ȥ졼򳫻Ϥ롣
.LP
ȥ졼μ¹桢ҥץϥʥ뤬뤿Ӥˡ
ȤΥʥ뤬̵뤹٤ΤǤäƤߤ
(SIGKILL 㳰ǡ̾ɤθ̤⤿餹)
ƥץˤϼ
.BR wait (2)
Τ졢ߤƤ֤˻ҥץĴ٤꽤ꤹ뤳ȤǤ롣
ƿƥץϻҥץμ¹ԤƳ뤬줿
ʥ̵뤹뤳ȤǤ (뤤̤Υʥ
뤳ȤǤ) 
.LP
ƥץȥ졼λݤˤϡ
PTRACE_KILL Ѥƻҥץλ뤳ȤǤ뤷
PTRACE_DETACH Ѥ̾Υȥ졼ʤΥ⡼ɤˤơ
¹Ԥ³뤳ȤǤ롣
.LP
\fIrequest\fP ͤΥƥॳưꤹ:
.TP
PTRACE_TRACEME
Υץƥץˤäƥȥ졼뤳Ȥɽ
Υץ (SIGKILL ʳ) ʥ뤬ȡ
ץߤƥץ
.BR wait ()
̤Τ롣
ޤʹߤϤΥץ
.BR exec ()
ƤӽФ٤ SIGTRAP 褦ˤʤ롣
ˤäơƥץ
ץब¹Ԥ򳫻Ϥ椹뤳ȤǤ롣
ƥץץȥ졼Ĥ꤬ʤˤϡ
餯Υץ׵Ԥ٤ǤϤʤ
(\fIpid\fP, \fIaddr\fP, \fIdata\fP ̵뤵롣)
.LP
嵭׵ϻҥץԤʤΤǤ롣
ĤϿƥץԤʤΤǤ롣
ʲ׵Ǥϡ\fIpid\fP оݤȤʤ
ҥץꤹ롣
PTRACE_KILL ׵Ԥʤˤ
ҥץߤƤʤФʤʤ
.TP
PTRACE_PEEKTEXT, PTRACE_PEEKDATA
ҥץΥ
.I addr
ΰ֤ 1 ɤɤ߽Фɤ߽Фɤ
.BR ptrace ()
֤ͤȤ֤롣 Linux Ǥϥƥ (text) ȥǡ (data) 
Ʊɥ쥹֤Ѥ뤿ᡢ 2 Ĥ׵ϸߤΤȤ
ƱΤǤ롣 ( \fIdata\fP ̵뤵롣)
.TP
PTRACE_PEEKUSR
ҥץ
.B USER
ΰΥեå
.I addr
ΰ֤ 1 ɤɤ߹ࡣUSER ΰˤϤΥץ
쥸 (registers) ʤɤξݻƤ롣(<linux/user.h>  <sys/user.h>
򻲾)ɤ߹ɤ
.BR ptrace ()
η̤Ȥ֤롣
ƤϥեåȤϥɶˤʤФʤʤ
ƥˤäƤϤɬפϤʤ
(\fIdata\fP ̵뤵롣 )
.TP
PTRACE_POKETEXT, PTRACE_POKEDATA

.IR data
ҥץΥ
.IR addr
ΰ֤إԡ롣ƱͤˡߤΤȤĤ
׵ƱΤǤ롣
.TP
PTRACE_POKEUSR

.I data
ҥץ
.B USER
ΰΥեå
.I addr 
ΰ֤˥ԡ롣
Ʊͤˡ̾եåȤϥɶˤʤФʤʤ
ͥδ (integrity) ݻ뤿ᡢ
ѹƤˤäƤ
.B USER
ΰѹ϶ػߤƤ롣
.TP
PTRACE_GETREGS, PTRACE_GETFPREGS
줾졢ҥץѥ쥸ư쥸ƥץ
\fIdata\fP ΰ֤˥ԡ롣 data ν񼰤˴ؤƤ
<linux/user.h> 򻲾Ȥ뤳ȡ(\fIaddr\fP ̵뤵롣)
.TP
PTRACE_GETSIGINFO (Linux 2.3.99-pre6 ʹ)
ߤθȤʤäʥ˴ؤ롣
\fIsiginfo_t\fP ¤
.RB ( sigaction (2)
) ҥץƥץ \fIdata\fP ΰ֤˥ԡ롣
(\fIaddr\fP ̵뤵롣)
.TP
PTRACE_SETREGS, PTRACE_SETFPREGS
줾졢ҥץѥ쥸ư쥸
ƥץ \fIdate\fP ΰ֤饳ԡ롣
PTRACE_POKEUSER Ʊͤˡѥ쥸ˤäƤ
ѹػߤƤ礬롣 (\fIaddr\fP ̵뤵롣)
.TP
PTRACE_SETSIGINFO (Linux 2.3.99-pre6 ʹ)
ʥꤹ롣
\fIsiginfo_t\fP ¤ΤƥץΥǡ \fIdata\fP ΰ֤
ҥץ˥ԡ롣
νԤȤǤΤϡҥץ̾Ϥ
ȥ졼ª줿ʥˤĤƤǤ롣
̾Υʥ
.BR ptrace ()
Ȥȯ륷ʥʬΤ񤷤⤷ʤ
(\fIaddr\fP ̵뤵롣)
.TP
PTRACE_SETOPTIONS (Linux 2.4.6 ʹ; ХξϤˤٹ⻲)
ƥץ \fIdata\fP ˴Ť ptrace Υץꤹ
(\fIaddr\fP ̵뤵)
\fIdata\fP ϥץΥӥåȥޥȤƲᤵ졢
ץˤϰʲΥե饰Ǥ:
.RS
.TP
PTRACE_O_TRACESYSGOOD (Linux 2.4.6 ʹ)
ƥॳΥȥåפ줿ȤˡʥֹΥӥå 7
ꤹ (ʤ(SIGTRAP | 0x80) )
ˤꡢȥ졼̾Υȥåפȥƥॳˤȥåפ
̤䤹ʤ롣
(PTRACE_O_TRACESYSGOOD ϤɤΥƥǤưʤǽ롣)
.TP
PTRACE_O_TRACEFORK (Linux 2.5.46 ʹ)

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

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

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

.BR exec ()
ƤӽФ
SIGTRAP | PTRACE_EVENT_EXEC << 8 ǻҥץưߤ롣
.TP
PTRACE_O_TRACEVFORKDONE (Linux 2.5.60 ʹ)

.BR vfork ()
ƤӽФ
SIGTRAP | PTRACE_EVENT_VFORK_DONE << 8 ǻҥץưߤ롣
.TP
PTRACE_O_TRACEEXIT (Linux 2.5.60 ʹ)
λ (exit)  SIGTRAP | PTRACE_EVENT_EXIT << 8 ǻҥץư
ߤ롣ҥץνλơ PTRACE_GETEVENTMSG ǼǤ롣
ߤϥ쥸ޤȲǽǤץλν˹Ԥ졢
ȥ졼ϤɤǽλȯΤ뤳ȤǤ롣
̾νλ (exit notification) ϥץνλλ
Ԥ롣ƥȤ򻲾Ȥ뤳ȤϤǤˤؤ餺
ȥ졼Ϥλ齪λߤ뤳ȤϤǤʤ
.RE
.TP
PTRACE_GETEVENTMSG (Linux 2.5.46 ʹ)
ȯФ ptrace ٥Ȥ˴ؤå
.RI ( "unsigned long"
) 롣
åϿƥץ \fIdata\fP ΰ֤˳Ǽ롣
ƤϡPTRACE_EVENT_EXIT ξϻҥץνλơǤꡢ
PTRACE_EVENT_FORK, PTRACE_EVENT_VFORK, PTRACE_EVENT_CLONE ξ
ץ PID Ǥ롣 (\fIaddr\fP ̵뤵롣)
.TP
PTRACE_CONT
ߤҥץμ¹ԤƳ롣
\fIdata\fP ǤʤSIGSTOP ǤʤС
ҥץ륷ʥȲᤵ롣
 SIGSTOP ξϥʥʤ
Ȥȡ㤨Сƥץ
ҥץ줿ʥºݤ뤫ɤ
椹뤳ȤǤ롣(\fIaddr\fP ̵뤵롣)
.TP
PTRACE_SYSCALL, PTRACE_SINGLESTEP
PTRACE_CONT ƱͤߤҥץƳ롣
PTRACE_SYSCALL ξϻҥץ
˥ƥॳ뤫ƥॳ뤫ȴ뤫ˡ
PTRACE_SINGLESTEP ξ 1 ̿ (instruction) ¹Ԥߤ
(̾ɤꡢҥץϥʥäˤߤ)
ƥץ鸫ȡҥץ SIGTRAP 
ߤ褦˸롣Τᡢ㤨 PTRACE_SYSCALL Ȥȡ
1ܤߤǰĴ٤ PTRACE_SYSCALL ¹Ԥ
2ܤߤǥƥॳ֤ͤĴ٤롢
Ȥ褦ʤȤǤ롣(\fIaddr\fP ̵뤵롣)
.TP
PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP (Linux 2.6.14 ʹ)
PTRACE_SYSEMU ϡ¹ԤƳΥƥॳߤ롣
ƥॳϼ¹Ԥʤ
PTRACE_SYSEMU_SINGLESTEP ƱͤƥॳǤʤˤ
1 ̿ (singlestep) ¹ԤǤߤ롣
Υ User Mode Linux Τ褦˻ҥץΥƥॳ
ߥ졼Ȥ褦ȤץǻѤ롣
(\fIaddr\fP  \fIdata\fP ̵뤵롣
ƤΥƥǥݡȤƤ櫓ǤϤʤ)
.TP
PTRACE_KILL
ҥץ SIGKILL 꽪λ롣(\fIaddr\fP  \fIdata\fP 
̵뤵롣)
.TP
PTRACE_ATTACH
.I pid
ǻꤵ줿ץ³ (attach) 򸽺ߤΥץ
ҥץȤƥȥ졼Ǥ褦ˤ롣ҥץ PTRACE_TRACEME
Τ褦˿񤦡ߤΥץϤΤۤȤɤŪˤơ
λҥץμºݤοƤˤʤ (㤨СҥץΥ٥Ȥ
ΤȤäꡢ
.BR ps (1)
ǿƤȤɽ줿ꤹ)ҥץ
.BR getppid (2)
¹Ԥˤϸοƥץ PID ֤롣
ҥץˤ SIGSTOP 뤬θƤӽФλޤǤ
ɬߤȤϸ¤ʤҥץߤԤĤˤ
.BR wait ()
Ѥ뤳ȡ(\fIaddr\fP  \fIdata\fP ̵뤵롣)
.TP
PTRACE_DETACH
PTRACE_CONT ƱͤߤҥץƳ롣
ޤΥץʬΥ (detach) Ԥ
PTRACE_ATTACH ǤοƤڤ괹ˤ̤
PTRACE_TRACEME θ̤äտޤΤǤϤʤ
Linux Ǥϡȥ졼ƤҥץϤɤΤ褦ˡǥȥ졼
Ϥ줿ȤƤ⡢ˡʬΥ (detach) 뤳ȤǤ롣
(\fIaddr\fP ̵뤵롣)
.SH 
.BR ptrace ()
ΰϾΤ褦ʥץȥפ˴ŤƲᤵ뤬
GNU libc ǤϡߤΤȤ
.BR ptrace ()
 \fIrequest\fP βĹؿȤ
Ƥ롣
ɬפʤлĤΰϾάǽǤ뤳Ȥ̣뤬

.BR gcc (1)
ʸƤʤưѤƤ뤳Ȥˤʤ롣
.LP
.BR init (8) 
ʤ PID  1 Υץϥȥ졼뤳ȤǤʤ
.LP
 USER ΰƤ֤ OS ȡƥ㤴Ȥ
˰¸롣
.LP
֥ (word) פ礭 OS ˤäƷޤ롣
(㤨С32 ӥåȤ Linux Ǥ 32 ӥåȤǤ롢ʤɡ)
.LP
ȥ졼뤳Ȥˤäƥȥ졼ץư˺٤ʰ㤤
뤳Ȥ롣㤨Сץ PTRACE_ATTACH ˤä³줿
ˤϡΥץߤǤοƤ
.BR wait ()
ȤäΤ뤳ȤǤƤΨ褯
Τ򿿻ˡʤ
.LP
Υޥ˥奢ϸߤ Linux ˤ
.BR ptrace ()
ưˤĤƵҤƤ롣¾ Unix Ǥ
ưۤʤ롣
ʤ
.BR ptrace ()
Ȥ OS 䥢ƥ˰¸Τˤʤ롣
.LP
SunOS Υޥ˥奢롦ڡˤ
.BR ptrace ()
ϡäԲIJפȵҤƤꡢޤǤ롣
Solaris 2 Ǥ proc ١
ǥХåΥ󥿡եȤ
.BR ptrace ()
ξ̸ߴؿ졢궯ϤǰΤΤȤʤäƤ롣
.SH ֤
ȡPTRACE_PEEK* ξ׵ᤷǡ֤
ʳξ 0 ֤
顼ξ \-1 ֤
.I errno
Ŭڤꤵ롣
PTRACE_PEEK* ֤ͤ⡡\-1 ˤʤ뤳Ȥ뤿ᡢ
Τ褦׵ξˤϡƤӽФ
.I errno
Ĵ١顼ȯΤɤȽǤʤФʤʤ
.SH Х
ͥ 2.6 Υإå󥹥ȡ뤵줿ۥȤǤϡ
PTRACE_SETOPTIONS ϥͥ 2.4 ΥإåȤϰۤʤͤ롣
Τᡢͥ 2.6 Υإåǥѥ뤵줿ץꥱ
ͥ 2.4 Ǥưʤ
ϡPTRACE_SETOPTIONS ƤȤϡ
PTRACE_SETOPTIONS  PTRACE_OLDSETOPTIONS ľȤ
нǤ롣
.SH 顼
.TP
.B EBUSY
(i386 Τ) ǥХå쥸γݤޤϲǥ顼ȯ
.TP
.B EFAULT
ƥץޤϻҥץΥΰɤ߽񤭤褦Ȥ
餯ΰ褬ޥåԥ󥰤Ƥʤ
ΰؤΥƤʤǤ롣
ԱʤȤˡLinux ǤϤΤ褦ʥ顼ξ硢¿쾯ʤ
Ū EIO ֤ 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 gdb (1),
.BR strace (1),
.BR execve (2),
.BR fork (2),
.BR signal (2),
.BR wait (2),
.BR exec (3),
.BR capabilities (7)