.\" Copyright (c) 1993 Michael Haardt <michael@moria.de>

.\" Fri Apr  2 11:32:09 MET DST 1993

.\"

.\" and changes Copyright (C) 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

.\"

.\" and Copyright (c) 2011, Denys Vlasenko <vda.linux@googlemail.com>

.\" and Copyright (c) 2015, 2016, Michael Kerrisk <mtk.manpages@gmail.com>

.\"

.\" %%%LICENSE_START(GPLv2+_DOC_FULL)

.\" 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, see

.\" <http://www.gnu.org/licenses/>.

.\" %%%LICENSE_END

.\"

.\" 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.)

.\" 2011-09, major update by Denys Vlasenko <vda.linux@googlemail.com>

.\" 2015-01, Kees Cook <keescook@chromium.org>

.\"    Added PTRACE_O_TRACESECCOMP, PTRACE_EVENT_SECCOMP

.\"

.\" FIXME The following are undocumented:

.\"

.\" PTRACE_GETWMMXREGS

.\" PTRACE_SETWMMXREGS

.\"	ARM

.\" 	Linux 2.6.12

.\"

.\" PTRACE_SET_SYSCALL

.\"	ARM and ARM64

.\"	Linux 2.6.16

.\"	commit 3f471126ee53feb5e9b210ea2f525ed3bb9b7a7f

.\"	Author: Nicolas Pitre <nico@cam.org>

.\"	Date:   Sat Jan 14 19:30:04 2006 +0000

.\"

.\" PTRACE_GETCRUNCHREGS

.\" PTRACE_SETCRUNCHREGS

.\"	ARM

.\"	Linux 2.6.18

.\"	commit 3bec6ded282b331552587267d67a06ed7fd95ddd

.\"	Author: Lennert Buytenhek <buytenh@wantstofly.org>

.\"	Date:   Tue Jun 27 22:56:18 2006 +0100

.\"

.\" PTRACE_GETVFPREGS

.\" PTRACE_SETVFPREGS

.\"	ARM and ARM64

.\"	Linux 2.6.30

.\"	commit 3d1228ead618b88e8606015cbabc49019981805d

.\"	Author: Catalin Marinas <catalin.marinas@arm.com>

.\"	Date:   Wed Feb 11 13:12:56 2009 +0100

.\"

.\" PTRACE_GETHBPREGS

.\" PTRACE_SETHBPREGS

.\"	ARM and ARM64

.\"	Linux 2.6.37

.\"	commit 864232fa1a2f8dfe003438ef0851a56722740f3e

.\"	Author: Will Deacon <will.deacon@arm.com>

.\"	Date:   Fri Sep 3 10:42:55 2010 +0100

.\"

.\" PTRACE_SINGLEBLOCK

.\"	Since at least Linux 2.4.0 on various architectures

.\"	Since Linux 2.6.25 on x86 (and others?)

.\"	commit 5b88abbf770a0e1975c668743100f42934f385e8

.\"	Author: Roland McGrath <roland@redhat.com>

.\"	Date:   Wed Jan 30 13:30:53 2008 +0100

.\"	    ptrace: generic PTRACE_SINGLEBLOCK

.\"

.\" PTRACE_GETFPXREGS

.\" PTRACE_SETFPXREGS

.\"	Since at least Linux 2.4.0 on various architectures

.\"

.\" PTRACE_GETFDPIC

.\" PTRACE_GETFDPIC_EXEC

.\" PTRACE_GETFDPIC_INTERP

.\"	blackfin, c6x, frv, sh

.\"	First appearance in Linux 2.6.11 on frv

.\"

.\" and others that can be found in the arch/*/include/uapi/asm/ptrace files

.\"

.TH PTRACE 2 2017-09-15 "Linux" "Linux Programmer's Manual"

.SH NAME

ptrace \- process trace

.SH SYNOPSIS

.nf

.B #include <sys/ptrace.h>

.PP

.BI "long ptrace(enum __ptrace_request " request ", pid_t " pid ", "

.BI "            void *" addr ", void *" data );

.fi

.SH DESCRIPTION

The

.BR ptrace ()

system call provides a means by which one process (the "tracer")

may observe and control the execution of another process (the "tracee"),

and examine and change the tracee's memory and registers.

It is primarily used to implement breakpoint debugging and system

call tracing.

.PP

A tracee first needs to be attached to the tracer.

Attachment and subsequent commands are per thread:

in a multithreaded process,

every thread can be individually attached to a

(potentially different) tracer,

or left not attached and thus not debugged.

Therefore, "tracee" always means "(one) thread",

never "a (possibly multithreaded) process".

Ptrace commands are always sent to

a specific tracee using a call of the form

.PP

    ptrace(PTRACE_foo, pid, ...)

.PP

where

.I pid

is the thread ID of the corresponding Linux thread.

.PP

(Note that in this page, a "multithreaded process"

means a thread group consisting of threads created using the

.BR clone (2)

.B CLONE_THREAD

flag.)

.PP

A process can initiate a trace by calling

.BR fork (2)

and having the resulting child do a

.BR PTRACE_TRACEME ,

followed (typically) by an

.BR execve (2).

Alternatively, one process may commence tracing another process using

.B PTRACE_ATTACH

or

.BR PTRACE_SEIZE .

.PP

While being traced, the tracee will stop each time a signal is delivered,

even if the signal is being ignored.

(An exception is

.BR SIGKILL ,

which has its usual effect.)

The tracer will be notified at its next call to

.BR waitpid (2)

(or one of the related "wait" system calls); that call will return a

.I status

value containing information that indicates

the cause of the stop in the tracee.

While the tracee is stopped,

the tracer can use various ptrace requests to inspect and modify the tracee.

The tracer then causes the tracee to continue,

optionally ignoring the delivered signal

(or even delivering a different signal instead).

.PP

If the

.B PTRACE_O_TRACEEXEC

option is not in effect, all successful calls to

.BR execve (2)

by the traced process will cause it to be sent a

.B SIGTRAP

signal,

giving the parent a chance to gain control before the new program

begins execution.

.PP

When the tracer is finished tracing, it can cause the tracee to continue

executing in a normal, untraced mode via

.BR PTRACE_DETACH .

.PP

The value of

.I request

determines the action to be performed:

.TP

.B PTRACE_TRACEME

Indicate that this process is to be traced by its parent.

A process probably shouldn't make this request if its parent

isn't expecting to trace it.

.RI ( pid ,

.IR addr ,

and

.IR data

are ignored.)

.IP

The

.B PTRACE_TRACEME

request is used only by the tracee;

the remaining requests are used only by the tracer.

In the following requests,

.I pid

specifies the thread ID of the tracee to be acted on.

For requests other than

.BR PTRACE_ATTACH ,

.BR PTRACE_SEIZE ,

.BR PTRACE_INTERRUPT ,

and

.BR PTRACE_KILL ,

the tracee must be stopped.

.TP

.BR PTRACE_PEEKTEXT ", " PTRACE_PEEKDATA

Read a word at the address

.I addr

in the tracee's memory, returning the word as the result of the

.BR ptrace ()

call.

Linux does not have separate text and data address spaces,

so these two requests are currently equivalent.

.RI ( data

is ignored; but see NOTES.)

.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.

Read a word at offset

.I addr

in the tracee's USER area,

which holds the registers and other information about the process

(see

.IR <sys/user.h> ).

The word is returned as the result of the

.BR ptrace ()

call.

Typically, the offset must be word-aligned, though this might vary by

architecture.

See NOTES.

.RI ( data

is ignored; but see NOTES.)

.TP

.BR PTRACE_POKETEXT ", " PTRACE_POKEDATA

Copy the word

.I data

to the address

.I addr

in the tracee's memory.

As for

.BR PTRACE_PEEKTEXT

and

.BR PTRACE_PEEKDATA ,

these two requests are currently equivalent.

.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.

Copy the word

.I data

to offset

.I addr

in the tracee's USER area.

As for

.BR PTRACE_PEEKUSER ,

the offset must typically be word-aligned.

In order to maintain the integrity of the kernel,

some modifications to the USER area are disallowed.

.\" FIXME In the preceding sentence, which modifications are disallowed,

.\" and when they are disallowed, how does user space discover that fact?

.TP

.BR PTRACE_GETREGS ", " PTRACE_GETFPREGS

Copy the tracee's general-purpose or floating-point registers,

respectively, to the address

.I data

in the tracer.

See

.I <sys/user.h>

for information on the format of this data.

.RI ( addr

is ignored.)

Note that SPARC systems have the meaning of

.I data

and

.I addr

reversed; that is,

.I data

is ignored and the registers are copied to the address

.IR addr .

.B PTRACE_GETREGS

and

.B PTRACE_GETFPREGS

are not present on all architectures.

.TP

.BR PTRACE_GETREGSET " (since Linux 2.6.34)"

Read the tracee's registers.

.I addr

specifies, in an architecture-dependent way, the type of registers to be read.

.B NT_PRSTATUS

(with numerical value 1)

usually results in reading of general-purpose registers.

If the CPU has, for example,

floating-point and/or vector registers, they can be retrieved by setting

.I addr

to the corresponding

.B NT_foo

constant.

.I data

points to a

.BR "struct iovec" ,

which describes the destination buffer's location and length.

On return, the kernel modifies

.B iov.len

to indicate the actual number of bytes returned.

.TP

.BR PTRACE_SETREGS ", " PTRACE_SETFPREGS

Modify the tracee's general-purpose or floating-point registers,

respectively, from the address

.I data

in the tracer.

As for

.BR PTRACE_POKEUSER ,

some general-purpose register modifications may be disallowed.

.\" FIXME . In the preceding sentence, which modifications are disallowed,

.\" and when they are disallowed, how does user space discover that fact?

.RI ( addr

is ignored.)

Note that SPARC systems have the meaning of

.I data

and

.I addr

reversed; that is,

.I data

is ignored and the registers are copied from the address

.IR addr .

.B PTRACE_SETREGS

and

.B PTRACE_SETFPREGS

are not present on all architectures.

.TP

.BR PTRACE_SETREGSET " (since Linux 2.6.34)"

Modify the tracee's registers.

The meaning of

.I addr

and

.I data

is analogous to

.BR PTRACE_GETREGSET .

.TP

.BR PTRACE_GETSIGINFO " (since Linux 2.3.99-pre6)"

Retrieve information about the signal that caused the stop.

Copy a

.I siginfo_t

structure (see

.BR sigaction (2))

from the tracee to the address

.I data

in the tracer.

.RI ( addr

is ignored.)

.TP

.BR PTRACE_SETSIGINFO " (since Linux 2.3.99-pre6)"

Set signal information:

copy a

.I siginfo_t

structure from the address

.I data

in the tracer to the tracee.

This will affect only signals that would normally be delivered to

the tracee and were caught by the tracer.

It may be difficult to tell

these normal signals from synthetic signals generated by

.BR ptrace ()

itself.

.RI ( addr

is ignored.)

.TP

.BR PTRACE_PEEKSIGINFO " (since Linux 3.10)"

.\" commit 84c751bd4aebbaae995fe32279d3dba48327bad4

Retrieve

.I siginfo_t

structures without removing signals from a queue.

.I addr

points to a

.I ptrace_peeksiginfo_args

structure that specifies the ordinal position from which

copying of signals should start,

and the number of signals to copy.

.I siginfo_t

structures are copied into the buffer pointed to by

.IR data .

The return value contains the number of copied signals (zero indicates

that there is no signal corresponding to the specified ordinal position).

Within the returned

.I siginfo

structures,

the

.IR si_code

field includes information

.RB ( __SI_CHLD ,

.BR __SI_FAULT ,

etc.) that are not otherwise exposed to user space.

.PP

.in +4n

.EX

struct ptrace_peeksiginfo_args {

    u64 off;    /* Ordinal position in queue at which

                   to start copying signals */

    u32 flags;  /* PTRACE_PEEKSIGINFO_SHARED or 0 */

    s32 nr;     /* Number of signals to copy */

};

.EE

.in

.IP

Currently, there is only one flag,

.BR PTRACE_PEEKSIGINFO_SHARED ,

for dumping signals from the process-wide signal queue.

If this flag is not set,

signals are read from the per-thread queue of the specified thread.

.in

.PP

.TP

.BR PTRACE_GETSIGMASK " (since Linux 3.11)"

.\" commit 29000caecbe87b6b66f144f72111f0d02fbbf0c1

Place a copy of the mask of blocked signals (see

.BR sigprocmask (2))

in the buffer pointed to by

.IR data ,

which should be a pointer to a buffer of type

.IR sigset_t .

The

.I addr

argument contains the size of the buffer pointed to by

.IR data

(i.e.,

.IR sizeof(sigset_t) ).

.TP

.BR PTRACE_SETSIGMASK " (since Linux 3.11)"

Change the mask of blocked signals (see

.BR sigprocmask (2))

to the value specified in the buffer pointed to by

.IR data ,

which should be a pointer to a buffer of type

.IR sigset_t .

The

.I addr

argument contains the size of the buffer pointed to by

.IR data

(i.e.,

.IR sizeof(sigset_t) ).

.TP

.BR PTRACE_SETOPTIONS " (since Linux 2.4.6; see BUGS for caveats)"

Set ptrace options from

.IR data .

.RI ( addr

is ignored.)

.IR data

is interpreted as a bit mask of options,

which are specified by the following flags:

.RS

.TP

.BR PTRACE_O_EXITKILL " (since Linux 3.8)"

.\" commit 992fb6e170639b0849bace8e49bf31bd37c4123

Send a

.B SIGKILL

signal to the tracee if the tracer exits.

This option is useful for ptrace jailers that

want to ensure that tracees can never escape the tracer's control.

.TP

.BR PTRACE_O_TRACECLONE " (since Linux 2.5.46)"

Stop the tracee at the next

.BR clone (2)

and automatically start tracing the newly cloned process,

which will start with a

.BR SIGSTOP ,

or

.B PTRACE_EVENT_STOP

if

.B PTRACE_SEIZE

was used.

A

.BR waitpid (2)

by the tracer will return a

.I status

value such that

.IP

.nf

  status>>8 == (SIGTRAP | (PTRACE_EVENT_CLONE<<8))

.fi

.IP

The PID of the new process can be retrieved with

.BR PTRACE_GETEVENTMSG .

.IP

This option may not catch

.BR clone (2)

calls in all cases.

If the tracee calls

.BR clone (2)

with the

.B CLONE_VFORK

flag,

.B PTRACE_EVENT_VFORK

will be delivered instead

if

.B PTRACE_O_TRACEVFORK

is set; otherwise if the tracee calls

.BR clone (2)

with the exit signal set to

.BR SIGCHLD ,

.B PTRACE_EVENT_FORK

will be delivered if

.B PTRACE_O_TRACEFORK

is set.

.TP

.BR PTRACE_O_TRACEEXEC " (since Linux 2.5.46)"

Stop the tracee at the next

.BR execve (2).

A

.BR waitpid (2)

by the tracer will return a

.I status

value such that

.IP

.nf

  status>>8 == (SIGTRAP | (PTRACE_EVENT_EXEC<<8))

.fi

.IP

If the execing thread is not a thread group leader,

the thread ID is reset to thread group leader's ID before this stop.

Since Linux 3.0, the former thread ID can be retrieved with

.BR PTRACE_GETEVENTMSG .

.TP

.BR PTRACE_O_TRACEEXIT " (since Linux 2.5.60)"

Stop the tracee at exit.

A

.BR waitpid (2)

by the tracer will return a

.I status

value such that

.IP

.nf

  status>>8 == (SIGTRAP | (PTRACE_EVENT_EXIT<<8))

.fi

.IP

The tracee's exit status can be retrieved with

.BR PTRACE_GETEVENTMSG .

.IP

The tracee is stopped early during process exit,

when registers are still available,

allowing the tracer to see where the exit occurred,

whereas the normal exit notification is done after the process

is finished exiting.

Even though context is available,

the tracer cannot prevent the exit from happening at this point.

.TP

.BR PTRACE_O_TRACEFORK " (since Linux 2.5.46)"

Stop the tracee at the next

.BR fork (2)

and automatically start tracing the newly forked process,

which will start with a

.BR SIGSTOP ,

or

.B PTRACE_EVENT_STOP

if

.B PTRACE_SEIZE

was used.

A

.BR waitpid (2)

by the tracer will return a

.I status

value such that

.IP

.nf

  status>>8 == (SIGTRAP | (PTRACE_EVENT_FORK<<8))

.fi

.IP

The PID of the new process can be retrieved with

.BR PTRACE_GETEVENTMSG .

.TP

.BR PTRACE_O_TRACESYSGOOD " (since Linux 2.4.6)"

When delivering system call traps, set bit 7 in the signal number

(i.e., deliver

.IR "SIGTRAP|0x80" ).

This makes it easy for the tracer to distinguish

normal traps from those caused by a system call.

.RB ( PTRACE_O_TRACESYSGOOD

may not work on all architectures.)

.TP

.BR PTRACE_O_TRACEVFORK " (since Linux 2.5.46)"

Stop the tracee at the next

.BR vfork (2)

and automatically start tracing the newly vforked process,

which will start with a

.BR SIGSTOP ,

or

.B PTRACE_EVENT_STOP

if

.B PTRACE_SEIZE

was used.

A

.BR waitpid (2)

by the tracer will return a

.I status

value such that

.IP

.nf

  status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK<<8))

.fi

.IP

The PID of the new process can be retrieved with

.BR PTRACE_GETEVENTMSG .

.TP

.BR PTRACE_O_TRACEVFORKDONE " (since Linux 2.5.60)"

Stop the tracee at the completion of the next

.BR vfork (2).

A

.BR waitpid (2)

by the tracer will return a

.I status

value such that

.IP

.nf

  status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK_DONE<<8))

.fi

.IP

The PID of the new process can (since Linux 2.6.18) be retrieved with

.BR PTRACE_GETEVENTMSG .

.TP

.BR PTRACE_O_TRACESECCOMP " (since Linux 3.5)"

Stop the tracee when a

.BR seccomp (2)

.BR SECCOMP_RET_TRACE

rule is triggered.

A

.BR waitpid (2)

by the tracer will return a

.I status

value such that

.IP

.nf

  status>>8 == (SIGTRAP | (PTRACE_EVENT_SECCOMP<<8))

.fi

.IP

While this triggers a

.BR PTRACE_EVENT

stop, it is similar to a syscall-enter-stop.

For details, see the note on

.B PTRACE_EVENT_SECCOMP

below.

The seccomp event message data (from the

.BR SECCOMP_RET_DATA

portion of the seccomp filter rule) can be retrieved with

.BR PTRACE_GETEVENTMSG .

.TP

.BR PTRACE_O_SUSPEND_SECCOMP " (since Linux 4.3)"

.\" commit 13c4a90119d28cfcb6b5bdd820c233b86c2b0237

Suspend the tracee's seccomp protections.

This applies regardless of mode, and

can be used when the tracee has not yet installed seccomp filters.

That is, a valid use case is to suspend a tracee's seccomp protections

before they are installed by the tracee,

let the tracee install the filters,

and then clear this flag when the filters should be resumed.

Setting this option requires that the tracer have the

.BR CAP_SYS_ADMIN

capability,

not have any seccomp protections installed, and not have

.BR PTRACE_O_SUSPEND_SECCOMP

set on itself.

.RE

.TP

.BR PTRACE_GETEVENTMSG " (since Linux 2.5.46)"

Retrieve a message (as an

.IR "unsigned long" )

about the ptrace event

that just happened, placing it at the address

.I data

in the tracer.

For

.BR PTRACE_EVENT_EXIT ,

this is the tracee's exit status.

For

.BR PTRACE_EVENT_FORK ,

.BR PTRACE_EVENT_VFORK ,

.BR PTRACE_EVENT_VFORK_DONE ,

and

.BR PTRACE_EVENT_CLONE ,

this is the PID of the new process.

For

.BR PTRACE_EVENT_SECCOMP ,

this is the

.BR seccomp (2)

filter's

.BR SECCOMP_RET_DATA

associated with the triggered rule.

.RI ( addr

is ignored.)

.TP

.B PTRACE_CONT

Restart the stopped tracee process.

If

.I data

is nonzero,

it is interpreted as the number of a signal to be delivered to the tracee;

otherwise, no signal is delivered.

Thus, for example, the tracer can control

whether a signal sent to the tracee is delivered or not.

.RI ( addr

is ignored.)

.TP

.BR PTRACE_SYSCALL ", " PTRACE_SINGLESTEP

Restart the stopped tracee as for

.BR PTRACE_CONT ,

but arrange for the tracee to be stopped at

the next entry to or exit from a system call,

or after execution of a single instruction, respectively.

(The tracee will also, as usual, be stopped upon receipt of a signal.)

From the tracer's perspective, the tracee will appear to have been

stopped by receipt of a

.BR SIGTRAP .

So, for

.BR PTRACE_SYSCALL ,

for example, the idea is to inspect

the arguments to the system call at the first stop,

then do another

.B PTRACE_SYSCALL

and inspect the return value of the system call at the second stop.

The

.I data

argument is treated as for

.BR PTRACE_CONT .

.RI ( addr

is ignored.)

.TP

.BR PTRACE_SYSEMU ", " PTRACE_SYSEMU_SINGLESTEP " (since Linux 2.6.14)"

For

.BR PTRACE_SYSEMU ,

continue and stop on entry to the next system call,

which will not be executed.

See the documentation on syscall-stops below.

For

.BR PTRACE_SYSEMU_SINGLESTEP ,

do the same but also singlestep if not a system call.

This call is used by programs like

User Mode Linux that want to emulate all the tracee's system calls.

The

.I data

argument is treated as for

.BR PTRACE_CONT .

The

.I addr

argument is ignored.

These requests are currently

.\" As at 3.7

supported only on x86.

.TP

.BR PTRACE_LISTEN " (since Linux 3.4)"

Restart the stopped tracee, but prevent it from executing.

The resulting state of the tracee is similar to a process which

has been stopped by a

.B SIGSTOP

(or other stopping signal).

See the "group-stop" subsection for additional information.

.B PTRACE_LISTEN

works only on tracees attached by

.BR PTRACE_SEIZE .

.TP

.B PTRACE_KILL

Send the tracee a

.B SIGKILL

to terminate it.

.RI ( addr

and

.I data

are ignored.)

.IP

.I This operation is deprecated; do not use it!

Instead, send a

.BR SIGKILL

directly using

.BR kill (2)

or

.BR tgkill (2).

The problem with

.B PTRACE_KILL

is that it requires the tracee to be in signal-delivery-stop,

otherwise it may not work

(i.e., may complete successfully but won't kill the tracee).

By contrast, sending a

.B SIGKILL

directly has no such limitation.

.\" [Note from Denys Vlasenko:

.\"     deprecation suggested by Oleg Nesterov. He prefers to deprecate it

.\"     instead of describing (and needing to support) PTRACE_KILL's quirks.]

.TP

.BR PTRACE_INTERRUPT " (since Linux 3.4)"

Stop a tracee.

If the tracee is running or sleeping in kernel space and

.B PTRACE_SYSCALL

is in effect,

the system call is interrupted and syscall-exit-stop is reported.

(The interrupted system call is restarted when the tracee is restarted.)

If the tracee was already stopped by a signal and

.B PTRACE_LISTEN

was sent to it,

the tracee stops with

.B PTRACE_EVENT_STOP

and

.I WSTOPSIG(status)

returns the stop signal.

If any other ptrace-stop is generated at the same time (for example,

if a signal is sent to the tracee), this ptrace-stop happens.

If none of the above applies (for example, if the tracee is running in user

space), it stops with

.B PTRACE_EVENT_STOP

with

.I WSTOPSIG(status)

==

.BR SIGTRAP .

.B PTRACE_INTERRUPT

only works on tracees attached by

.BR PTRACE_SEIZE .

.TP

.B PTRACE_ATTACH

Attach to the process specified in

.IR pid ,

making it a tracee of the calling process.

.\" No longer true (removed by Denys Vlasenko, 2011, who remarks:

.\"        "I think it isn't true in non-ancient 2.4 and in 2.6/3.x.

.\"         Basically, it's not true for any Linux in practical use.

.\" ; the behavior of the tracee is as if it had done a

.\" .BR PTRACE_TRACEME .

.\" The calling process actually becomes the parent of the tracee

.\" process for most purposes (e.g., it will receive

.\" notification of tracee events and appears in

.\" .BR ps (1)

.\" output as the tracee's parent), but a

.\" .BR getppid (2)

.\" by the tracee will still return the PID of the original parent.

The tracee is sent a

.BR SIGSTOP ,

but will not necessarily have stopped

by the completion of this call; use

.BR waitpid (2)

to wait for the tracee to stop.

See the "Attaching and detaching" subsection for additional information.

.RI ( addr

and

.I data

are ignored.)

.IP

Permission to perform a

.BR PTRACE_ATTACH

is governed by a ptrace access mode

.B PTRACE_MODE_ATTACH_REALCREDS

check; see below.

.TP

.BR PTRACE_SEIZE " (since Linux 3.4)"

.\"

.\" Noted by Dmitry Levin:

.\"

.\"     PTRACE_SEIZE was introduced by commit v3.1-rc1~308^2~28, but

.\"     it had to be used along with a temporary flag PTRACE_SEIZE_DEVEL,

.\"     which was removed later by commit v3.4-rc1~109^2~20.

.\"

.\"     That is, [before] v3.4 we had a test mode of PTRACE_SEIZE API,

.\"     which was not compatible with the current PTRACE_SEIZE API introduced

.\"     in Linux 3.4.

.\"

Attach to the process specified in

.IR pid ,

making it a tracee of the calling process.

Unlike

.BR PTRACE_ATTACH ,

.B PTRACE_SEIZE

does not stop the process.

Group-stops are reported as