2011-09-26 17:33:04 +00:00
|
|
|
.\" Copyright (c) 1993 Michael Haardt <michael@moria.de>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Fri Apr 2 11:32:09 MET DST 1993
|
|
|
|
.\"
|
2011-09-26 17:33:04 +00:00
|
|
|
.\" and changes Copyright (C) 1999 Mike Coleman (mkc@acm.org)
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" -- major revision to fully document ptrace semantics per recent Linux
|
2007-04-12 22:42:49 +00:00
|
|
|
.\" kernel (2.2.10) and glibc (2.1.2)
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Sun Nov 7 03:18:35 CST 1999
|
|
|
|
.\"
|
2011-09-26 17:33:04 +00:00
|
|
|
.\" and Copyright (c) 2011, Denys Vlasenko <vda.linux@googlemail.com>
|
2016-06-25 06:31:28 +00:00
|
|
|
.\" and Copyright (c) 2015, 2016, Michael Kerrisk <mtk.manpages@gmail.com>
|
2011-09-26 17:33:04 +00:00
|
|
|
.\"
|
getent.1, _syscall.2, acct.2, adjtimex.2, bdflush.2, brk.2, cacheflush.2, getsid.2, getxattr.2, inotify_add_watch.2, inotify_init.2, inotify_rm_watch.2, ioperm.2, ipc.2, listxattr.2, mlock.2, modify_ldt.2, mremap.2, nanosleep.2, outb.2, perf_event_open.2, ptrace.2, removexattr.2, s390_runtime_instr.2, sched_get_priority_max.2, sched_rr_get_interval.2, sched_setaffinity.2, sched_setparam.2, sched_setscheduler.2, sched_yield.2, setsid.2, setxattr.2, socketcall.2, unimplemented.2, aio_cancel.3, aio_error.3, aio_fsync.3, aio_read.3, aio_return.3, aio_suspend.3, aio_write.3, cfree.3, crypt.3, dlopen.3, encrypt.3, errno.3, fenv.3, ftime.3, ftw.3, getgrent_r.3, getpass.3, getpwent_r.3, getutent.3, hsearch.3, lio_listio.3, lockf.3, login.3, longjmp.3, perror.3, printf.3, scandirat.3, setjmp.3, strfmon.3, strtoimax.3, termios.3, ttyname.3, ualarm.3, updwtmp.3, wcstoimax.3, wordexp.3, console_ioctl.4, dsp56k.4, fd.4, hd.4, intro.4, lp.4, mem.4, null.4, ram.4, rtc.4, sk98lin.4, tty.4, ttyS.4, vcs.4, filesystems.5, group.5, host.conf.5, hosts.5, intro.5, issue.5, motd.5, networks.5, nologin.5, nsswitch.conf.5, passwd.5, proc.5, protocols.5, securetty.5, shells.5, termcap.5, ttytype.5, utmp.5, intro.6, armscii-8.7, ascii.7, bootparam.7, cp1251.7, environ.7, glob.7, intro.7, iso_8859-1.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-15.7, iso_8859-16.7, iso_8859-2.7, iso_8859-3.7, iso_8859-4.7, iso_8859-5.7, iso_8859-6.7, iso_8859-7.7, iso_8859-8.7, iso_8859-9.7, koi8-r.7, koi8-u.7, posixoptions.7, standards.7, unicode.7, utf-8.7, intro.8: s/GPLv2+_doc_full/GPLv2+_DOC_FULL/
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2013-03-10 09:29:46 +00:00
|
|
|
.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" 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
|
getent.1, _syscall.2, acct.2, adjtimex.2, bdflush.2, brk.2, cacheflush.2, getsid.2, getxattr.2, inotify_add_watch.2, inotify_init.2, inotify_rm_watch.2, ioperm.2, ipc.2, listxattr.2, mlock.2, modify_ldt.2, mremap.2, nanosleep.2, outb.2, ptrace.2, removexattr.2, sched_get_priority_max.2, sched_rr_get_interval.2, sched_setaffinity.2, sched_setparam.2, sched_setscheduler.2, sched_yield.2, setsid.2, setxattr.2, socketcall.2, unimplemented.2, aio_cancel.3, aio_error.3, aio_fsync.3, aio_read.3, aio_return.3, aio_suspend.3, aio_write.3, cfree.3, crypt.3, dlopen.3, errno.3, fenv.3, ftime.3, ftw.3, getgrent_r.3, getpass.3, getpwent_r.3, getutent.3, hsearch.3, lio_listio.3, login.3, longjmp.3, perror.3, printf.3, scandirat.3, setjmp.3, strfmon.3, strtoimax.3, termios.3, ttyname.3, ualarm.3, wcstoimax.3, wordexp.3, console_ioctl.4, dsp56k.4, fd.4, hd.4, intro.4, lp.4, mem.4, null.4, ram.4, rtc.4, sk98lin.4, tty.4, ttyS.4, vcs.4, charmap.5, filesystems.5, ftpusers.5, gai.conf.5, group.5, host.conf.5, hosts.5, intro.5, issue.5, locale.5, motd.5, networks.5, nologin.5, nscd.conf.5, nss.5, nsswitch.conf.5, passwd.5, proc.5, protocols.5, securetty.5, shells.5, termcap.5, ttytype.5, utmp.5, intro.6, armscii-8.7, ascii.7, bootparam.7, cp1251.7, cpuset.7, environ.7, glob.7, intro.7, iso_8859-1.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-15.7, iso_8859-16.7, iso_8859-2.7, iso_8859-3.7, iso_8859-4.7, iso_8859-5.7, iso_8859-6.7, iso_8859-7.7, iso_8859-8.7, iso_8859-9.7, koi8-r.7, koi8-u.7, posixoptions.7, standards.7, unicode.7, utf-8.7, intro.8, ldconfig.8, nscd.8: Global fix: Update info in source comments on where to get a copy of the GPL
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2013-03-10 09:28:43 +00:00
|
|
|
.\" License along with this manual; if not, see
|
|
|
|
.\" <http://www.gnu.org/licenses/>.
|
getent.1, _syscall.2, acct.2, adjtimex.2, bdflush.2, brk.2, cacheflush.2, getsid.2, getxattr.2, inotify_add_watch.2, inotify_init.2, inotify_rm_watch.2, ioperm.2, ipc.2, listxattr.2, mlock.2, modify_ldt.2, mremap.2, nanosleep.2, outb.2, perf_event_open.2, ptrace.2, removexattr.2, s390_runtime_instr.2, sched_get_priority_max.2, sched_rr_get_interval.2, sched_setaffinity.2, sched_setparam.2, sched_setscheduler.2, sched_yield.2, setsid.2, setxattr.2, socketcall.2, unimplemented.2, aio_cancel.3, aio_error.3, aio_fsync.3, aio_read.3, aio_return.3, aio_suspend.3, aio_write.3, cfree.3, crypt.3, dlopen.3, encrypt.3, errno.3, fenv.3, ftime.3, ftw.3, getgrent_r.3, getpass.3, getpwent_r.3, getutent.3, hsearch.3, lio_listio.3, lockf.3, login.3, longjmp.3, perror.3, printf.3, scandirat.3, setjmp.3, strfmon.3, strtoimax.3, termios.3, ttyname.3, ualarm.3, updwtmp.3, wcstoimax.3, wordexp.3, console_ioctl.4, dsp56k.4, fd.4, hd.4, intro.4, lp.4, mem.4, null.4, ram.4, rtc.4, sk98lin.4, tty.4, ttyS.4, vcs.4, filesystems.5, group.5, host.conf.5, hosts.5, intro.5, issue.5, motd.5, networks.5, nologin.5, nsswitch.conf.5, passwd.5, proc.5, protocols.5, securetty.5, shells.5, termcap.5, ttytype.5, utmp.5, intro.6, armscii-8.7, ascii.7, bootparam.7, cp1251.7, environ.7, glob.7, intro.7, iso_8859-1.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-15.7, iso_8859-16.7, iso_8859-2.7, iso_8859-3.7, iso_8859-4.7, iso_8859-5.7, iso_8859-6.7, iso_8859-7.7, iso_8859-8.7, iso_8859-9.7, koi8-r.7, koi8-u.7, posixoptions.7, standards.7, unicode.7, utf-8.7, intro.8: Global fix: Add LICENSE_START(GPLv2+_doc_full)
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2013-03-10 09:28:44 +00:00
|
|
|
.\" %%%LICENSE_END
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
|
|
|
.\" 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>
|
2007-09-20 06:52:22 +00:00
|
|
|
.\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Added notes on capability requirements
|
|
|
|
.\"
|
2006-03-23 22:00:08 +00:00
|
|
|
.\" 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-26 17:33:04 +00:00
|
|
|
.\" 2011-09, major update by Denys Vlasenko <vda.linux@googlemail.com>
|
2015-01-18 06:26:17 +00:00
|
|
|
.\" 2015-01, Kees Cook <keescook@chromium.org>
|
|
|
|
.\" Added PTRACE_O_TRACESECCOMP, PTRACE_EVENT_SECCOMP
|
2006-03-23 22:00:08 +00:00
|
|
|
.\"
|
2016-11-01 13:02:13 +00:00
|
|
|
.\" FIXME The following are undocumented:
|
|
|
|
.\"
|
2016-11-01 13:06:28 +00:00
|
|
|
.\" PTRACE_GETWMMXREGS
|
2016-11-01 13:02:13 +00:00
|
|
|
.\" 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
|
2016-11-09 00:49:25 +00:00
|
|
|
.\" Since at least Linux 2.4.0 on various architectures
|
2016-11-01 13:02:13 +00:00
|
|
|
.\" 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
|
2016-11-09 00:49:25 +00:00
|
|
|
.\" Since at least Linux 2.4.0 on various architectures
|
2016-11-01 13:02:13 +00:00
|
|
|
.\"
|
|
|
|
.\" PTRACE_GETFDPIC
|
|
|
|
.\" PTRACE_GETFDPIC_EXEC
|
|
|
|
.\" PTRACE_GETFDPIC_INTERP
|
|
|
|
.\" blackfin, c6x, frv, sh
|
|
|
|
.\" First appearance in Linux 2.6.11 on frv
|
2016-10-29 10:23:48 +00:00
|
|
|
.\"
|
2015-10-09 13:09:22 +00:00
|
|
|
.\" and others that can be found in the arch/*/include/uapi/asm/ptrace files
|
|
|
|
.\"
|
ldd.1, localedef.1, add_key.2, chroot.2, clone.2, fork.2, futex.2, get_mempolicy.2, get_robust_list.2, getitimer.2, getpriority.2, ioctl.2, ioctl_ficlonerange.2, ioctl_fideduperange.2, kcmp.2, kill.2, lookup_dcookie.2, mmap.2, mount.2, open.2, pciconfig_read.2, perf_event_open.2, prctl.2, process_vm_readv.2, ptrace.2, quotactl.2, recv.2, setfsgid.2, setfsuid.2, sysinfo.2, umask.2, umount.2, unshare.2, utimensat.2, wait.2, assert.3, fmax.3, fmin.3, getauxval.3, inet_pton.3, malloc_hook.3, memmem.3, mkdtemp.3, mktemp.3, printf.3, strcasecmp.3, strcat.3, strtoul.3, strxfrm.3, console_codes.4, console_ioctl.4, lirc.4, tty.4, vcs.4, charmap.5, elf.5, locale.5, proc.5, repertoiremap.5, utmp.5, capabilities.7, cgroup_namespaces.7, cgroups.7, charsets.7, cp1251.7, cp1252.7, credentials.7, feature_test_macros.7, iso_8859-1.7, iso_8859-15.7, iso_8859-5.7, koi8-r.7, koi8-u.7, man-pages.7, mount_namespaces.7, namespaces.7, netlink.7, pid_namespaces.7, unix.7, user_namespaces.7, utf-8.7: tstamp
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2016-07-17 16:07:58 +00:00
|
|
|
.TH PTRACE 2 2016-07-17 "Linux" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
ptrace \- process trace
|
|
|
|
.SH SYNOPSIS
|
2006-03-23 22:00:08 +00:00
|
|
|
.nf
|
2004-11-03 13:51:07 +00:00
|
|
|
.B #include <sys/ptrace.h>
|
|
|
|
.sp
|
2006-03-23 22:00:08 +00:00
|
|
|
.BI "long ptrace(enum __ptrace_request " request ", pid_t " pid ", "
|
|
|
|
.BI " void *" addr ", void *" data );
|
|
|
|
.fi
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH DESCRIPTION
|
|
|
|
The
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR ptrace ()
|
2011-09-26 17:33:04 +00:00
|
|
|
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.
|
2006-03-25 21:28:28 +00:00
|
|
|
It is primarily used to implement breakpoint debugging and system
|
2004-11-03 13:51:07 +00:00
|
|
|
call tracing.
|
|
|
|
.LP
|
2011-10-01 05:39:39 +00:00
|
|
|
A tracee first needs to be attached to the tracer.
|
2011-09-26 17:33:04 +00:00
|
|
|
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".
|
2011-09-25 05:30:51 +00:00
|
|
|
Ptrace commands are always sent to
|
2011-09-26 17:33:04 +00:00
|
|
|
a specific tracee using a call of the form
|
|
|
|
|
|
|
|
ptrace(PTRACE_foo, pid, ...)
|
|
|
|
|
|
|
|
where
|
|
|
|
.I pid
|
|
|
|
is the thread ID of the corresponding Linux thread.
|
|
|
|
.LP
|
2011-10-01 05:39:39 +00:00
|
|
|
(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.)
|
|
|
|
.LP
|
2011-09-26 17:33:04 +00:00
|
|
|
A process can initiate a trace by calling
|
2007-04-12 22:42:49 +00:00
|
|
|
.BR fork (2)
|
2007-06-21 05:38:48 +00:00
|
|
|
and having the resulting child do a
|
|
|
|
.BR PTRACE_TRACEME ,
|
2006-03-25 21:28:28 +00:00
|
|
|
followed (typically) by an
|
2011-09-24 06:29:34 +00:00
|
|
|
.BR execve (2).
|
2011-09-26 17:33:04 +00:00
|
|
|
Alternatively, one process may commence tracing another process using
|
2013-02-16 08:50:27 +00:00
|
|
|
.B PTRACE_ATTACH
|
|
|
|
or
|
|
|
|
.BR PTRACE_SEIZE .
|
2004-11-03 13:51:07 +00:00
|
|
|
.LP
|
2011-09-24 06:29:34 +00:00
|
|
|
While being traced, the tracee will stop each time a signal is delivered,
|
2007-04-12 22:42:49 +00:00
|
|
|
even if the signal is being ignored.
|
2011-09-26 17:33:04 +00:00
|
|
|
(An exception is
|
2007-06-21 05:38:48 +00:00
|
|
|
.BR SIGKILL ,
|
|
|
|
which has its usual effect.)
|
2011-09-26 17:33:04 +00:00
|
|
|
The tracer will be notified at its next call to
|
|
|
|
.BR waitpid (2)
|
2011-10-01 05:39:39 +00:00
|
|
|
(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.
|
2011-09-24 06:29:34 +00:00
|
|
|
The tracer then causes the tracee to continue,
|
2006-03-25 21:28:28 +00:00
|
|
|
optionally ignoring the delivered signal
|
2004-11-03 13:51:07 +00:00
|
|
|
(or even delivering a different signal instead).
|
|
|
|
.LP
|
2012-03-29 17:57:11 +00:00
|
|
|
If the
|
2012-03-29 17:50:37 +00:00
|
|
|
.B PTRACE_O_TRACEEXEC
|
|
|
|
option is not in effect, all successful calls to
|
|
|
|
.BR execve (2)
|
2012-03-29 17:57:11 +00:00
|
|
|
by the traced process will cause it to be sent a
|
2012-03-29 17:50:37 +00:00
|
|
|
.B SIGTRAP
|
2012-03-29 17:57:11 +00:00
|
|
|
signal,
|
2012-03-29 17:50:37 +00:00
|
|
|
giving the parent a chance to gain control before the new program
|
|
|
|
begins execution.
|
|
|
|
.LP
|
2011-09-26 17:33:04 +00:00
|
|
|
When the tracer is finished tracing, it can cause the tracee to continue
|
2011-09-24 06:29:34 +00:00
|
|
|
executing in a normal, untraced mode via
|
2007-06-21 05:38:48 +00:00
|
|
|
.BR PTRACE_DETACH .
|
2004-11-03 13:51:07 +00:00
|
|
|
.LP
|
2011-09-26 17:33:04 +00:00
|
|
|
The value of
|
|
|
|
.I request
|
|
|
|
determines the action to be performed:
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
2007-06-21 05:38:48 +00:00
|
|
|
.B PTRACE_TRACEME
|
2011-09-26 17:33:04 +00:00
|
|
|
Indicate that this process is to be traced by its parent.
|
2007-04-12 22:42:49 +00:00
|
|
|
A process probably shouldn't make this request if its parent
|
|
|
|
isn't expecting to trace it.
|
2011-09-26 17:33:04 +00:00
|
|
|
.RI ( pid ,
|
|
|
|
.IR addr ,
|
|
|
|
and
|
|
|
|
.IR data
|
|
|
|
are ignored.)
|
2014-02-19 08:24:51 +00:00
|
|
|
.IP
|
2011-09-26 17:33:04 +00:00
|
|
|
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.
|
2007-06-21 05:38:48 +00:00
|
|
|
For requests other than
|
2013-02-16 08:50:27 +00:00
|
|
|
.BR PTRACE_ATTACH ,
|
|
|
|
.BR PTRACE_SEIZE ,
|
fcntl.2, msgget.2, ptrace.2, request_key.2, shmget.2, sigaction.2, syscalls.2, dbopen.3, euidaccess.3, getgrnam.3, getpwnam.3, strfmon.3, strtol.3, strtoul.3, cciss.4, hpsa.4, mouse.4, termcap.5, charsets.7, iso_8859-16.7, iso_8859-2.7, koi8-r.7, unicode.7, utf-8.7: Use Oxford comma
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2014-02-05 15:09:11 +00:00
|
|
|
.BR PTRACE_INTERRUPT ,
|
2012-03-29 17:50:37 +00:00
|
|
|
and
|
2007-06-21 05:38:48 +00:00
|
|
|
.BR PTRACE_KILL ,
|
2011-09-24 06:29:34 +00:00
|
|
|
the tracee must be stopped.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
2007-06-21 05:38:48 +00:00
|
|
|
.BR PTRACE_PEEKTEXT ", " PTRACE_PEEKDATA
|
2011-09-26 17:33:04 +00:00
|
|
|
Read a word at the address
|
2007-09-20 16:26:31 +00:00
|
|
|
.I addr
|
2011-09-24 06:29:34 +00:00
|
|
|
in the tracee's memory, returning the word as the result of the
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR ptrace ()
|
2007-04-12 22:42:49 +00:00
|
|
|
call.
|
2011-09-26 17:33:04 +00:00
|
|
|
Linux does not have separate text and data address spaces,
|
|
|
|
so these two requests are currently equivalent.
|
|
|
|
.RI ( data
|
2014-02-19 10:30:24 +00:00
|
|
|
is ignored; but see NOTES.)
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
2007-10-17 20:49:47 +00:00
|
|
|
.B PTRACE_PEEKUSER
|
2007-11-24 07:34:48 +00:00
|
|
|
.\" PTRACE_PEEKUSR in kernel source, but glibc uses PTRACE_PEEKUSER,
|
|
|
|
.\" and that is the name that seems common on other systems.
|
2011-09-26 17:33:04 +00:00
|
|
|
Read a word at offset
|
2004-11-03 13:51:07 +00:00
|
|
|
.I addr
|
2011-09-24 06:29:34 +00:00
|
|
|
in the tracee's USER area,
|
2007-06-21 05:38:48 +00:00
|
|
|
which holds the registers and other information about the process
|
2011-09-26 17:33:04 +00:00
|
|
|
(see
|
|
|
|
.IR <sys/user.h> ).
|
2006-03-25 21:28:28 +00:00
|
|
|
The word is returned as the result of the
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR ptrace ()
|
2007-04-12 22:42:49 +00:00
|
|
|
call.
|
2011-09-26 17:33:04 +00:00
|
|
|
Typically, the offset must be word-aligned, though this might vary by
|
2008-05-21 20:23:25 +00:00
|
|
|
architecture.
|
|
|
|
See NOTES.
|
2011-09-26 17:33:04 +00:00
|
|
|
.RI ( data
|
2014-02-19 10:30:24 +00:00
|
|
|
is ignored; but see NOTES.)
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
2007-06-21 05:38:48 +00:00
|
|
|
.BR PTRACE_POKETEXT ", " PTRACE_POKEDATA
|
2011-09-26 17:33:04 +00:00
|
|
|
Copy the word
|
2007-09-20 16:26:31 +00:00
|
|
|
.I data
|
2011-09-26 17:33:04 +00:00
|
|
|
to the address
|
2007-09-20 16:26:31 +00:00
|
|
|
.I addr
|
2011-09-24 06:29:34 +00:00
|
|
|
in the tracee's memory.
|
2011-09-26 17:33:04 +00:00
|
|
|
As for
|
2012-03-05 19:54:38 +00:00
|
|
|
.BR PTRACE_PEEKTEXT
|
2011-09-26 17:33:04 +00:00
|
|
|
and
|
|
|
|
.BR PTRACE_PEEKDATA ,
|
|
|
|
these two requests are currently equivalent.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
2007-10-17 20:49:47 +00:00
|
|
|
.B PTRACE_POKEUSER
|
2007-11-24 07:34:48 +00:00
|
|
|
.\" PTRACE_POKEUSR in kernel source, but glibc uses PTRACE_POKEUSER,
|
|
|
|
.\" and that is the name that seems common on other systems.
|
2011-09-26 17:33:04 +00:00
|
|
|
Copy the word
|
2007-09-20 16:26:31 +00:00
|
|
|
.I data
|
2004-11-03 13:51:07 +00:00
|
|
|
to offset
|
|
|
|
.I addr
|
2011-09-24 06:29:34 +00:00
|
|
|
in the tracee's USER area.
|
2011-09-26 17:33:04 +00:00
|
|
|
As for
|
|
|
|
.BR PTRACE_PEEKUSER ,
|
|
|
|
the offset must typically be word-aligned.
|
2007-04-12 22:42:49 +00:00
|
|
|
In order to maintain the integrity of the kernel,
|
2007-06-21 05:38:48 +00:00
|
|
|
some modifications to the USER area are disallowed.
|
2011-09-26 17:33:04 +00:00
|
|
|
.\" FIXME In the preceding sentence, which modifications are disallowed,
|
eventfd.2, futex.2, mmap2.2, open.2, pciconfig_read.2, ptrace.2, reboot.2, request_key.2, sched_rr_get_interval.2, splice.2, stat.2, sync_file_range.2, syscalls.2, timer_create.2, vm86.2, pthread_attr_setscope.3, core.5, proc.5, aio.7, futex.7, netlink.7, time.7: Global fix: "userspace" ==> "user space" or "user-space"
Existing pages variously use "userspace or "user space".
But, "userspace" is not quite an English word.
So change "userspace" to "user space" or, when used
attributively, "user-space".
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2012-10-21 06:04:42 +00:00
|
|
|
.\" and when they are disallowed, how does user space discover that fact?
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
2007-06-21 05:38:48 +00:00
|
|
|
.BR PTRACE_GETREGS ", " PTRACE_GETFPREGS
|
2013-03-02 05:33:34 +00:00
|
|
|
Copy the tracee's general-purpose or floating-point registers,
|
2011-09-26 17:33:04 +00:00
|
|
|
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.)
|
2012-04-24 06:03:38 +00:00
|
|
|
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 .
|
2012-10-25 12:02:19 +00:00
|
|
|
.B PTRACE_GETREGS
|
|
|
|
and
|
|
|
|
.B PTRACE_GETFPREGS
|
|
|
|
are not present on all architectures.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
2013-02-16 08:50:27 +00:00
|
|
|
.BR PTRACE_GETREGSET " (since Linux 2.6.34)"
|
|
|
|
Read the tracee's registers.
|
|
|
|
.I addr
|
2013-02-16 09:22:49 +00:00
|
|
|
specifies, in an architecture-dependent way, the type of registers to be read.
|
2013-02-16 08:50:27 +00:00
|
|
|
.B NT_PRSTATUS
|
|
|
|
(with numerical value 1)
|
2013-02-16 09:22:49 +00:00
|
|
|
usually results in reading of general-purpose registers.
|
|
|
|
If the CPU has, for example,
|
2013-02-16 08:50:27 +00:00
|
|
|
floating-point and/or vector registers, they can be retrieved by setting
|
|
|
|
.I addr
|
2013-02-16 09:22:49 +00:00
|
|
|
to the corresponding
|
2013-02-16 08:50:27 +00:00
|
|
|
.B NT_foo
|
|
|
|
constant.
|
|
|
|
.I data
|
|
|
|
points to a
|
|
|
|
.BR "struct iovec" ,
|
2013-03-02 05:22:31 +00:00
|
|
|
which describes the destination buffer's location and length.
|
2013-02-16 09:22:49 +00:00
|
|
|
On return, the kernel modifies
|
2013-02-16 08:50:27 +00:00
|
|
|
.B iov.len
|
2013-02-16 09:22:49 +00:00
|
|
|
to indicate the actual number of bytes returned.
|
2013-02-16 08:50:27 +00:00
|
|
|
.TP
|
2007-10-16 19:18:17 +00:00
|
|
|
.BR PTRACE_SETREGS ", " PTRACE_SETFPREGS
|
2013-02-16 08:50:27 +00:00
|
|
|
Modify the tracee's general-purpose or floating-point registers,
|
2011-09-26 17:33:04 +00:00
|
|
|
respectively, from the address
|
|
|
|
.I data
|
|
|
|
in the tracer.
|
2007-06-21 05:38:48 +00:00
|
|
|
As for
|
|
|
|
.BR PTRACE_POKEUSER ,
|
2012-03-05 16:15:23 +00:00
|
|
|
some general-purpose register modifications may be disallowed.
|
adjtimex.2, bind.2, cacheflush.2, clone.2, fallocate.2, fanotify_init.2, fanotify_mark.2, flock.2, futex.2, getdents.2, getpriority.2, getrlimit.2, gettid.2, gettimeofday.2, ioprio_set.2, kexec_load.2, migrate_pages.2, modify_ldt.2, mount.2, move_pages.2, mprotect.2, msgop.2, nfsservctl.2, perf_event_open.2, pread.2, ptrace.2, recvmmsg.2, rename.2, restart_syscall.2, sched_setattr.2, send.2, shmop.2, shutdown.2, sigaction.2, signalfd.2, syscalls.2, timer_create.2, timerfd_create.2, tkill.2, vmsplice.2, wait.2, aio_init.3, confstr.3, exit.3, fmemopen.3, fopen.3, getaddrinfo.3, getauxval.3, getspnam.3, isalpha.3, isatty.3, mallinfo.3, malloc.3, mallopt.3, psignal.3, pthread_attr_setinheritsched.3, qecvt.3, queue.3, rtnetlink.3, strerror.3, strftime.3, toupper.3, towlower.3, towupper.3, initrd.4, locale.5, proc.5, bootparam.7, capabilities.7, ddp.7, fanotify.7, icmp.7, inotify.7, ip.7, ipv6.7, netdevice.7, netlink.7, path_resolution.7, rtld-audit.7, rtnetlink.7, sched.7, signal.7, socket.7, svipc.7, tcp.7, unix.7, ld.so.8: srcfix: Update FIXMEs
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2014-08-21 21:47:44 +00:00
|
|
|
.\" FIXME . In the preceding sentence, which modifications are disallowed,
|
eventfd.2, futex.2, mmap2.2, open.2, pciconfig_read.2, ptrace.2, reboot.2, request_key.2, sched_rr_get_interval.2, splice.2, stat.2, sync_file_range.2, syscalls.2, timer_create.2, vm86.2, pthread_attr_setscope.3, core.5, proc.5, aio.7, futex.7, netlink.7, time.7: Global fix: "userspace" ==> "user space" or "user-space"
Existing pages variously use "userspace or "user space".
But, "userspace" is not quite an English word.
So change "userspace" to "user space" or, when used
attributively, "user-space".
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2012-10-21 06:04:42 +00:00
|
|
|
.\" and when they are disallowed, how does user space discover that fact?
|
2011-09-26 17:33:04 +00:00
|
|
|
.RI ( addr
|
|
|
|
is ignored.)
|
2012-04-24 06:03:38 +00:00
|
|
|
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 .
|
2012-10-25 12:02:19 +00:00
|
|
|
.B PTRACE_SETREGS
|
|
|
|
and
|
|
|
|
.B PTRACE_SETFPREGS
|
|
|
|
are not present on all architectures.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
2013-02-16 08:50:27 +00:00
|
|
|
.BR PTRACE_SETREGSET " (since Linux 2.6.34)"
|
2013-02-16 09:22:49 +00:00
|
|
|
Modify the tracee's registers.
|
|
|
|
The meaning of
|
2013-02-16 08:50:27 +00:00
|
|
|
.I addr
|
|
|
|
and
|
|
|
|
.I data
|
|
|
|
is analogous to
|
|
|
|
.BR PTRACE_GETREGSET .
|
|
|
|
.TP
|
2013-07-16 08:19:31 +00:00
|
|
|
.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
|
2007-06-21 05:38:48 +00:00
|
|
|
.BR PTRACE_SETSIGINFO " (since Linux 2.3.99-pre6)"
|
2011-09-26 17:33:04 +00:00
|
|
|
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
|
2011-09-24 06:29:34 +00:00
|
|
|
the tracee and were caught by the tracer.
|
2007-04-12 22:42:49 +00:00
|
|
|
It may be difficult to tell
|
2006-03-23 22:00:08 +00:00
|
|
|
these normal signals from synthetic signals generated by
|
|
|
|
.BR ptrace ()
|
2008-05-21 20:23:25 +00:00
|
|
|
itself.
|
2011-09-26 17:33:04 +00:00
|
|
|
.RI ( addr
|
|
|
|
is ignored.)
|
2006-03-23 22:00:08 +00:00
|
|
|
.TP
|
2013-07-16 08:19:32 +00:00
|
|
|
.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
|
2014-01-20 10:03:06 +00:00
|
|
|
structure that specifies the ordinal position from which
|
|
|
|
copying of signals should start,
|
|
|
|
and the number of signals to copy.
|
2013-07-16 08:19:32 +00:00
|
|
|
.I siginfo_t
|
2014-01-20 10:03:06 +00:00
|
|
|
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
|
2013-07-16 08:19:32 +00:00
|
|
|
.I siginfo
|
2014-01-20 10:03:06 +00:00
|
|
|
structures,
|
|
|
|
the
|
2013-07-16 08:19:32 +00:00
|
|
|
.IR si_code
|
2014-01-20 10:03:06 +00:00
|
|
|
field includes information
|
|
|
|
.RB ( __SI_CHLD ,
|
|
|
|
.BR __SI_FAULT ,
|
2014-02-01 20:24:50 +00:00
|
|
|
etc.) that are not otherwise exposed to user space.
|
2013-07-16 08:19:32 +00:00
|
|
|
.PP
|
|
|
|
.in +10n
|
|
|
|
.nf
|
|
|
|
struct ptrace_peeksiginfo_args {
|
2014-01-20 10:03:06 +00:00
|
|
|
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 */
|
2013-07-16 08:19:32 +00:00
|
|
|
};
|
|
|
|
.fi
|
2016-08-11 19:04:43 +00:00
|
|
|
.in
|
2016-11-08 12:43:12 +00:00
|
|
|
.IP
|
2014-01-20 10:03:06 +00:00
|
|
|
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.
|
2013-07-16 08:19:32 +00:00
|
|
|
.in
|
|
|
|
.PP
|
|
|
|
.TP
|
2013-07-16 08:19:33 +00:00
|
|
|
.BR PTRACE_GETSIGMASK " (since Linux 3.11)"
|
|
|
|
.\" commit 29000caecbe87b6b66f144f72111f0d02fbbf0c1
|
2014-01-23 05:13:57 +00:00
|
|
|
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 .
|
2013-07-16 08:19:33 +00:00
|
|
|
The
|
|
|
|
.I addr
|
2014-01-23 05:13:57 +00:00
|
|
|
argument contains the size of the buffer pointed to by
|
|
|
|
.IR data
|
|
|
|
(i.e.,
|
|
|
|
.IR sizeof(sigset_t) ).
|
2013-07-16 08:19:33 +00:00
|
|
|
.TP
|
|
|
|
.BR PTRACE_SETSIGMASK " (since Linux 3.11)"
|
2014-01-23 05:13:57 +00:00
|
|
|
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 .
|
2013-07-16 08:19:33 +00:00
|
|
|
The
|
|
|
|
.I addr
|
2014-01-23 05:13:57 +00:00
|
|
|
argument contains the size of the buffer pointed to by
|
|
|
|
.IR data
|
|
|
|
(i.e.,
|
|
|
|
.IR sizeof(sigset_t) ).
|
2013-07-16 08:19:33 +00:00
|
|
|
.TP
|
2007-06-21 05:38:48 +00:00
|
|
|
.BR PTRACE_SETOPTIONS " (since Linux 2.4.6; see BUGS for caveats)"
|
2011-09-26 17:33:04 +00:00
|
|
|
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:
|
2013-01-24 00:43:09 +00:00
|
|
|
.RS
|
2013-01-24 00:52:42 +00:00
|
|
|
.TP
|
|
|
|
.BR PTRACE_O_EXITKILL " (since Linux 3.8)"
|
|
|
|
.\" commit 992fb6e170639b0849bace8e49bf31bd37c4123
|
|
|
|
If a tracer sets this flag, a
|
|
|
|
.B SIGKILL
|
2013-01-27 20:28:25 +00:00
|
|
|
signal will be sent to every tracee if the tracer exits.
|
|
|
|
This option is useful for ptrace jailers that
|
2013-02-04 04:29:50 +00:00
|
|
|
want to ensure that tracees can never escape the tracer's control.
|
2006-03-23 22:00:08 +00:00
|
|
|
.TP
|
2007-06-21 05:38:48 +00:00
|
|
|
.BR PTRACE_O_TRACECLONE " (since Linux 2.5.46)"
|
2011-09-24 06:29:34 +00:00
|
|
|
Stop the tracee at the next
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR clone (2)
|
2011-09-26 17:33:04 +00:00
|
|
|
and automatically start tracing the newly cloned process,
|
|
|
|
which will start with a
|
2013-07-10 18:40:14 +00:00
|
|
|
.BR SIGSTOP ,
|
|
|
|
or
|
|
|
|
.B PTRACE_EVENT_STOP
|
|
|
|
if
|
|
|
|
.B PTRACE_SEIZE
|
|
|
|
was used.
|
2011-10-01 05:39:39 +00:00
|
|
|
A
|
|
|
|
.BR waitpid (2)
|
2012-02-26 18:36:30 +00:00
|
|
|
by the tracer will return a
|
2011-10-01 05:39:39 +00:00
|
|
|
.I status
|
2012-02-26 18:36:30 +00:00
|
|
|
value such that
|
|
|
|
|
|
|
|
.nf
|
|
|
|
status>>8 == (SIGTRAP | (PTRACE_EVENT_CLONE<<8))
|
|
|
|
.fi
|
|
|
|
|
2011-09-26 17:33:04 +00:00
|
|
|
The PID of the new process can be retrieved with
|
2007-06-21 05:38:48 +00:00
|
|
|
.BR PTRACE_GETEVENTMSG .
|
2011-09-26 17:33:04 +00:00
|
|
|
.IP
|
2006-03-23 22:00:08 +00:00
|
|
|
This option may not catch
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR clone (2)
|
2007-04-12 22:42:49 +00:00
|
|
|
calls in all cases.
|
2011-09-24 06:29:34 +00:00
|
|
|
If the tracee calls
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR clone (2)
|
2007-06-21 05:38:48 +00:00
|
|
|
with the
|
2007-09-20 16:26:31 +00:00
|
|
|
.B CLONE_VFORK
|
2007-06-21 05:38:48 +00:00
|
|
|
flag,
|
|
|
|
.B PTRACE_EVENT_VFORK
|
|
|
|
will be delivered instead
|
|
|
|
if
|
|
|
|
.B PTRACE_O_TRACEVFORK
|
2011-09-24 06:29:34 +00:00
|
|
|
is set; otherwise if the tracee calls
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR clone (2)
|
2007-06-21 05:38:48 +00:00
|
|
|
with the exit signal set to
|
|
|
|
.BR SIGCHLD ,
|
|
|
|
.B PTRACE_EVENT_FORK
|
2011-09-26 17:33:04 +00:00
|
|
|
will be delivered if
|
2007-06-21 05:38:48 +00:00
|
|
|
.B PTRACE_O_TRACEFORK
|
|
|
|
is set.
|
2006-03-23 22:00:08 +00:00
|
|
|
.TP
|
2007-06-21 05:38:48 +00:00
|
|
|
.BR PTRACE_O_TRACEEXEC " (since Linux 2.5.46)"
|
2011-09-24 06:29:34 +00:00
|
|
|
Stop the tracee at the next
|
2011-09-26 17:33:04 +00:00
|
|
|
.BR execve (2).
|
2011-10-01 05:39:39 +00:00
|
|
|
A
|
|
|
|
.BR waitpid (2)
|
2012-02-26 18:36:30 +00:00
|
|
|
by the tracer will return a
|
2011-10-01 05:39:39 +00:00
|
|
|
.I status
|
2012-02-26 18:36:30 +00:00
|
|
|
value such that
|
|
|
|
|
|
|
|
.nf
|
|
|
|
status>>8 == (SIGTRAP | (PTRACE_EVENT_EXEC<<8))
|
|
|
|
.fi
|
|
|
|
|
2012-03-23 18:52:17 +00:00
|
|
|
If the execing thread is not a thread group leader,
|
|
|
|
the thread ID is reset to thread group leader's ID before this stop.
|
2012-03-23 18:49:32 +00:00
|
|
|
Since Linux 3.0, the former thread ID can be retrieved with
|
|
|
|
.BR PTRACE_GETEVENTMSG .
|
2006-03-23 22:00:08 +00:00
|
|
|
.TP
|
2007-06-21 05:38:48 +00:00
|
|
|
.BR PTRACE_O_TRACEEXIT " (since Linux 2.5.60)"
|
2011-09-26 17:33:04 +00:00
|
|
|
Stop the tracee at exit.
|
2011-10-01 05:39:39 +00:00
|
|
|
A
|
|
|
|
.BR waitpid (2)
|
2012-02-26 18:36:30 +00:00
|
|
|
by the tracer will return a
|
2011-10-01 05:39:39 +00:00
|
|
|
.I status
|
2012-02-26 18:36:30 +00:00
|
|
|
value such that
|
|
|
|
|
|
|
|
.nf
|
|
|
|
status>>8 == (SIGTRAP | (PTRACE_EVENT_EXIT<<8))
|
|
|
|
.fi
|
|
|
|
|
2011-09-24 06:29:34 +00:00
|
|
|
The tracee's exit status can be retrieved with
|
2007-06-21 05:38:48 +00:00
|
|
|
.BR PTRACE_GETEVENTMSG .
|
2011-09-26 17:33:04 +00:00
|
|
|
.IP
|
|
|
|
The tracee is stopped early during process exit,
|
|
|
|
when registers are still available,
|
|
|
|
allowing the tracer to see where the exit occurred,
|
2007-04-12 22:42:49 +00:00
|
|
|
whereas the normal exit notification is done after the process
|
2006-03-25 21:28:28 +00:00
|
|
|
is finished exiting.
|
2011-09-26 17:33:04 +00:00
|
|
|
Even though context is available,
|
|
|
|
the tracer cannot prevent the exit from happening at this point.
|
2013-01-24 00:43:09 +00:00
|
|
|
.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
|
2013-07-10 18:40:14 +00:00
|
|
|
.BR SIGSTOP ,
|
|
|
|
or
|
|
|
|
.B PTRACE_EVENT_STOP
|
|
|
|
if
|
|
|
|
.B PTRACE_SEIZE
|
|
|
|
was used.
|
2013-01-24 00:43:09 +00:00
|
|
|
A
|
|
|
|
.BR waitpid (2)
|
|
|
|
by the tracer will return a
|
|
|
|
.I status
|
|
|
|
value such that
|
|
|
|
|
|
|
|
.nf
|
|
|
|
status>>8 == (SIGTRAP | (PTRACE_EVENT_FORK<<8))
|
|
|
|
.fi
|
|
|
|
|
|
|
|
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
|
2013-07-10 18:40:14 +00:00
|
|
|
.BR SIGSTOP ,
|
|
|
|
or
|
|
|
|
.B PTRACE_EVENT_STOP
|
|
|
|
if
|
|
|
|
.B PTRACE_SEIZE
|
|
|
|
was used.
|
2013-01-24 00:43:09 +00:00
|
|
|
A
|
|
|
|
.BR waitpid (2)
|
|
|
|
by the tracer will return a
|
|
|
|
.I status
|
|
|
|
value such that
|
|
|
|
|
|
|
|
.nf
|
|
|
|
status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK<<8))
|
|
|
|
.fi
|
|
|
|
|
|
|
|
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
|
|
|
|
|
|
|
|
.nf
|
|
|
|
status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK_DONE<<8))
|
|
|
|
.fi
|
|
|
|
|
|
|
|
The PID of the new process can (since Linux 2.6.18) be retrieved with
|
|
|
|
.BR PTRACE_GETEVENTMSG .
|
2015-01-18 06:26:17 +00:00
|
|
|
.TP
|
|
|
|
.BR PTRACE_O_TRACESECCOMP " (since Linux 3.5)"
|
|
|
|
Stop the tracee when a
|
|
|
|
.BR seccomp (2)
|
|
|
|
.BR SECCOMP_RET_TRACE
|
2015-01-18 11:09:19 +00:00
|
|
|
rule is triggered.
|
|
|
|
A
|
2015-01-18 06:26:17 +00:00
|
|
|
.BR waitpid (2)
|
|
|
|
by the tracer will return a
|
|
|
|
.I status
|
|
|
|
value such that
|
|
|
|
|
|
|
|
.nf
|
|
|
|
status>>8 == (SIGTRAP | (PTRACE_EVENT_SECCOMP<<8))
|
|
|
|
.fi
|
|
|
|
|
|
|
|
While this triggers a
|
|
|
|
.BR PTRACE_EVENT
|
2016-11-17 07:21:01 +00:00
|
|
|
stop, it is similar to a syscall-enter-stop.
|
|
|
|
For details, see the note on
|
|
|
|
.B PTRACE_EVENT_SECCOMP
|
|
|
|
below.
|
2015-01-18 11:09:19 +00:00
|
|
|
The seccomp event message data (from the
|
2015-01-18 06:26:17 +00:00
|
|
|
.BR SECCOMP_RET_DATA
|
2015-01-18 11:09:19 +00:00
|
|
|
portion of the seccomp filter rule) can be retrieved with
|
2015-01-18 06:26:17 +00:00
|
|
|
.BR PTRACE_GETEVENTMSG .
|
2015-09-11 11:53:28 +00:00
|
|
|
.TP
|
2015-09-11 12:00:59 +00:00
|
|
|
.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,
|
2015-09-11 11:53:28 +00:00
|
|
|
not have any seccomp protections installed, and not have
|
|
|
|
.BR PTRACE_O_SUSPEND_SECCOMP
|
|
|
|
set on itself.
|
2006-03-23 22:00:08 +00:00
|
|
|
.RE
|
|
|
|
.TP
|
2007-06-21 05:38:48 +00:00
|
|
|
.BR PTRACE_GETEVENTMSG " (since Linux 2.5.46)"
|
2007-04-12 22:42:49 +00:00
|
|
|
Retrieve a message (as an
|
|
|
|
.IR "unsigned long" )
|
2006-03-23 22:00:08 +00:00
|
|
|
about the ptrace event
|
2011-09-26 17:33:04 +00:00
|
|
|
that just happened, placing it at the address
|
|
|
|
.I data
|
|
|
|
in the tracer.
|
2007-06-21 05:38:48 +00:00
|
|
|
For
|
2011-09-26 17:33:04 +00:00
|
|
|
.BR PTRACE_EVENT_EXIT ,
|
2011-09-24 06:29:34 +00:00
|
|
|
this is the tracee's exit status.
|
2007-06-21 05:38:48 +00:00
|
|
|
For
|
|
|
|
.BR PTRACE_EVENT_FORK ,
|
2011-09-26 17:33:04 +00:00
|
|
|
.BR PTRACE_EVENT_VFORK ,
|
|
|
|
.BR PTRACE_EVENT_VFORK_DONE ,
|
2007-06-21 05:38:48 +00:00
|
|
|
and
|
2011-09-26 17:33:04 +00:00
|
|
|
.BR PTRACE_EVENT_CLONE ,
|
|
|
|
this is the PID of the new process.
|
2015-01-18 06:26:17 +00:00
|
|
|
For
|
|
|
|
.BR PTRACE_EVENT_SECCOMP ,
|
|
|
|
this is the
|
|
|
|
.BR seccomp (2)
|
|
|
|
filter's
|
|
|
|
.BR SECCOMP_RET_DATA
|
|
|
|
associated with the triggered rule.
|
2014-02-19 09:34:42 +00:00
|
|
|
.RI ( addr
|
2011-09-26 17:33:04 +00:00
|
|
|
is ignored.)
|
2006-03-23 22:00:08 +00:00
|
|
|
.TP
|
2007-06-21 05:38:48 +00:00
|
|
|
.B PTRACE_CONT
|
2011-09-26 17:33:04 +00:00
|
|
|
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;
|
2007-04-12 22:42:49 +00:00
|
|
|
otherwise, no signal is delivered.
|
2011-09-24 06:29:34 +00:00
|
|
|
Thus, for example, the tracer can control
|
|
|
|
whether a signal sent to the tracee is delivered or not.
|
2011-09-26 17:33:04 +00:00
|
|
|
.RI ( addr
|
|
|
|
is ignored.)
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
2007-06-21 05:38:48 +00:00
|
|
|
.BR PTRACE_SYSCALL ", " PTRACE_SINGLESTEP
|
2011-09-26 17:33:04 +00:00
|
|
|
Restart the stopped tracee as for
|
2007-06-21 05:38:48 +00:00
|
|
|
.BR PTRACE_CONT ,
|
2011-09-26 17:33:04 +00:00
|
|
|
but arrange for the tracee to be stopped at
|
|
|
|
the next entry to or exit from a system call,
|
2007-04-12 22:42:49 +00:00
|
|
|
or after execution of a single instruction, respectively.
|
2011-09-24 06:29:34 +00:00
|
|
|
(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
|
2007-06-21 05:38:48 +00:00
|
|
|
stopped by receipt of a
|
|
|
|
.BR SIGTRAP .
|
|
|
|
So, for
|
|
|
|
.BR PTRACE_SYSCALL ,
|
|
|
|
for example, the idea is to inspect
|
2007-04-12 22:42:49 +00:00
|
|
|
the arguments to the system call at the first stop,
|
2007-06-21 05:38:48 +00:00
|
|
|
then do another
|
|
|
|
.B PTRACE_SYSCALL
|
2011-09-26 17:33:04 +00:00
|
|
|
and inspect the return value of the system call at the second stop.
|
2009-03-30 00:30:07 +00:00
|
|
|
The
|
|
|
|
.I data
|
|
|
|
argument is treated as for
|
|
|
|
.BR PTRACE_CONT .
|
2012-03-23 23:12:33 +00:00
|
|
|
.RI ( addr
|
2011-09-26 17:33:04 +00:00
|
|
|
is ignored.)
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
2007-10-16 19:18:17 +00:00
|
|
|
.BR PTRACE_SYSEMU ", " PTRACE_SYSEMU_SINGLESTEP " (since Linux 2.6.14)"
|
2007-06-21 05:38:48 +00:00
|
|
|
For
|
|
|
|
.BR PTRACE_SYSEMU ,
|
2011-09-26 17:33:04 +00:00
|
|
|
continue and stop on entry to the next system call,
|
2016-11-17 07:21:01 +00:00
|
|
|
which will not be executed.
|
|
|
|
See the documentation on syscall-stops below.
|
2007-06-21 05:38:48 +00:00
|
|
|
For
|
|
|
|
.BR PTRACE_SYSEMU_SINGLESTEP ,
|
2011-09-26 17:33:04 +00:00
|
|
|
do the same but also singlestep if not a system call.
|
2007-04-12 22:42:49 +00:00
|
|
|
This call is used by programs like
|
2011-09-24 06:29:34 +00:00
|
|
|
User Mode Linux that want to emulate all the tracee's system calls.
|
2009-03-30 00:30:07 +00:00
|
|
|
The
|
|
|
|
.I data
|
|
|
|
argument is treated as for
|
|
|
|
.BR PTRACE_CONT .
|
2012-10-25 12:02:19 +00:00
|
|
|
The
|
|
|
|
.I addr
|
|
|
|
argument is ignored.
|
|
|
|
These requests are currently
|
|
|
|
.\" As at 3.7
|
2012-11-09 05:53:19 +00:00
|
|
|
supported only on x86.
|
2006-03-23 22:00:08 +00:00
|
|
|
.TP
|
2013-02-16 08:50:27 +00:00
|
|
|
.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
|
2013-02-16 09:22:49 +00:00
|
|
|
has been stopped by a
|
|
|
|
.B SIGSTOP
|
|
|
|
(or other stopping signal).
|
2013-02-16 08:50:27 +00:00
|
|
|
See the "group-stop" subsection for additional information.
|
|
|
|
.B PTRACE_LISTEN
|
intro.1, _syscall.2, access.2, arch_prctl.2, cacheflush.2, chown.2, clock_getres.2, clone.2, create_module.2, fcntl.2, flock.2, get_kernel_syms.2, get_robust_list.2, get_thread_area.2, getcpu.2, getpriority.2, getrlimit.2, getrusage.2, ioprio_set.2, kexec_load.2, madvise.2, mbind.2, migrate_pages.2, mknod.2, mmap.2, mount.2, move_pages.2, mprotect.2, open.2, pause.2, pciconfig_read.2, perf_event_open.2, prctl.2, ptrace.2, query_module.2, read.2, reboot.2, recv.2, s390_runtime_instr.2, sched_setscheduler.2, select_tut.2, send.2, set_mempolicy.2, setfsgid.2, setfsuid.2, sigaction.2, spu_create.2, spu_run.2, stime.2, swapon.2, syslog.2, timer_create.2, timer_getoverrun.2, times.2, tkill.2, umount.2, unimplemented.2, ustat.2, vm86.2, wait.2, abs.3, aio_read.3, aio_write.3, bsd_signal.3, catgets.3, clearenv.3, cmsg.3, dbopen.3, dirfd.3, dlopen.3, exec.3, fenv.3, ferror.3, fmemopen.3, fnmatch.3, fopen.3, futimes.3, getaddrinfo.3, getifaddrs.3, getipnodebyname.3, hsearch.3, if_nameindex.3, inet_pton.3, mblen.3, mbrlen.3, mbsrtowcs.3, mbtowc.3, mcheck.3, memfrob.3, mq_notify.3, netlink.3, posix_memalign.3, printf.3, pthread_attr_setscope.3, pthread_cleanup_push.3, pthread_kill_other_threads_np.3, pthread_self.3, pthread_setcancelstate.3, pthread_setconcurrency.3, raise.3, resolver.3, rpc.3, rtime.3, rtnetlink.3, scanf.3, setbuf.3, setnetgrent.3, shm_open.3, sigpause.3, sigset.3, sigwait.3, sockatmark.3, strcasecmp.3, strcmp.3, strdup.3, strftime.3, strptime.3, strsignal.3, strverscmp.3, sysv_signal.3, termios.3, wcrtomb.3, wcsnlen.3, wcsnrtombs.3, wcsrtombs.3, wctomb.3, wprintf.3, console_codes.4, cpuid.4, msr.4, rtc.4, sk98lin.4, st.4, tty.4, charmap.5, core.5, elf.5, hosts.equiv.5, proc.5, resolv.conf.5, services.5, slabinfo.5, arp.7, bootparam.7, capabilities.7, charsets.7, cpuset.7, ddp.7, epoll.7, feature_test_macros.7, futex.7, hier.7, icmp.7, inotify.7, ip.7, ipv6.7, man-pages.7, mdoc.7, mdoc.samples.7, netdevice.7, netlink.7, numa.7, packet.7, path_resolution.7, posixoptions.7, pthreads.7, raw.7, rtld-audit.7, rtnetlink.7, sem_overview.7, sigevent.7, socket.7, spufs.7, tcp.7, udp.7, unicode.7, uri.7, utf-8.7, intro.8, ldconfig.8, sync.8: Global fix: fix placement of word "only"
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2013-03-31 08:53:00 +00:00
|
|
|
works only on tracees attached by
|
2013-02-16 08:50:27 +00:00
|
|
|
.BR PTRACE_SEIZE .
|
|
|
|
.TP
|
2007-06-21 05:38:48 +00:00
|
|
|
.B PTRACE_KILL
|
2011-09-26 17:33:04 +00:00
|
|
|
Send the tracee a
|
2007-06-21 05:38:48 +00:00
|
|
|
.B SIGKILL
|
|
|
|
to terminate it.
|
2011-09-26 17:33:04 +00:00
|
|
|
.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.
|
2011-10-01 05:39:39 +00:00
|
|
|
.\" [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.]
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
2013-02-16 08:50:27 +00:00
|
|
|
.BR PTRACE_INTERRUPT " (since Linux 3.4)"
|
2013-02-16 09:22:49 +00:00
|
|
|
Stop a tracee.
|
2013-06-30 21:27:11 +00:00
|
|
|
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
|
2013-07-10 18:35:48 +00:00
|
|
|
and
|
2013-06-30 21:27:11 +00:00
|
|
|
.I WSTOPSIG(status)
|
2013-07-10 18:35:48 +00:00
|
|
|
returns the stop signal.
|
2013-06-30 21:27:11 +00:00
|
|
|
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.
|
2013-12-31 06:59:13 +00:00
|
|
|
If none of the above applies (for example, if the tracee is running in user
|
|
|
|
space), it stops with
|
2013-06-30 21:27:11 +00:00
|
|
|
.B PTRACE_EVENT_STOP
|
|
|
|
with
|
|
|
|
.I WSTOPSIG(status)
|
|
|
|
==
|
|
|
|
.BR SIGTRAP .
|
2013-02-16 08:50:27 +00:00
|
|
|
.B PTRACE_INTERRUPT
|
|
|
|
only works on tracees attached by
|
|
|
|
.BR PTRACE_SEIZE .
|
|
|
|
.TP
|
2007-06-21 05:38:48 +00:00
|
|
|
.B PTRACE_ATTACH
|
2011-09-26 17:33:04 +00:00
|
|
|
Attach to the process specified in
|
2004-11-03 13:51:07 +00:00
|
|
|
.IR pid ,
|
2011-09-24 06:29:34 +00:00
|
|
|
making it a tracee of the calling process.
|
2011-10-01 05:39:39 +00:00
|
|
|
.\" 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.
|
2011-09-24 06:29:34 +00:00
|
|
|
.\" ; 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
|
2007-06-21 05:38:48 +00:00
|
|
|
.BR SIGSTOP ,
|
|
|
|
but will not necessarily have stopped
|
2006-03-25 21:28:28 +00:00
|
|
|
by the completion of this call; use
|
2011-09-26 17:33:04 +00:00
|
|
|
.BR waitpid (2)
|
2011-09-25 05:30:51 +00:00
|
|
|
to wait for the tracee to stop.
|
2011-09-26 17:33:04 +00:00
|
|
|
See the "Attaching and detaching" subsection for additional information.
|
|
|
|
.RI ( addr
|
|
|
|
and
|
|
|
|
.I data
|
|
|
|
are ignored.)
|
2015-10-08 11:05:06 +00:00
|
|
|
|
2016-06-11 10:08:08 +00:00
|
|
|
Permission to perform a
|
|
|
|
.BR PTRACE_ATTACH
|
|
|
|
is governed by a ptrace access mode
|
|
|
|
.B PTRACE_MODE_ATTACH_REALCREDS
|
|
|
|
check; see below.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
2013-02-16 08:50:27 +00:00
|
|
|
.BR PTRACE_SEIZE " (since Linux 3.4)"
|
2016-03-28 04:36:26 +00:00
|
|
|
.\"
|
|
|
|
.\" 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.
|
|
|
|
.\"
|
2013-02-16 08:50:27 +00:00
|
|
|
Attach to the process specified in
|
|
|
|
.IR pid ,
|
|
|
|
making it a tracee of the calling process.
|
|
|
|
Unlike
|
|
|
|
.BR PTRACE_ATTACH ,
|
|
|
|
.B PTRACE_SEIZE
|
2013-02-16 09:22:49 +00:00
|
|
|
does not stop the process.
|
2015-02-11 13:20:35 +00:00
|
|
|
Group-stops are reported as
|
|
|
|
.B PTRACE_EVENT_STOP
|
2015-02-11 13:48:03 +00:00
|
|
|
and
|
2015-02-11 13:20:35 +00:00
|
|
|
.I WSTOPSIG(status)
|
2015-02-11 13:48:03 +00:00
|
|
|
returns the stop signal.
|
2015-02-11 13:20:35 +00:00
|
|
|
Automatically attached children stop with
|
|
|
|
.B PTRACE_EVENT_STOP
|
2015-02-11 13:48:03 +00:00
|
|
|
and
|
2015-02-11 13:20:35 +00:00
|
|
|
.I WSTOPSIG(status)
|
2015-02-11 13:48:03 +00:00
|
|
|
returns
|
2015-02-11 13:20:35 +00:00
|
|
|
.B SIGTRAP
|
|
|
|
instead of having
|
|
|
|
.B SIGSTOP
|
|
|
|
signal delivered to them.
|
2015-10-19 12:30:51 +00:00
|
|
|
.BR execve (2)
|
2015-02-11 13:20:35 +00:00
|
|
|
does not deliver an extra
|
2015-02-11 13:48:03 +00:00
|
|
|
.BR SIGTRAP .
|
2013-02-16 09:22:49 +00:00
|
|
|
Only a
|
2013-02-16 08:50:27 +00:00
|
|
|
.BR PTRACE_SEIZE d
|
|
|
|
process can accept
|
|
|
|
.B PTRACE_INTERRUPT
|
|
|
|
and
|
|
|
|
.B PTRACE_LISTEN
|
|
|
|
commands.
|
2015-02-11 13:20:35 +00:00
|
|
|
The "seized" behavior just described is inherited by
|
|
|
|
children that are automatically attached using
|
|
|
|
.BR PTRACE_O_TRACEFORK ,
|
|
|
|
.BR PTRACE_O_TRACEVFORK ,
|
|
|
|
and
|
|
|
|
.BR PTRACE_O_TRACECLONE .
|
2013-02-16 08:50:27 +00:00
|
|
|
.I addr
|
|
|
|
must be zero.
|
|
|
|
.I data
|
|
|
|
contains a bit mask of ptrace options to activate immediately.
|
2016-06-11 10:09:18 +00:00
|
|
|
|
|
|
|
Permission to perform a
|
|
|
|
.BR PTRACE_SEIZE
|
|
|
|
is governed by a ptrace access mode
|
|
|
|
.B PTRACE_MODE_ATTACH_REALCREDS
|
|
|
|
check; see below.
|
2016-11-08 13:07:31 +00:00
|
|
|
.\"
|
|
|
|
.TP
|
|
|
|
.BR PTRACE_SECCOMP_GET_FILTER " (since Linux 4.4)"
|
|
|
|
.\" commit f8e529ed941ba2bbcbf310b575d968159ce7e895
|
|
|
|
This operation allows the tracer to dump the tracee's
|
|
|
|
classic BPF filters.
|
|
|
|
|
|
|
|
.I addr
|
|
|
|
is an integer specifying the index of the filter to be dumped.
|
|
|
|
The most recently installed filter has the index 0.
|
|
|
|
If
|
|
|
|
.I addr
|
|
|
|
is greater than the number of installed filters,
|
|
|
|
the operation fails with the error
|
|
|
|
.BR ENOENT .
|
|
|
|
|
|
|
|
.I data
|
|
|
|
is either a pointer to a
|
|
|
|
.IR "struct sock_filter"
|
|
|
|
array that is large enough to store the BPF program,
|
|
|
|
or NULL if the program is not to be stored.
|
|
|
|
|
|
|
|
Upon success,
|
|
|
|
the return value is the number of instructions in the BPF program.
|
|
|
|
If
|
|
|
|
.I data
|
|
|
|
was NULL, then this return value can be used to correctly size the
|
|
|
|
.IR "struct sock_filter"
|
|
|
|
array passed in a subsequent call.
|
|
|
|
|
|
|
|
This operation fails with the error
|
|
|
|
.B EACCESS
|
|
|
|
if the caller does not have the
|
|
|
|
.B CAP_SYS_ADMIN
|
|
|
|
capability or if the caller is in strict or filter seccomp mode.
|
|
|
|
If the filter referred to by
|
|
|
|
.I addr
|
|
|
|
is not a classic BPF filter, the operation fails with the error
|
|
|
|
.BR EMEDIUMTYPE .
|
|
|
|
|
|
|
|
This operation is available if the kernel was configured with both the
|
|
|
|
.B CONFIG_SECCOMP_FILTER
|
|
|
|
and the
|
|
|
|
.B CONFIG_CHECKPOINT_RESTORE
|
|
|
|
options.
|
2013-02-16 08:50:27 +00:00
|
|
|
.TP
|
2007-06-21 05:38:48 +00:00
|
|
|
.B PTRACE_DETACH
|
2011-09-26 17:33:04 +00:00
|
|
|
Restart the stopped tracee as for
|
2007-06-21 05:38:48 +00:00
|
|
|
.BR PTRACE_CONT ,
|
2011-09-26 17:33:04 +00:00
|
|
|
but first detach from it.
|
|
|
|
Under Linux, a tracee can be detached in this way regardless
|
|
|
|
of which method was used to initiate tracing.
|
|
|
|
.RI ( addr
|
|
|
|
is ignored.)
|
2016-11-08 13:07:31 +00:00
|
|
|
.\"
|
2016-11-01 13:25:06 +00:00
|
|
|
.TP
|
|
|
|
.BR PTRACE_GET_THREAD_AREA " (since Linux 2.6.0)"
|
|
|
|
This operation performs a similar task to
|
|
|
|
.BR get_thread_area (2).
|
|
|
|
It reads the TLS entry in the GDT whose index is given in
|
|
|
|
.IR addr ,
|
|
|
|
placing a copy of the entry into the
|
|
|
|
.IR "struct user_desc"
|
|
|
|
pointed to by
|
|
|
|
.IR data .
|
|
|
|
(By contrast with
|
|
|
|
.BR get_thread_area (2),
|
|
|
|
the
|
|
|
|
.I entry_number
|
|
|
|
of the
|
|
|
|
.IR "struct user_desc"
|
|
|
|
is ignored.)
|
|
|
|
.TP
|
|
|
|
.BR PTRACE_SET_THREAD_AREA " (since Linux 2.6.0)"
|
|
|
|
This operation performs a similar task to
|
|
|
|
.BR set_thread_area (2).
|
|
|
|
It sets the TLS entry in the GDT whose index is given in
|
|
|
|
.IR addr ,
|
|
|
|
assigning it the data supplied in the
|
|
|
|
.IR "struct user_desc"
|
|
|
|
pointed to by
|
|
|
|
.IR data .
|
|
|
|
(By contrast with
|
|
|
|
.BR set_thread_area (2),
|
|
|
|
the
|
|
|
|
.I entry_number
|
|
|
|
of the
|
|
|
|
.IR "struct user_desc"
|
|
|
|
is ignored; in other words,
|
|
|
|
this ptrace operation can't be used to allocate a free TLS entry.)
|
|
|
|
.\"
|
2011-09-24 06:29:34 +00:00
|
|
|
.SS Death under ptrace
|
2011-09-26 17:33:04 +00:00
|
|
|
When a (possibly multithreaded) process receives a killing signal
|
|
|
|
(one whose disposition is set to
|
|
|
|
.B SIG_DFL
|
|
|
|
and whose default action is to kill the process),
|
2011-09-25 05:30:51 +00:00
|
|
|
all threads exit.
|
|
|
|
Tracees report their death to their tracer(s).
|
2011-09-26 17:33:04 +00:00
|
|
|
Notification of this event is delivered via
|
|
|
|
.BR waitpid (2).
|
|
|
|
.LP
|
|
|
|
Note that the killing signal will first cause signal-delivery-stop
|
|
|
|
(on one tracee only),
|
|
|
|
and only after it is injected by the tracer
|
|
|
|
(or after it was dispatched to a thread which isn't traced),
|
|
|
|
will death from the signal happen on
|
|
|
|
.I all
|
|
|
|
tracees within a multithreaded process.
|
|
|
|
(The term "signal-delivery-stop" is explained below.)
|
2011-09-24 06:29:34 +00:00
|
|
|
.LP
|
2011-09-26 17:33:04 +00:00
|
|
|
.B SIGKILL
|
2012-08-03 04:28:46 +00:00
|
|
|
does not generate signal-delivery-stop and
|
|
|
|
therefore the tracer can't suppress it.
|
2011-09-26 17:33:04 +00:00
|
|
|
.B SIGKILL
|
|
|
|
kills even within system calls
|
|
|
|
(syscall-exit-stop is not generated prior to death by
|
|
|
|
.BR SIGKILL ).
|
|
|
|
The net effect is that
|
|
|
|
.B SIGKILL
|
|
|
|
always kills the process (all its threads),
|
|
|
|
even if some threads of the process are ptraced.
|
|
|
|
.LP
|
|
|
|
When the tracee calls
|
|
|
|
.BR _exit (2),
|
|
|
|
it reports its death to its tracer.
|
2011-09-24 06:29:34 +00:00
|
|
|
Other threads are not affected.
|
|
|
|
.LP
|
2011-09-26 17:33:04 +00:00
|
|
|
When any thread executes
|
|
|
|
.BR exit_group (2),
|
|
|
|
every tracee in its thread group reports its death to its tracer.
|
2011-09-24 06:29:34 +00:00
|
|
|
.LP
|
2011-09-26 17:33:04 +00:00
|
|
|
If the
|
|
|
|
.B PTRACE_O_TRACEEXIT
|
|
|
|
option is on,
|
|
|
|
.B PTRACE_EVENT_EXIT
|
|
|
|
will happen before actual death.
|
|
|
|
This applies to exits via
|
|
|
|
.BR exit (2),
|
|
|
|
.BR exit_group (2),
|
|
|
|
and signal deaths (except
|
2015-05-12 10:43:48 +00:00
|
|
|
.BR SIGKILL ,
|
|
|
|
depending on the kernel version; see BUGS below),
|
2011-09-26 17:33:04 +00:00
|
|
|
and when threads are torn down on
|
|
|
|
.BR execve (2)
|
|
|
|
in a multithreaded process.
|
|
|
|
.LP
|
|
|
|
The tracer cannot assume that the ptrace-stopped tracee exists.
|
|
|
|
There are many scenarios when the tracee may die while stopped (such as
|
|
|
|
.BR SIGKILL ).
|
2012-03-05 19:54:38 +00:00
|
|
|
Therefore, the tracer must be prepared to handle an
|
2011-09-26 17:33:04 +00:00
|
|
|
.B ESRCH
|
|
|
|
error on any ptrace operation.
|
|
|
|
Unfortunately, the same error is returned if the tracee
|
|
|
|
exists but is not ptrace-stopped
|
|
|
|
(for commands which require a stopped tracee),
|
|
|
|
or if it is not traced by the process which issued the ptrace call.
|
|
|
|
The tracer needs to keep track of the stopped/running state of the tracee,
|
|
|
|
and interpret
|
|
|
|
.B ESRCH
|
|
|
|
as "tracee died unexpectedly" only if it knows that the tracee has
|
|
|
|
been observed to enter ptrace-stop.
|
|
|
|
Note that there is no guarantee that
|
|
|
|
.I waitpid(WNOHANG)
|
|
|
|
will reliably report the tracee's death status if a
|
|
|
|
ptrace operation returned
|
|
|
|
.BR ESRCH .
|
|
|
|
.I waitpid(WNOHANG)
|
|
|
|
may return 0 instead.
|
|
|
|
In other words, the tracee may be "not yet fully dead",
|
|
|
|
but already refusing ptrace requests.
|
|
|
|
.LP
|
|
|
|
The tracer can't assume that the tracee
|
|
|
|
.I always
|
|
|
|
ends its life by reporting
|
|
|
|
.I WIFEXITED(status)
|
|
|
|
or
|
2011-10-01 05:39:39 +00:00
|
|
|
.IR WIFSIGNALED(status) ;
|
|
|
|
there are cases where this does not occur.
|
|
|
|
For example, if a thread other than thread group leader does an
|
|
|
|
.BR execve (2),
|
|
|
|
it disappears;
|
|
|
|
its PID will never be seen again,
|
|
|
|
and any subsequent ptrace stops will be reported under
|
|
|
|
the thread group leader's PID.
|
2011-09-24 06:29:34 +00:00
|
|
|
.SS Stopped states
|
|
|
|
A tracee can be in two states: running or stopped.
|
2013-07-10 18:35:48 +00:00
|
|
|
For the purposes of ptrace, a tracee which is blocked in a system call
|
2013-06-30 21:27:11 +00:00
|
|
|
(such as
|
|
|
|
.BR read (2),
|
2013-07-10 18:35:48 +00:00
|
|
|
.BR pause (2),
|
|
|
|
etc.)
|
|
|
|
is nevertheless considered to be running, even if the tracee is blocked
|
2013-06-30 21:27:11 +00:00
|
|
|
for a long time.
|
|
|
|
The state of the tracee after
|
|
|
|
.BR PTRACE_LISTEN
|
|
|
|
is somewhat of a gray area: it is not in any ptrace-stop (ptrace commands
|
2013-07-10 18:35:48 +00:00
|
|
|
won't work on it, and it will deliver
|
|
|
|
.BR waitpid (2)
|
|
|
|
notifications),
|
2013-06-30 21:27:11 +00:00
|
|
|
but it also may be considered "stopped" because
|
|
|
|
it is not executing instructions (is not scheduled), and if it was
|
|
|
|
in group-stop before
|
|
|
|
.BR PTRACE_LISTEN ,
|
2013-07-10 18:35:48 +00:00
|
|
|
it will not respond to signals until
|
|
|
|
.B SIGCONT
|
|
|
|
is received.
|
2011-09-24 06:29:34 +00:00
|
|
|
.LP
|
2011-09-26 17:33:04 +00:00
|
|
|
There are many kinds of states when the tracee is stopped, and in ptrace
|
2011-09-25 05:30:51 +00:00
|
|
|
discussions they are often conflated.
|
2011-09-26 17:33:04 +00:00
|
|
|
Therefore, it is important to use precise terms.
|
2011-09-24 06:29:34 +00:00
|
|
|
.LP
|
2011-09-26 17:33:04 +00:00
|
|
|
In this manual page, any stopped state in which the tracee is ready
|
|
|
|
to accept ptrace commands from the tracer is called
|
|
|
|
.IR ptrace-stop .
|
2011-09-25 05:30:51 +00:00
|
|
|
Ptrace-stops can
|
2011-09-26 17:33:04 +00:00
|
|
|
be further subdivided into
|
|
|
|
.IR signal-delivery-stop ,
|
|
|
|
.IR group-stop ,
|
|
|
|
.IR syscall-stop ,
|
2016-11-16 05:52:27 +00:00
|
|
|
.IR PTRACE_EVENT stops,
|
2011-09-26 17:33:04 +00:00
|
|
|
and so on.
|
|
|
|
These stopped states are described in detail below.
|
|
|
|
.LP
|
|
|
|
When the running tracee enters ptrace-stop, it notifies its tracer using
|
|
|
|
.BR waitpid (2)
|
|
|
|
(or one of the other "wait" system calls).
|
|
|
|
Most of this manual page assumes that the tracer waits with:
|
|
|
|
.LP
|
|
|
|
pid = waitpid(pid_or_minus_1, &status, __WALL);
|
|
|
|
.LP
|
|
|
|
Ptrace-stopped tracees are reported as returns with
|
|
|
|
.I pid
|
|
|
|
greater than 0 and
|
|
|
|
.I WIFSTOPPED(status)
|
|
|
|
true.
|
2011-10-01 05:39:39 +00:00
|
|
|
.\" Denys Vlasenko:
|
|
|
|
.\" Do we require __WALL usage, or will just using 0 be ok? (With 0,
|
|
|
|
.\" I am not 100% sure there aren't ugly corner cases.) Are the
|
2011-09-26 17:33:04 +00:00
|
|
|
.\" rules different if user wants to use waitid? Will waitid require
|
|
|
|
.\" WEXITED?
|
|
|
|
.\"
|
2011-09-24 06:29:34 +00:00
|
|
|
.LP
|
2011-09-26 17:33:04 +00:00
|
|
|
The
|
|
|
|
.B __WALL
|
|
|
|
flag does not include the
|
|
|
|
.B WSTOPPED
|
|
|
|
and
|
|
|
|
.B WEXITED
|
|
|
|
flags, but implies their functionality.
|
|
|
|
.LP
|
|
|
|
Setting the
|
|
|
|
.B WCONTINUED
|
|
|
|
flag when calling
|
|
|
|
.BR waitpid (2)
|
|
|
|
is not recommended: the "continued" state is per-process and
|
|
|
|
consuming it can confuse the real parent of the tracee.
|
|
|
|
.LP
|
|
|
|
Use of the
|
|
|
|
.B WNOHANG
|
|
|
|
flag may cause
|
|
|
|
.BR waitpid (2)
|
|
|
|
to return 0 ("no wait results available yet")
|
|
|
|
even if the tracer knows there should be a notification.
|
|
|
|
Example:
|
|
|
|
.nf
|
|
|
|
|
2012-08-03 04:28:46 +00:00
|
|
|
errno = 0;
|
|
|
|
ptrace(PTRACE_CONT, pid, 0L, 0L);
|
|
|
|
if (errno == ESRCH) {
|
|
|
|
/* tracee is dead */
|
|
|
|
r = waitpid(tracee, &status, __WALL | WNOHANG);
|
|
|
|
/* r can still be 0 here! */
|
|
|
|
}
|
2011-09-26 17:33:04 +00:00
|
|
|
.fi
|
adjtimex.2, bind.2, cacheflush.2, clone.2, fallocate.2, fanotify_init.2, fanotify_mark.2, flock.2, futex.2, getdents.2, getpriority.2, getrlimit.2, gettid.2, gettimeofday.2, ioprio_set.2, kexec_load.2, migrate_pages.2, modify_ldt.2, mount.2, move_pages.2, mprotect.2, msgop.2, nfsservctl.2, perf_event_open.2, pread.2, ptrace.2, recvmmsg.2, rename.2, restart_syscall.2, sched_setattr.2, send.2, shmop.2, shutdown.2, sigaction.2, signalfd.2, syscalls.2, timer_create.2, timerfd_create.2, tkill.2, vmsplice.2, wait.2, aio_init.3, confstr.3, exit.3, fmemopen.3, fopen.3, getaddrinfo.3, getauxval.3, getspnam.3, isalpha.3, isatty.3, mallinfo.3, malloc.3, mallopt.3, psignal.3, pthread_attr_setinheritsched.3, qecvt.3, queue.3, rtnetlink.3, strerror.3, strftime.3, toupper.3, towlower.3, towupper.3, initrd.4, locale.5, proc.5, bootparam.7, capabilities.7, ddp.7, fanotify.7, icmp.7, inotify.7, ip.7, ipv6.7, netdevice.7, netlink.7, path_resolution.7, rtld-audit.7, rtnetlink.7, sched.7, signal.7, socket.7, svipc.7, tcp.7, unix.7, ld.so.8: srcfix: Update FIXMEs
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2014-08-21 21:47:44 +00:00
|
|
|
.\" FIXME .
|
2011-09-26 17:33:04 +00:00
|
|
|
.\" waitid usage? WNOWAIT?
|
|
|
|
.\" describe how wait notifications queue (or not queue)
|
2011-09-24 06:29:34 +00:00
|
|
|
.LP
|
|
|
|
The following kinds of ptrace-stops exist: signal-delivery-stops,
|
2012-03-23 23:12:33 +00:00
|
|
|
group-stops,
|
|
|
|
.B PTRACE_EVENT
|
|
|
|
stops, syscall-stops.
|
2011-09-26 17:33:04 +00:00
|
|
|
They all are reported by
|
|
|
|
.BR waitpid (2)
|
|
|
|
with
|
|
|
|
.I WIFSTOPPED(status)
|
|
|
|
true.
|
|
|
|
They may be differentiated by examining the value
|
|
|
|
.IR status>>8 ,
|
|
|
|
and if there is ambiguity in that value, by querying
|
|
|
|
.BR PTRACE_GETSIGINFO .
|
|
|
|
(Note: the
|
|
|
|
.I WSTOPSIG(status)
|
2012-02-26 18:36:30 +00:00
|
|
|
macro can't be used to perform this examination,
|
2011-10-01 05:39:39 +00:00
|
|
|
because it returns the value
|
2012-05-06 21:42:31 +00:00
|
|
|
.IR "(status>>8)\ &\ 0xff" .)
|
2011-09-24 06:29:34 +00:00
|
|
|
.SS Signal-delivery-stop
|
2011-09-26 17:33:04 +00:00
|
|
|
When a (possibly multithreaded) process receives any signal except
|
|
|
|
.BR SIGKILL ,
|
|
|
|
the kernel selects an arbitrary thread which handles the signal.
|
|
|
|
(If the signal is generated with
|
|
|
|
.BR tgkill (2),
|
|
|
|
the target thread can be explicitly selected by the caller.)
|
|
|
|
If the selected thread is traced, it enters signal-delivery-stop.
|
|
|
|
At this point, the signal is not yet delivered to the process,
|
|
|
|
and can be suppressed by the tracer.
|
|
|
|
If the tracer doesn't suppress the signal,
|
|
|
|
it passes the signal to the tracee in the next ptrace restart request.
|
2011-09-25 05:30:51 +00:00
|
|
|
This second step of signal delivery is called
|
2011-09-26 17:33:04 +00:00
|
|
|
.I "signal injection"
|
|
|
|
in this manual page.
|
|
|
|
Note that if the signal is blocked,
|
|
|
|
signal-delivery-stop doesn't happen until the signal is unblocked,
|
|
|
|
with the usual exception that
|
|
|
|
.B SIGSTOP
|
|
|
|
can't be blocked.
|
|
|
|
.LP
|
|
|
|
Signal-delivery-stop is observed by the tracer as
|
|
|
|
.BR waitpid (2)
|
|
|
|
returning with
|
|
|
|
.I WIFSTOPPED(status)
|
2012-03-19 18:18:20 +00:00
|
|
|
true, with the signal returned by
|
2011-09-26 17:33:04 +00:00
|
|
|
.IR WSTOPSIG(status) .
|
2012-03-19 18:18:20 +00:00
|
|
|
If the signal is
|
2011-09-26 17:33:04 +00:00
|
|
|
.BR SIGTRAP ,
|
|
|
|
this may be a different kind of ptrace-stop;
|
|
|
|
see the "Syscall-stops" and "execve" sections below for details.
|
2011-09-25 05:30:51 +00:00
|
|
|
If
|
2011-09-26 17:33:04 +00:00
|
|
|
.I WSTOPSIG(status)
|
|
|
|
returns a stopping signal, this may be a group-stop; see below.
|
2011-09-24 06:29:34 +00:00
|
|
|
.SS Signal injection and suppression
|
2011-09-26 17:33:04 +00:00
|
|
|
After signal-delivery-stop is observed by the tracer,
|
|
|
|
the tracer should restart the tracee with the call
|
2011-09-24 06:29:34 +00:00
|
|
|
.LP
|
2011-09-26 17:33:04 +00:00
|
|
|
ptrace(PTRACE_restart, pid, 0, sig)
|
2011-09-24 06:29:34 +00:00
|
|
|
.LP
|
2011-09-26 17:33:04 +00:00
|
|
|
where
|
|
|
|
.B PTRACE_restart
|
|
|
|
is one of the restarting ptrace requests.
|
|
|
|
If
|
|
|
|
.I sig
|
|
|
|
is 0, then a signal is not delivered.
|
|
|
|
Otherwise, the signal
|
|
|
|
.I sig
|
|
|
|
is delivered.
|
|
|
|
This operation is called
|
|
|
|
.I "signal injection"
|
|
|
|
in this manual page, to distinguish it from signal-delivery-stop.
|
|
|
|
.LP
|
2011-10-01 05:39:39 +00:00
|
|
|
The
|
2011-09-26 17:33:04 +00:00
|
|
|
.I sig
|
|
|
|
value may be different from the
|
|
|
|
.I WSTOPSIG(status)
|
|
|
|
value: the tracer can cause a different signal to be injected.
|
|
|
|
.LP
|
|
|
|
Note that a suppressed signal still causes system calls to return
|
2011-09-25 05:30:51 +00:00
|
|
|
prematurely.
|
2014-03-26 05:24:50 +00:00
|
|
|
In this case, system calls will be restarted: the tracer will
|
2012-03-19 18:29:29 +00:00
|
|
|
observe the tracee to reexecute the interrupted system call (or
|
2012-03-23 23:12:33 +00:00
|
|
|
.BR restart_syscall (2)
|
2014-05-19 08:10:03 +00:00
|
|
|
system call for a few system calls which use a different mechanism
|
2012-03-19 18:18:20 +00:00
|
|
|
for restarting) if the tracer uses
|
|
|
|
.BR PTRACE_SYSCALL .
|
|
|
|
Even system calls (such as
|
2012-03-23 23:12:33 +00:00
|
|
|
.BR poll (2))
|
2012-03-19 18:18:20 +00:00
|
|
|
which are not restartable after signal are restarted after
|
2012-03-19 18:29:29 +00:00
|
|
|
signal is suppressed;
|
2014-05-19 08:10:03 +00:00
|
|
|
however, kernel bugs exist which cause some system calls to fail with
|
2011-09-26 17:33:04 +00:00
|
|
|
.B EINTR
|
|
|
|
even though no observable signal is injected to the tracee.
|
2011-09-24 06:29:34 +00:00
|
|
|
.LP
|
2011-10-01 05:39:39 +00:00
|
|
|
Restarting ptrace commands issued in ptrace-stops other than
|
2011-09-26 17:33:04 +00:00
|
|
|
signal-delivery-stop are not guaranteed to inject a signal, even if
|
|
|
|
.I sig
|
2011-09-25 05:30:51 +00:00
|
|
|
is nonzero.
|
2011-09-26 17:33:04 +00:00
|
|
|
No error is reported; a nonzero
|
|
|
|
.I sig
|
|
|
|
may simply be ignored.
|
|
|
|
Ptrace users should not try to "create a new signal" this way: use
|
|
|
|
.BR tgkill (2)
|
|
|
|
instead.
|
2011-09-24 06:29:34 +00:00
|
|
|
.LP
|
2011-10-01 05:39:39 +00:00
|
|
|
The fact that signal injection requests may be ignored
|
|
|
|
when restarting the tracee after
|
|
|
|
ptrace stops that are not signal-delivery-stops
|
|
|
|
is a cause of confusion among ptrace users.
|
2011-09-26 17:33:04 +00:00
|
|
|
One typical scenario is that the tracer observes group-stop,
|
|
|
|
mistakes it for signal-delivery-stop, restarts the tracee with
|
|
|
|
|
2013-02-16 08:50:27 +00:00
|
|
|
ptrace(PTRACE_restart, pid, 0, stopsig)
|
2011-09-26 17:33:04 +00:00
|
|
|
|
|
|
|
with the intention of injecting
|
|
|
|
.IR stopsig ,
|
|
|
|
but
|
|
|
|
.I stopsig
|
|
|
|
gets ignored and the tracee continues to run.
|
|
|
|
.LP
|
|
|
|
The
|
|
|
|
.B SIGCONT
|
|
|
|
signal has a side effect of waking up (all threads of)
|
|
|
|
a group-stopped process.
|
|
|
|
This side effect happens before signal-delivery-stop.
|
2012-03-23 23:12:33 +00:00
|
|
|
The tracer can't suppress this side effect (it can
|
2011-09-26 17:33:04 +00:00
|
|
|
only suppress signal injection, which only causes the
|
|
|
|
.BR SIGCONT
|
|
|
|
handler to not be executed in the tracee, if such a handler is installed).
|
|
|
|
In fact, waking up from group-stop may be followed by
|
|
|
|
signal-delivery-stop for signal(s)
|
|
|
|
.I other than
|
|
|
|
.BR SIGCONT ,
|
|
|
|
if they were pending when
|
|
|
|
.B SIGCONT
|
|
|
|
was delivered.
|
|
|
|
In other words,
|
|
|
|
.B SIGCONT
|
|
|
|
may be not the first signal observed by the tracee after it was sent.
|
|
|
|
.LP
|
|
|
|
Stopping signals cause (all threads of) a process to enter group-stop.
|
2011-09-24 06:29:34 +00:00
|
|
|
This side effect happens after signal injection, and therefore can be
|
2011-09-26 17:33:04 +00:00
|
|
|
suppressed by the tracer.
|
|
|
|
.LP
|
2012-02-26 18:36:30 +00:00
|
|
|
In Linux 2.4 and earlier, the
|
|
|
|
.B SIGSTOP
|
|
|
|
signal can't be injected.
|
|
|
|
.\" In the Linux 2.4 sources, in arch/i386/kernel/signal.c::do_signal(),
|
|
|
|
.\" there is:
|
2012-03-05 19:54:38 +00:00
|
|
|
.\"
|
2012-02-26 18:36:30 +00:00
|
|
|
.\" /* The debugger continued. Ignore SIGSTOP. */
|
|
|
|
.\" if (signr == SIGSTOP)
|
|
|
|
.\" continue;
|
|
|
|
.LP
|
2011-09-26 17:33:04 +00:00
|
|
|
.B PTRACE_GETSIGINFO
|
|
|
|
can be used to retrieve a
|
|
|
|
.I siginfo_t
|
|
|
|
structure which corresponds to the delivered signal.
|
|
|
|
.B PTRACE_SETSIGINFO
|
|
|
|
may be used to modify it.
|
|
|
|
If
|
|
|
|
.B PTRACE_SETSIGINFO
|
|
|
|
has been used to alter
|
|
|
|
.IR siginfo_t ,
|
|
|
|
the
|
|
|
|
.I si_signo
|
|
|
|
field and the
|
|
|
|
.I sig
|
|
|
|
parameter in the restarting command must match,
|
2011-09-24 06:29:34 +00:00
|
|
|
otherwise the result is undefined.
|
|
|
|
.SS Group-stop
|
2011-09-26 17:33:04 +00:00
|
|
|
When a (possibly multithreaded) process receives a stopping signal,
|
2011-09-25 05:30:51 +00:00
|
|
|
all threads stop.
|
|
|
|
If some threads are traced, they enter a group-stop.
|
2011-09-26 17:33:04 +00:00
|
|
|
Note that the stopping signal will first cause signal-delivery-stop
|
|
|
|
(on one tracee only), and only after it is injected by the tracer
|
|
|
|
(or after it was dispatched to a thread which isn't traced),
|
|
|
|
will group-stop be initiated on
|
|
|
|
.I all
|
|
|
|
tracees within the multithreaded process.
|
|
|
|
As usual, every tracee reports its group-stop separately
|
|
|
|
to the corresponding tracer.
|
|
|
|
.LP
|
|
|
|
Group-stop is observed by the tracer as
|
|
|
|
.BR waitpid (2)
|
|
|
|
returning with
|
|
|
|
.I WIFSTOPPED(status)
|
|
|
|
true, with the stopping signal available via
|
|
|
|
.IR WSTOPSIG(status) .
|
|
|
|
The same result is returned by some other classes of ptrace-stops,
|
|
|
|
therefore the recommended practice is to perform the call
|
|
|
|
.LP
|
|
|
|
ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo)
|
|
|
|
.LP
|
|
|
|
The call can be avoided if the signal is not
|
|
|
|
.BR SIGSTOP ,
|
|
|
|
.BR SIGTSTP ,
|
|
|
|
.BR SIGTTIN ,
|
|
|
|
or
|
|
|
|
.BR SIGTTOU ;
|
|
|
|
only these four signals are stopping signals.
|
|
|
|
If the tracer sees something else, it can't be a group-stop.
|
|
|
|
Otherwise, the tracer needs to call
|
|
|
|
.BR PTRACE_GETSIGINFO .
|
|
|
|
If
|
|
|
|
.B PTRACE_GETSIGINFO
|
|
|
|
fails with
|
|
|
|
.BR EINVAL ,
|
|
|
|
then it is definitely a group-stop.
|
|
|
|
(Other failure codes are possible, such as
|
|
|
|
.B ESRCH
|
|
|
|
("no such process") if a
|
|
|
|
.B SIGKILL
|
|
|
|
killed the tracee.)
|
2011-09-24 06:29:34 +00:00
|
|
|
.LP
|
2013-07-10 18:35:48 +00:00
|
|
|
If tracee was attached using
|
2013-09-04 02:21:47 +00:00
|
|
|
.BR PTRACE_SEIZE ,
|
2013-07-10 18:35:48 +00:00
|
|
|
group-stop is indicated by
|
2013-06-30 21:27:11 +00:00
|
|
|
.BR PTRACE_EVENT_STOP :
|
2013-07-10 18:35:48 +00:00
|
|
|
.IR "status>>16 == PTRACE_EVENT_STOP" .
|
|
|
|
This allows detection of group-stops
|
|
|
|
without requiring an extra
|
2013-06-30 21:27:11 +00:00
|
|
|
.B PTRACE_GETSIGINFO
|
|
|
|
call.
|
|
|
|
.LP
|
2013-02-16 09:22:49 +00:00
|
|
|
As of Linux 2.6.38,
|
2011-09-26 17:33:04 +00:00
|
|
|
after the tracer sees the tracee ptrace-stop and until it
|
|
|
|
restarts or kills it, the tracee will not run,
|
|
|
|
and will not send notifications (except
|
|
|
|
.B SIGKILL
|
|
|
|
death) to the tracer, even if the tracer enters into another
|
|
|
|
.BR waitpid (2)
|
2011-09-25 05:30:51 +00:00
|
|
|
call.
|
2011-09-24 06:29:34 +00:00
|
|
|
.LP
|
2012-03-05 17:16:37 +00:00
|
|
|
The kernel behavior described in the previous paragraph
|
|
|
|
causes a problem with transparent handling of stopping signals.
|
|
|
|
If the tracer restarts the tracee after group-stop,
|
2012-02-26 18:36:30 +00:00
|
|
|
the stopping signal
|
2011-10-01 05:39:39 +00:00
|
|
|
is effectively ignored\(emthe tracee doesn't remain stopped, it runs.
|
2011-09-26 17:33:04 +00:00
|
|
|
If the tracer doesn't restart the tracee before entering into the next
|
|
|
|
.BR waitpid (2),
|
|
|
|
future
|
|
|
|
.B SIGCONT
|
2012-03-05 17:16:37 +00:00
|
|
|
signals will not be reported to the tracer;
|
|
|
|
this would cause the
|
2011-09-26 17:33:04 +00:00
|
|
|
.B SIGCONT
|
2012-03-05 17:16:37 +00:00
|
|
|
signals to have no effect on the tracee.
|
2013-02-16 08:50:27 +00:00
|
|
|
.LP
|
2013-02-16 09:22:49 +00:00
|
|
|
Since Linux 3.4, there is a method to overcome this problem: instead of
|
2013-02-16 08:50:27 +00:00
|
|
|
.BR PTRACE_CONT ,
|
|
|
|
a
|
|
|
|
.B PTRACE_LISTEN
|
|
|
|
command can be used to restart a tracee in a way where it does not execute,
|
2013-02-16 09:22:49 +00:00
|
|
|
but waits for a new event which it can report via
|
|
|
|
.BR waitpid (2)
|
|
|
|
(such as when
|
2013-02-16 08:50:27 +00:00
|
|
|
it is restarted by a
|
|
|
|
.BR SIGCONT ).
|
2011-09-24 06:29:34 +00:00
|
|
|
.SS PTRACE_EVENT stops
|
2011-09-26 17:33:04 +00:00
|
|
|
If the tracer sets
|
|
|
|
.B PTRACE_O_TRACE_*
|
|
|
|
options, the tracee will enter ptrace-stops called
|
|
|
|
.B PTRACE_EVENT
|
|
|
|
stops.
|
|
|
|
.LP
|
|
|
|
.B PTRACE_EVENT
|
|
|
|
stops are observed by the tracer as
|
|
|
|
.BR waitpid (2)
|
|
|
|
returning with
|
|
|
|
.IR WIFSTOPPED(status) ,
|
|
|
|
and
|
|
|
|
.I WSTOPSIG(status)
|
|
|
|
returns
|
|
|
|
.BR SIGTRAP .
|
|
|
|
An additional bit is set in the higher byte of the status word:
|
|
|
|
the value
|
|
|
|
.I status>>8
|
|
|
|
will be
|
|
|
|
|
|
|
|
(SIGTRAP | PTRACE_EVENT_foo << 8).
|
|
|
|
|
2011-09-25 05:30:51 +00:00
|
|
|
The following events exist:
|
2011-09-26 17:33:04 +00:00
|
|
|
.TP
|
|
|
|
.B PTRACE_EVENT_VFORK
|
|
|
|
Stop before return from
|
|
|
|
.BR vfork (2)
|
|
|
|
or
|
|
|
|
.BR clone (2)
|
|
|
|
with the
|
|
|
|
.B CLONE_VFORK
|
|
|
|
flag.
|
|
|
|
When the tracee is continued after this stop, it will wait for child to
|
|
|
|
exit/exec before continuing its execution
|
|
|
|
(in other words, the usual behavior on
|
|
|
|
.BR vfork (2)).
|
|
|
|
.TP
|
|
|
|
.B PTRACE_EVENT_FORK
|
|
|
|
Stop before return from
|
|
|
|
.BR fork (2)
|
|
|
|
or
|
|
|
|
.BR clone (2)
|
|
|
|
with the exit signal set to
|
|
|
|
.BR SIGCHLD .
|
|
|
|
.TP
|
|
|
|
.B PTRACE_EVENT_CLONE
|
|
|
|
Stop before return from
|
2012-03-23 23:12:33 +00:00
|
|
|
.BR clone (2).
|
2011-09-26 17:33:04 +00:00
|
|
|
.TP
|
|
|
|
.B PTRACE_EVENT_VFORK_DONE
|
|
|
|
Stop before return from
|
|
|
|
.BR vfork (2)
|
|
|
|
or
|
|
|
|
.BR clone (2)
|
|
|
|
with the
|
|
|
|
.B CLONE_VFORK
|
|
|
|
flag,
|
|
|
|
but after the child unblocked this tracee by exiting or execing.
|
2011-09-24 06:29:34 +00:00
|
|
|
.LP
|
2011-09-26 17:33:04 +00:00
|
|
|
For all four stops described above,
|
|
|
|
the stop occurs in the parent (i.e., the tracee),
|
|
|
|
not in the newly created thread.
|
|
|
|
.BR PTRACE_GETEVENTMSG
|
|
|
|
can be used to retrieve the new thread's ID.
|
|
|
|
.TP
|
|
|
|
.B PTRACE_EVENT_EXEC
|
|
|
|
Stop before return from
|
|
|
|
.BR execve (2).
|
2012-03-23 18:49:32 +00:00
|
|
|
Since Linux 3.0,
|
|
|
|
.BR PTRACE_GETEVENTMSG
|
|
|
|
returns the former thread ID.
|
2011-09-26 17:33:04 +00:00
|
|
|
.TP
|
|
|
|
.B PTRACE_EVENT_EXIT
|
|
|
|
Stop before exit (including death from
|
|
|
|
.BR exit_group (2)),
|
|
|
|
signal death, or exit caused by
|
|
|
|
.BR execve (2)
|
|
|
|
in a multithreaded process.
|
|
|
|
.B PTRACE_GETEVENTMSG
|
|
|
|
returns the exit status.
|
2011-09-25 05:30:51 +00:00
|
|
|
Registers can be examined
|
|
|
|
(unlike when "real" exit happens).
|
2011-09-26 17:33:04 +00:00
|
|
|
The tracee is still alive; it needs to be
|
|
|
|
.BR PTRACE_CONT ed
|
|
|
|
or
|
|
|
|
.BR PTRACE_DETACH ed
|
|
|
|
to finish exiting.
|
2013-02-16 08:50:27 +00:00
|
|
|
.TP
|
|
|
|
.B PTRACE_EVENT_STOP
|
|
|
|
Stop induced by
|
|
|
|
.B PTRACE_INTERRUPT
|
2013-07-10 18:40:14 +00:00
|
|
|
command, or group-stop, or initial ptrace-stop when a new child is attached
|
|
|
|
(only if attached using
|
2015-02-11 13:20:35 +00:00
|
|
|
.BR PTRACE_SEIZE ).
|
2015-01-18 06:26:17 +00:00
|
|
|
.TP
|
|
|
|
.B PTRACE_EVENT_SECCOMP
|
|
|
|
Stop triggered by a
|
|
|
|
.BR seccomp (2)
|
|
|
|
rule on tracee syscall entry when
|
|
|
|
.BR PTRACE_O_TRACESECCOMP
|
2015-01-18 11:09:19 +00:00
|
|
|
has been set by the tracer.
|
|
|
|
The seccomp event message data (from the
|
2015-01-18 06:26:17 +00:00
|
|
|
.BR SECCOMP_RET_DATA
|
2015-01-18 11:09:19 +00:00
|
|
|
portion of the seccomp filter rule) can be retrieved with
|
2016-11-17 07:21:01 +00:00
|
|
|
.BR PTRACE_GETEVENTMSG .
|
|
|
|
The semantics of this stop are described in
|
2016-11-16 05:52:27 +00:00
|
|
|
detail in a separate section below.
|
2011-09-26 17:33:04 +00:00
|
|
|
.LP
|
|
|
|
.B PTRACE_GETSIGINFO
|
|
|
|
on
|
|
|
|
.B PTRACE_EVENT
|
|
|
|
stops returns
|
2012-03-23 18:49:32 +00:00
|
|
|
.B SIGTRAP
|
|
|
|
in
|
2011-09-26 17:33:04 +00:00
|
|
|
.IR si_signo ,
|
|
|
|
with
|
|
|
|
.I si_code
|
|
|
|
set to
|
|
|
|
.IR "(event<<8)\ |\ SIGTRAP" .
|
2011-09-24 06:29:34 +00:00
|
|
|
.SS Syscall-stops
|
2011-09-26 17:33:04 +00:00
|
|
|
If the tracee was restarted by
|
2016-11-16 05:51:59 +00:00
|
|
|
.BR PTRACE_SYSCALL
|
|
|
|
or
|
|
|
|
.BR PTRACE_SYSEMU ,
|
2011-09-26 17:33:04 +00:00
|
|
|
the tracee enters
|
2016-11-16 05:51:59 +00:00
|
|
|
syscall-enter-stop just prior to entering any system call (which
|
|
|
|
will not be executed if the restart was using
|
2016-11-17 07:21:01 +00:00
|
|
|
.BR PTRACE_SYSEMU ,
|
2016-11-16 05:51:59 +00:00
|
|
|
regardless of any change made to registers at this point or how the
|
|
|
|
tracee is restarted after this stop).
|
|
|
|
No matter which method caused the syscall-entry-stop,
|
|
|
|
if the tracer restarts the tracee with
|
2011-09-26 17:33:04 +00:00
|
|
|
.BR PTRACE_SYSCALL ,
|
|
|
|
the tracee enters syscall-exit-stop when the system call is finished,
|
|
|
|
or if it is interrupted by a signal.
|
|
|
|
(That is, signal-delivery-stop never happens between syscall-enter-stop
|
|
|
|
and syscall-exit-stop; it happens
|
|
|
|
.I after
|
2016-11-17 07:21:01 +00:00
|
|
|
syscall-exit-stop.).
|
|
|
|
If the tracee is continued using any other method (including
|
|
|
|
.BR PTRACE_SYSEMU ),
|
|
|
|
no syscall-exit-stop occurs.
|
|
|
|
Note that all mentions
|
2016-11-16 05:51:59 +00:00
|
|
|
.BR PTRACE_SYSEMU
|
|
|
|
apply equally to
|
|
|
|
.BR PTRACE_SYSEMU_SINGLESTEP.
|
2011-09-26 17:33:04 +00:00
|
|
|
.LP
|
2016-11-16 05:51:59 +00:00
|
|
|
However, even if the tracee is was continued using
|
|
|
|
.BR PTRACE_SYSCALL
|
|
|
|
, it is not guaranteed that the next stop will be a syscall-exit-stop.
|
2011-09-26 17:33:04 +00:00
|
|
|
Other possibilities are that the tracee may stop in a
|
|
|
|
.B PTRACE_EVENT
|
2016-11-16 05:52:27 +00:00
|
|
|
stop (including seccomp stops), exit (if it entered
|
2011-09-26 17:33:04 +00:00
|
|
|
.BR _exit (2)
|
|
|
|
or
|
|
|
|
.BR exit_group (2)),
|
|
|
|
be killed by
|
|
|
|
.BR SIGKILL ,
|
|
|
|
or die silently (if it is a thread group leader, the
|
|
|
|
.BR execve (2)
|
|
|
|
happened in another thread,
|
|
|
|
and that thread is not traced by the same tracer;
|
|
|
|
this situation is discussed later).
|
|
|
|
.LP
|
|
|
|
Syscall-enter-stop and syscall-exit-stop are observed by the tracer as
|
|
|
|
.BR waitpid (2)
|
|
|
|
returning with
|
|
|
|
.I WIFSTOPPED(status)
|
|
|
|
true, and
|
|
|
|
.I WSTOPSIG(status)
|
|
|
|
giving
|
|
|
|
.BR SIGTRAP .
|
|
|
|
If the
|
|
|
|
.B PTRACE_O_TRACESYSGOOD
|
|
|
|
option was set by the tracer, then
|
|
|
|
.I WSTOPSIG(status)
|
|
|
|
will give the value
|
|
|
|
.IR "(SIGTRAP\ |\ 0x80)" .
|
2011-09-24 06:29:34 +00:00
|
|
|
.LP
|
|
|
|
Syscall-stops can be distinguished from signal-delivery-stop with
|
2011-09-26 17:33:04 +00:00
|
|
|
.B SIGTRAP
|
|
|
|
by querying
|
|
|
|
.BR PTRACE_GETSIGINFO
|
|
|
|
for the following cases:
|
|
|
|
.TP
|
|
|
|
.IR si_code " <= 0"
|
|
|
|
.B SIGTRAP
|
eventfd.2, futex.2, mmap2.2, open.2, pciconfig_read.2, ptrace.2, reboot.2, request_key.2, sched_rr_get_interval.2, splice.2, stat.2, sync_file_range.2, syscalls.2, timer_create.2, vm86.2, pthread_attr_setscope.3, core.5, proc.5, aio.7, futex.7, netlink.7, time.7: Global fix: "userspace" ==> "user space" or "user-space"
Existing pages variously use "userspace or "user space".
But, "userspace" is not quite an English word.
So change "userspace" to "user space" or, when used
attributively, "user-space".
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2012-10-21 06:04:42 +00:00
|
|
|
was delivered as a result of a user-space action,
|
2011-10-01 05:39:39 +00:00
|
|
|
for example, a system call
|
2011-09-26 17:33:04 +00:00
|
|
|
.RB ( tgkill (2),
|
2011-10-01 05:39:39 +00:00
|
|
|
.BR kill (2),
|
2011-09-26 17:33:04 +00:00
|
|
|
.BR sigqueue (3),
|
2011-10-01 05:39:39 +00:00
|
|
|
etc.),
|
|
|
|
expiration of a POSIX timer,
|
|
|
|
change of state on a POSIX message queue,
|
|
|
|
or completion of an asynchronous I/O request.
|
2011-09-26 17:33:04 +00:00
|
|
|
.TP
|
|
|
|
.IR si_code " == SI_KERNEL (0x80)"
|
|
|
|
.B SIGTRAP
|
|
|
|
was sent by the kernel.
|
|
|
|
.TP
|
|
|
|
.IR si_code " == SIGTRAP or " si_code " == (SIGTRAP|0x80)"
|
|
|
|
This is a syscall-stop.
|
|
|
|
.LP
|
|
|
|
However, syscall-stops happen very often (twice per system call),
|
|
|
|
and performing
|
|
|
|
.B PTRACE_GETSIGINFO
|
|
|
|
for every syscall-stop may be somewhat expensive.
|
|
|
|
.LP
|
|
|
|
Some architectures allow the cases to be distinguished
|
|
|
|
by examining registers.
|
|
|
|
For example, on x86,
|
|
|
|
.I rax
|
|
|
|
==
|
|
|
|
.RB - ENOSYS
|
|
|
|
in syscall-enter-stop.
|
|
|
|
Since
|
|
|
|
.B SIGTRAP
|
|
|
|
(like any other signal) always happens
|
|
|
|
.I after
|
|
|
|
syscall-exit-stop,
|
|
|
|
and at this point
|
|
|
|
.I rax
|
|
|
|
almost never contains
|
|
|
|
.RB - ENOSYS ,
|
|
|
|
the
|
|
|
|
.B SIGTRAP
|
|
|
|
looks like "syscall-stop which is not syscall-enter-stop";
|
|
|
|
in other words, it looks like a
|
2011-09-25 05:30:51 +00:00
|
|
|
"stray syscall-exit-stop" and can be detected this way.
|
2011-09-26 17:33:04 +00:00
|
|
|
But such detection is fragile and is best avoided.
|
2011-09-24 06:29:34 +00:00
|
|
|
.LP
|
2011-09-26 17:33:04 +00:00
|
|
|
Using the
|
|
|
|
.B PTRACE_O_TRACESYSGOOD
|
2012-03-19 18:29:29 +00:00
|
|
|
option is the recommended method to distinguish syscall-stops
|
2012-03-05 17:16:37 +00:00
|
|
|
from other kinds of ptrace-stops,
|
2011-09-26 17:33:04 +00:00
|
|
|
since it is reliable and does not incur a performance penalty.
|
2011-09-24 06:29:34 +00:00
|
|
|
.LP
|
2011-09-26 17:33:04 +00:00
|
|
|
Syscall-enter-stop and syscall-exit-stop are
|
|
|
|
indistinguishable from each other by the tracer.
|
|
|
|
The tracer needs to keep track of the sequence of
|
2011-09-24 06:29:34 +00:00
|
|
|
ptrace-stops in order to not misinterpret syscall-enter-stop as
|
2011-09-25 05:30:51 +00:00
|
|
|
syscall-exit-stop or vice versa.
|
2016-11-17 07:21:01 +00:00
|
|
|
In general, a syscall-enter-stop is
|
2011-09-26 17:33:04 +00:00
|
|
|
always followed by syscall-exit-stop,
|
|
|
|
.B PTRACE_EVENT
|
2016-11-17 07:21:01 +00:00
|
|
|
stop, or the tracee's death;
|
2011-09-26 17:33:04 +00:00
|
|
|
no other kinds of ptrace-stop can occur in between.
|
2016-11-16 05:52:27 +00:00
|
|
|
However, note that seccomp stops (see below) can cause syscall-exit-stops,
|
2016-11-17 07:21:01 +00:00
|
|
|
without preceeding syscall-entry-stops.
|
|
|
|
If seccomp is in use, care needs
|
|
|
|
to be taken not to misinterpret such stops as syscall-entry-stops.
|
2011-09-24 06:29:34 +00:00
|
|
|
.LP
|
2011-09-26 17:33:04 +00:00
|
|
|
If after syscall-enter-stop,
|
|
|
|
the tracer uses a restarting command other than
|
|
|
|
.BR PTRACE_SYSCALL ,
|
|
|
|
syscall-exit-stop is not generated.
|
2011-09-24 06:29:34 +00:00
|
|
|
.LP
|
2011-09-26 17:33:04 +00:00
|
|
|
.B PTRACE_GETSIGINFO
|
|
|
|
on syscall-stops returns
|
|
|
|
.B SIGTRAP
|
|
|
|
in
|
|
|
|
.IR si_signo ,
|
|
|
|
with
|
|
|
|
.I si_code
|
|
|
|
set to
|
|
|
|
.B SIGTRAP
|
|
|
|
or
|
|
|
|
.IR (SIGTRAP|0x80) .
|
2016-11-17 07:21:01 +00:00
|
|
|
.\"
|
|
|
|
.SS PTRACE_EVENT_SECCOMP stops (Linux 3.5 to 4.7)
|
2016-11-16 05:52:27 +00:00
|
|
|
The behavior of
|
|
|
|
.BR PTRACE_EVENT_SECCOMP
|
|
|
|
stops and their interaction with other kinds
|
2016-11-17 07:21:01 +00:00
|
|
|
of ptrace stops has changed between kernel versions.
|
|
|
|
This documents the behavior
|
|
|
|
from their introduction until Linux 4.7 (inclusive).
|
|
|
|
The behavior in later kernel versions is documented in the next section.
|
2016-11-16 05:52:27 +00:00
|
|
|
|
|
|
|
A
|
|
|
|
.BR PTRACE_EVENT_SECCOMP
|
|
|
|
stop occurs whenever a
|
|
|
|
.BR SECCOMP_RET_TRACE
|
2016-11-17 07:21:01 +00:00
|
|
|
rule is triggered.
|
|
|
|
This is independent of which methods was used to restart the system call.
|
|
|
|
Notably, seccomp still runs even if the tracee was restarted using
|
2016-11-16 05:52:27 +00:00
|
|
|
.BR PTRACE_SYSEMU
|
|
|
|
and this system call is unconditionally skipped.
|
|
|
|
|
|
|
|
Restarts from this stop will behave as if the stop had occurred right
|
2016-11-17 07:21:01 +00:00
|
|
|
before the system call in question.
|
|
|
|
In particular, both
|
2016-11-16 05:52:27 +00:00
|
|
|
.BR PTRACE_SYSCALL
|
|
|
|
and
|
|
|
|
.BR PTRACE_SYSEMU
|
2016-11-17 07:21:01 +00:00
|
|
|
will normally cause a subsequent syscall-entry-stop.
|
|
|
|
However, if after the
|
2016-11-16 05:52:27 +00:00
|
|
|
.BR PTRACE_EVENT_SECCOMP
|
2016-11-17 07:21:01 +00:00
|
|
|
the system call number is negative,
|
|
|
|
both the syscall-entry-stop and the system call itself will be skipped.
|
|
|
|
This means that if the system call number is negative after a
|
2016-11-16 05:52:27 +00:00
|
|
|
.BR PTRACE_EVENT_SECCOMP
|
|
|
|
and the tracee is restarted using
|
|
|
|
.BR PTRACE_SYSCALL,
|
|
|
|
the next observed stop will be a syscall-exit-stop,
|
2016-11-17 07:21:01 +00:00
|
|
|
rather than the syscall-entry-stop that might have been expected.
|
|
|
|
.\"
|
|
|
|
.SS PTRACE_EVENT_SECCOMP stops (since Linux 4.8)
|
|
|
|
Starting with Linux 4.8,
|
|
|
|
.\" commit 93e35efb8de45393cf61ed07f7b407629bf698ea
|
|
|
|
the
|
2016-11-16 05:52:27 +00:00
|
|
|
.BR PTRACE_EVENT_SECCOMP
|
2016-11-17 07:21:01 +00:00
|
|
|
stop was reordered to occur between syscall-entry-stop and
|
|
|
|
syscall-exit-stop.
|
|
|
|
Note that seccomp no longer runs (and no
|
|
|
|
.B PTRACE_EVENT_SECCOMP
|
|
|
|
will be reported) if the system call is skipped due to
|
|
|
|
.BR PTRACE_SYSEMU .
|
2016-11-16 05:52:27 +00:00
|
|
|
|
2016-11-17 07:21:01 +00:00
|
|
|
Functionally, a
|
|
|
|
.B PTRACE_EVENT_SECCOMP
|
|
|
|
stop functions comparably
|
|
|
|
to a syscall-entry-stop (i.e., continuations using
|
2016-11-16 05:52:27 +00:00
|
|
|
.BR PTRACE_SYSCALL
|
2016-11-17 07:21:01 +00:00
|
|
|
will cause syscall-exit-stops,
|
|
|
|
the system call number may be changed and any other modified registers
|
|
|
|
are visible to the to-be-executed system call as well).
|
|
|
|
Note that there may be,
|
|
|
|
but need not have been a preceeding syscall-entry-stop.
|
2016-11-16 05:52:27 +00:00
|
|
|
|
|
|
|
After a
|
|
|
|
.BR PTRACE_EVENT_SECCOMP
|
2016-11-17 07:21:01 +00:00
|
|
|
stop, seccomp will be rerun, with a
|
2016-11-16 05:52:27 +00:00
|
|
|
.BR SECCOMP_RET_TRACE
|
|
|
|
rule now functioning the same as a
|
2016-11-17 07:21:01 +00:00
|
|
|
.BR SECCOMP_RET_ALLOW .
|
|
|
|
Specifically, this means that if registers are not modified during the
|
2016-11-16 05:52:27 +00:00
|
|
|
.BR PTRACE_EVENT_SECCOMP
|
|
|
|
stop, the system call will then be allowed.
|
2016-11-17 07:21:01 +00:00
|
|
|
.\"
|
2016-11-16 05:51:59 +00:00
|
|
|
.SS PTRACE_SINGLESTEP stops
|
2012-03-05 17:16:37 +00:00
|
|
|
[Details of these kinds of stops are yet to be documented.]
|
2011-09-26 17:33:04 +00:00
|
|
|
.\"
|
adjtimex.2, bind.2, cacheflush.2, clone.2, fallocate.2, fanotify_init.2, fanotify_mark.2, flock.2, futex.2, getdents.2, getpriority.2, getrlimit.2, gettid.2, gettimeofday.2, ioprio_set.2, kexec_load.2, migrate_pages.2, modify_ldt.2, mount.2, move_pages.2, mprotect.2, msgop.2, nfsservctl.2, perf_event_open.2, pread.2, ptrace.2, recvmmsg.2, rename.2, restart_syscall.2, sched_setattr.2, send.2, shmop.2, shutdown.2, sigaction.2, signalfd.2, syscalls.2, timer_create.2, timerfd_create.2, tkill.2, vmsplice.2, wait.2, aio_init.3, confstr.3, exit.3, fmemopen.3, fopen.3, getaddrinfo.3, getauxval.3, getspnam.3, isalpha.3, isatty.3, mallinfo.3, malloc.3, mallopt.3, psignal.3, pthread_attr_setinheritsched.3, qecvt.3, queue.3, rtnetlink.3, strerror.3, strftime.3, toupper.3, towlower.3, towupper.3, initrd.4, locale.5, proc.5, bootparam.7, capabilities.7, ddp.7, fanotify.7, icmp.7, inotify.7, ip.7, ipv6.7, netdevice.7, netlink.7, path_resolution.7, rtld-audit.7, rtnetlink.7, sched.7, signal.7, socket.7, svipc.7, tcp.7, unix.7, ld.so.8: srcfix: Update FIXMEs
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2014-08-21 21:47:44 +00:00
|
|
|
.\" FIXME .
|
2016-11-16 05:51:59 +00:00
|
|
|
.\" document stops occurring with PTRACE_SINGLESTEP
|
2016-11-17 07:21:01 +00:00
|
|
|
.\"
|
2011-09-24 06:29:34 +00:00
|
|
|
.SS Informational and restarting ptrace commands
|
2011-09-26 17:33:04 +00:00
|
|
|
Most ptrace commands (all except
|
|
|
|
.BR PTRACE_ATTACH ,
|
2013-02-16 08:50:27 +00:00
|
|
|
.BR PTRACE_SEIZE ,
|
2011-09-26 17:33:04 +00:00
|
|
|
.BR PTRACE_TRACEME ,
|
2013-02-16 08:50:27 +00:00
|
|
|
.BR PTRACE_INTERRUPT ,
|
2011-09-26 17:33:04 +00:00
|
|
|
and
|
|
|
|
.BR PTRACE_KILL )
|
|
|
|
require the tracee to be in a ptrace-stop, otherwise they fail with
|
|
|
|
.BR ESRCH .
|
2011-09-24 06:29:34 +00:00
|
|
|
.LP
|
2011-09-26 17:33:04 +00:00
|
|
|
When the tracee is in ptrace-stop,
|
|
|
|
the tracer can read and write data to
|
|
|
|
the tracee using informational commands.
|
|
|
|
These commands leave the tracee in ptrace-stopped state:
|
2011-09-24 06:29:34 +00:00
|
|
|
.LP
|
|
|
|
.nf
|
2011-09-26 17:33:04 +00:00
|
|
|
ptrace(PTRACE_PEEKTEXT/PEEKDATA/PEEKUSER, pid, addr, 0);
|
|
|
|
ptrace(PTRACE_POKETEXT/POKEDATA/POKEUSER, pid, addr, long_val);
|
|
|
|
ptrace(PTRACE_GETREGS/GETFPREGS, pid, 0, &struct);
|
|
|
|
ptrace(PTRACE_SETREGS/SETFPREGS, pid, 0, &struct);
|
2013-02-16 08:50:27 +00:00
|
|
|
ptrace(PTRACE_GETREGSET, pid, NT_foo, &iov);
|
|
|
|
ptrace(PTRACE_SETREGSET, pid, NT_foo, &iov);
|
2011-09-26 17:33:04 +00:00
|
|
|
ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo);
|
|
|
|
ptrace(PTRACE_SETSIGINFO, pid, 0, &siginfo);
|
|
|
|
ptrace(PTRACE_GETEVENTMSG, pid, 0, &long_var);
|
|
|
|
ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
|
2011-09-24 06:29:34 +00:00
|
|
|
.fi
|
|
|
|
.LP
|
2011-09-25 05:30:51 +00:00
|
|
|
Note that some errors are not reported.
|
2011-09-26 17:33:04 +00:00
|
|
|
For example, setting signal information
|
|
|
|
.RI ( siginfo )
|
2011-09-24 06:29:34 +00:00
|
|
|
may have no effect in some ptrace-stops, yet the call may succeed
|
2011-09-26 17:33:04 +00:00
|
|
|
(return 0 and not set
|
|
|
|
.IR errno );
|
|
|
|
querying
|
|
|
|
.B PTRACE_GETEVENTMSG
|
|
|
|
may succeed and return some random value if current ptrace-stop
|
|
|
|
is not documented as returning a meaningful event message.
|
|
|
|
.LP
|
|
|
|
The call
|
|
|
|
|
|
|
|
ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
|
2012-03-05 19:54:38 +00:00
|
|
|
|
2011-09-26 17:33:04 +00:00
|
|
|
affects one tracee.
|
|
|
|
The tracee's current flags are replaced.
|
|
|
|
Flags are inherited by new tracees created and "auto-attached" via active
|
|
|
|
.BR PTRACE_O_TRACEFORK ,
|
|
|
|
.BR PTRACE_O_TRACEVFORK ,
|
|
|
|
or
|
|
|
|
.BR PTRACE_O_TRACECLONE
|
|
|
|
options.
|
|
|
|
.LP
|
|
|
|
Another group of commands makes the ptrace-stopped tracee run.
|
|
|
|
They have the form:
|
|
|
|
.LP
|
2011-10-01 05:39:39 +00:00
|
|
|
ptrace(cmd, pid, 0, sig);
|
2011-09-26 17:33:04 +00:00
|
|
|
.LP
|
|
|
|
where
|
|
|
|
.I cmd
|
|
|
|
is
|
|
|
|
.BR PTRACE_CONT ,
|
2013-02-16 08:50:27 +00:00
|
|
|
.BR PTRACE_LISTEN ,
|
2011-09-26 17:33:04 +00:00
|
|
|
.BR PTRACE_DETACH ,
|
|
|
|
.BR PTRACE_SYSCALL ,
|
|
|
|
.BR PTRACE_SINGLESTEP ,
|
|
|
|
.BR PTRACE_SYSEMU ,
|
|
|
|
or
|
2012-03-23 23:12:33 +00:00
|
|
|
.BR PTRACE_SYSEMU_SINGLESTEP .
|
2011-09-26 17:33:04 +00:00
|
|
|
If the tracee is in signal-delivery-stop,
|
|
|
|
.I sig
|
|
|
|
is the signal to be injected (if it is nonzero).
|
|
|
|
Otherwise,
|
|
|
|
.I sig
|
|
|
|
may be ignored.
|
2011-10-01 05:39:39 +00:00
|
|
|
(When restarting a tracee from a ptrace-stop other than signal-delivery-stop,
|
|
|
|
recommended practice is to always pass 0 in
|
2012-03-23 23:12:33 +00:00
|
|
|
.IR sig .)
|
2011-09-24 06:29:34 +00:00
|
|
|
.SS Attaching and detaching
|
2011-09-26 17:33:04 +00:00
|
|
|
A thread can be attached to the tracer using the call
|
|
|
|
|
|
|
|
ptrace(PTRACE_ATTACH, pid, 0, 0);
|
|
|
|
|
2013-02-16 08:50:27 +00:00
|
|
|
or
|
|
|
|
|
|
|
|
ptrace(PTRACE_SEIZE, pid, 0, PTRACE_O_flags);
|
|
|
|
|
|
|
|
.B PTRACE_ATTACH
|
|
|
|
sends
|
2011-09-26 17:33:04 +00:00
|
|
|
.B SIGSTOP
|
|
|
|
to this thread.
|
|
|
|
If the tracer wants this
|
|
|
|
.B SIGSTOP
|
|
|
|
to have no effect, it needs to suppress it.
|
|
|
|
Note that if other signals are concurrently sent to
|
|
|
|
this thread during attach,
|
|
|
|
the tracer may see the tracee enter signal-delivery-stop
|
|
|
|
with other signal(s) first!
|
|
|
|
The usual practice is to reinject these signals until
|
|
|
|
.B SIGSTOP
|
|
|
|
is seen, then suppress
|
|
|
|
.B SIGSTOP
|
|
|
|
injection.
|
|
|
|
The design bug here is that a ptrace attach and a concurrently delivered
|
|
|
|
.B SIGSTOP
|
|
|
|
may race and the concurrent
|
|
|
|
.B SIGSTOP
|
|
|
|
may be lost.
|
|
|
|
.\"
|
2016-10-29 10:23:48 +00:00
|
|
|
.\" FIXME Describe how to attach to a thread which is already group-stopped.
|
2011-09-26 17:33:04 +00:00
|
|
|
.LP
|
|
|
|
Since attaching sends
|
|
|
|
.B SIGSTOP
|
|
|
|
and the tracer usually suppresses it, this may cause a stray
|
2012-03-23 23:12:33 +00:00
|
|
|
.B EINTR
|
2011-09-26 17:33:04 +00:00
|
|
|
return from the currently executing system call in the tracee,
|
2012-03-23 23:12:33 +00:00
|
|
|
as described in the "Signal injection and suppression" section.
|
2011-09-26 17:33:04 +00:00
|
|
|
.LP
|
2013-02-16 09:22:49 +00:00
|
|
|
Since Linux 3.4,
|
2013-02-16 08:50:27 +00:00
|
|
|
.B PTRACE_SEIZE
|
|
|
|
can be used instead of
|
|
|
|
.BR PTRACE_ATTACH .
|
|
|
|
.B PTRACE_SEIZE
|
2013-03-18 20:17:29 +00:00
|
|
|
does not stop the attached process.
|
|
|
|
If you need to stop
|
2013-02-16 08:50:27 +00:00
|
|
|
it after attach (or at any other time) without sending it any signals,
|
|
|
|
use
|
|
|
|
.B PTRACE_INTERRUPT
|
|
|
|
command.
|
|
|
|
.LP
|
2011-09-26 17:33:04 +00:00
|
|
|
The request
|
|
|
|
|
|
|
|
ptrace(PTRACE_TRACEME, 0, 0, 0);
|
|
|
|
|
|
|
|
turns the calling thread into a tracee.
|
|
|
|
The thread continues to run (doesn't enter ptrace-stop).
|
|
|
|
A common practice is to follow the
|
|
|
|
.B PTRACE_TRACEME
|
|
|
|
with
|
|
|
|
|
|
|
|
raise(SIGSTOP);
|
|
|
|
|
|
|
|
and allow the parent (which is our tracer now) to observe our
|
2011-09-24 06:29:34 +00:00
|
|
|
signal-delivery-stop.
|
|
|
|
.LP
|
2012-03-05 19:54:38 +00:00
|
|
|
If the
|
2011-09-26 17:33:04 +00:00
|
|
|
.BR PTRACE_O_TRACEFORK ,
|
|
|
|
.BR PTRACE_O_TRACEVFORK ,
|
|
|
|
or
|
|
|
|
.BR PTRACE_O_TRACECLONE
|
|
|
|
options are in effect, then children created by, respectively,
|
|
|
|
.BR vfork (2)
|
|
|
|
or
|
|
|
|
.BR clone (2)
|
|
|
|
with the
|
|
|
|
.B CLONE_VFORK
|
|
|
|
flag,
|
|
|
|
.BR fork (2)
|
|
|
|
or
|
|
|
|
.BR clone (2)
|
|
|
|
with the exit signal set to
|
|
|
|
.BR SIGCHLD ,
|
|
|
|
and other kinds of
|
|
|
|
.BR clone (2),
|
|
|
|
are automatically attached to the same tracer which traced their parent.
|
|
|
|
.B SIGSTOP
|
|
|
|
is delivered to the children, causing them to enter
|
|
|
|
signal-delivery-stop after they exit the system call which created them.
|
|
|
|
.LP
|
|
|
|
Detaching of the tracee is performed by:
|
|
|
|
|
|
|
|
ptrace(PTRACE_DETACH, pid, 0, sig);
|
|
|
|
|
|
|
|
.B PTRACE_DETACH
|
|
|
|
is a restarting operation;
|
|
|
|
therefore it requires the tracee to be in ptrace-stop.
|
|
|
|
If the tracee is in signal-delivery-stop, a signal can be injected.
|
|
|
|
Otherwise, the
|
|
|
|
.I sig
|
|
|
|
parameter may be silently ignored.
|
|
|
|
.LP
|
|
|
|
If the tracee is running when the tracer wants to detach it,
|
|
|
|
the usual solution is to send
|
|
|
|
.B SIGSTOP
|
|
|
|
(using
|
|
|
|
.BR tgkill (2),
|
|
|
|
to make sure it goes to the correct thread),
|
|
|
|
wait for the tracee to stop in signal-delivery-stop for
|
|
|
|
.B SIGSTOP
|
|
|
|
and then detach it (suppressing
|
|
|
|
.B SIGSTOP
|
|
|
|
injection).
|
|
|
|
A design bug is that this can race with concurrent
|
|
|
|
.BR SIGSTOP s.
|
|
|
|
Another complication is that the tracee may enter other ptrace-stops
|
|
|
|
and needs to be restarted and waited for again, until
|
|
|
|
.B SIGSTOP
|
|
|
|
is seen.
|
|
|
|
Yet another complication is to be sure that
|
|
|
|
the tracee is not already ptrace-stopped,
|
|
|
|
because no signal delivery happens while it is\(emnot even
|
|
|
|
.BR SIGSTOP .
|
2016-10-29 10:23:48 +00:00
|
|
|
.\" FIXME Describe how to detach from a group-stopped tracee so that it
|
|
|
|
.\" doesn't run, but continues to wait for SIGCONT.
|
2011-09-26 17:33:04 +00:00
|
|
|
.LP
|
|
|
|
If the tracer dies, all tracees are automatically detached and restarted,
|
2011-09-25 05:30:51 +00:00
|
|
|
unless they were in group-stop.
|
2012-03-05 17:16:37 +00:00
|
|
|
Handling of restart from group-stop is currently buggy,
|
|
|
|
but the "as planned" behavior is to leave tracee stopped and waiting for
|
2011-09-26 17:33:04 +00:00
|
|
|
.BR SIGCONT .
|
|
|
|
If the tracee is restarted from signal-delivery-stop,
|
|
|
|
the pending signal is injected.
|
|
|
|
.SS execve(2) under ptrace
|
2012-08-02 11:58:18 +00:00
|
|
|
.\" clone(2) CLONE_THREAD says:
|
2011-09-26 17:33:04 +00:00
|
|
|
.\" If any of the threads in a thread group performs an execve(2),
|
|
|
|
.\" then all threads other than the thread group leader are terminated,
|
2012-03-05 19:54:38 +00:00
|
|
|
.\" and the new program is executed in the thread group leader.
|
2011-09-26 17:33:04 +00:00
|
|
|
.\"
|
2011-10-01 05:39:39 +00:00
|
|
|
When one thread in a multithreaded process calls
|
2011-09-26 17:33:04 +00:00
|
|
|
.BR execve (2),
|
|
|
|
the kernel destroys all other threads in the process,
|
|
|
|
.\" In kernel 3.1 sources, see fs/exec.c::de_thread()
|
|
|
|
and resets the thread ID of the execing thread to the
|
|
|
|
thread group ID (process ID).
|
|
|
|
(Or, to put things another way, when a multithreaded process does an
|
|
|
|
.BR execve (2),
|
2011-10-01 05:39:39 +00:00
|
|
|
at completion of the call, it appears as though the
|
2011-09-26 17:33:04 +00:00
|
|
|
.BR execve (2)
|
|
|
|
occurred in the thread group leader, regardless of which thread did the
|
|
|
|
.BR execve (2).)
|
|
|
|
This resetting of the thread ID looks very confusing to tracers:
|
|
|
|
.IP * 3
|
|
|
|
All other threads stop in
|
2011-10-01 05:39:39 +00:00
|
|
|
.B PTRACE_EVENT_EXIT
|
2012-03-05 17:16:37 +00:00
|
|
|
stop, if the
|
2011-10-01 05:39:39 +00:00
|
|
|
.BR PTRACE_O_TRACEEXIT
|
|
|
|
option was turned on.
|
2011-09-26 17:33:04 +00:00
|
|
|
Then all other threads except the thread group leader report
|
|
|
|
death as if they exited via
|
|
|
|
.BR _exit (2)
|
|
|
|
with exit code 0.
|
2012-03-05 17:16:37 +00:00
|
|
|
.IP *
|
2011-09-26 17:33:04 +00:00
|
|
|
The execing tracee changes its thread ID while it is in the
|
|
|
|
.BR execve (2).
|
|
|
|
(Remember, under ptrace, the "pid" returned from
|
|
|
|
.BR waitpid (2),
|
|
|
|
or fed into ptrace calls, is the tracee's thread ID.)
|
|
|
|
That is, the tracee's thread ID is reset to be the same as its process ID,
|
|
|
|
which is the same as the thread group leader's thread ID.
|
|
|
|
.IP *
|
2012-03-19 18:18:20 +00:00
|
|
|
Then a
|
|
|
|
.B PTRACE_EVENT_EXEC
|
|
|
|
stop happens, if the
|
|
|
|
.BR PTRACE_O_TRACEEXEC
|
|
|
|
option was turned on.
|
|
|
|
.IP *
|
|
|
|
If the thread group leader has reported its
|
|
|
|
.B PTRACE_EVENT_EXIT
|
|
|
|
stop by this time,
|
2011-09-26 17:33:04 +00:00
|
|
|
it appears to the tracer that
|
|
|
|
the dead thread leader "reappears from nowhere".
|
2012-03-19 18:29:29 +00:00
|
|
|
(Note: the thread group leader does not report death via
|
2012-03-19 18:18:20 +00:00
|
|
|
.I WIFEXITED(status)
|
|
|
|
until there is at least one other live thread.
|
2012-03-19 18:29:29 +00:00
|
|
|
This eliminates the possibility that the tracer will see
|
2012-03-19 18:18:20 +00:00
|
|
|
it dying and then reappearing.)
|
2011-09-26 17:33:04 +00:00
|
|
|
If the thread group leader was still alive,
|
|
|
|
for the tracer this may look as if thread group leader
|
|
|
|
returns from a different system call than it entered,
|
|
|
|
or even "returned from a system call even though
|
|
|
|
it was not in any system call".
|
|
|
|
If the thread group leader was not traced
|
|
|
|
(or was traced by a different tracer), then during
|
|
|
|
.BR execve (2)
|
|
|
|
it will appear as if it has become a tracee of
|
|
|
|
the tracer of the execing tracee.
|
2011-09-24 06:29:34 +00:00
|
|
|
.LP
|
2011-09-26 17:33:04 +00:00
|
|
|
All of the above effects are the artifacts of
|
|
|
|
the thread ID change in the tracee.
|
2011-09-24 06:29:34 +00:00
|
|
|
.LP
|
2011-09-26 17:33:04 +00:00
|
|
|
The
|
|
|
|
.B PTRACE_O_TRACEEXEC
|
|
|
|
option is the recommended tool for dealing with this situation.
|
2012-03-05 17:16:37 +00:00
|
|
|
First, it enables
|
2012-03-23 23:12:33 +00:00
|
|
|
.BR PTRACE_EVENT_EXEC
|
|
|
|
stop,
|
2012-03-05 17:16:37 +00:00
|
|
|
which occurs before
|
2012-03-23 23:12:33 +00:00
|
|
|
.BR execve (2)
|
2012-03-05 17:16:37 +00:00
|
|
|
returns.
|
|
|
|
In this stop, the tracer can use
|
|
|
|
.B PTRACE_GETEVENTMSG
|
|
|
|
to retrieve the tracee's former thread ID.
|
2015-05-04 11:08:24 +00:00
|
|
|
(This feature was introduced in Linux 3.0.)
|
2012-03-05 17:16:37 +00:00
|
|
|
Second, the
|
|
|
|
.B PTRACE_O_TRACEEXEC
|
|
|
|
option disables legacy
|
|
|
|
.B SIGTRAP
|
|
|
|
generation on
|
|
|
|
.BR execve (2).
|
2011-09-26 17:33:04 +00:00
|
|
|
.LP
|
|
|
|
When the tracer receives
|
|
|
|
.B PTRACE_EVENT_EXEC
|
|
|
|
stop notification,
|
|
|
|
it is guaranteed that except this tracee and the thread group leader,
|
|
|
|
no other threads from the process are alive.
|
|
|
|
.LP
|
|
|
|
On receiving the
|
|
|
|
.B PTRACE_EVENT_EXEC
|
|
|
|
stop notification,
|
|
|
|
the tracer should clean up all its internal
|
|
|
|
data structures describing the threads of this process,
|
|
|
|
and retain only one data structure\(emone which
|
|
|
|
describes the single still running tracee, with
|
|
|
|
|
2012-03-19 18:18:20 +00:00
|
|
|
thread ID == thread group ID == process ID.
|
2011-09-26 17:33:04 +00:00
|
|
|
.LP
|
|
|
|
Example: two threads call
|
|
|
|
.BR execve (2)
|
|
|
|
at the same time:
|
2011-09-24 06:29:34 +00:00
|
|
|
.LP
|
|
|
|
.nf
|
2012-03-23 23:12:33 +00:00
|
|
|
*** we get syscall-enter-stop in thread 1: **
|
2011-09-24 06:29:34 +00:00
|
|
|
PID1 execve("/bin/foo", "foo" <unfinished ...>
|
|
|
|
*** we issue PTRACE_SYSCALL for thread 1 **
|
2012-03-23 23:12:33 +00:00
|
|
|
*** we get syscall-enter-stop in thread 2: **
|
2011-09-24 06:29:34 +00:00
|
|
|
PID2 execve("/bin/bar", "bar" <unfinished ...>
|
|
|
|
*** we issue PTRACE_SYSCALL for thread 2 **
|
|
|
|
*** we get PTRACE_EVENT_EXEC for PID0, we issue PTRACE_SYSCALL **
|
|
|
|
*** we get syscall-exit-stop for PID0: **
|
|
|
|
PID0 <... execve resumed> ) = 0
|
|
|
|
.fi
|
|
|
|
.LP
|
2011-09-26 17:33:04 +00:00
|
|
|
If the
|
|
|
|
.B PTRACE_O_TRACEEXEC
|
|
|
|
option is
|
|
|
|
.I not
|
2015-02-11 13:20:35 +00:00
|
|
|
in effect for the execing tracee,
|
2015-02-11 13:48:03 +00:00
|
|
|
and if the tracee was
|
2015-02-11 13:20:35 +00:00
|
|
|
.BR PTRACE_ATTACH ed
|
|
|
|
rather that
|
|
|
|
.BR PTRACE_SEIZE d,
|
|
|
|
the kernel delivers an extra
|
2011-09-26 17:33:04 +00:00
|
|
|
.B SIGTRAP
|
|
|
|
to the tracee after
|
|
|
|
.BR execve (2)
|
2011-09-25 05:30:51 +00:00
|
|
|
returns.
|
|
|
|
This is an ordinary signal (similar to one which can be
|
2011-09-26 17:33:04 +00:00
|
|
|
generated by
|
|
|
|
.IR "kill -TRAP" ),
|
|
|
|
not a special kind of ptrace-stop.
|
|
|
|
Employing
|
|
|
|
.B PTRACE_GETSIGINFO
|
|
|
|
for this signal returns
|
|
|
|
.I si_code
|
|
|
|
set to 0
|
|
|
|
.RI ( SI_USER ).
|
|
|
|
This signal may be blocked by signal mask,
|
|
|
|
and thus may be delivered (much) later.
|
|
|
|
.LP
|
|
|
|
Usually, the tracer (for example,
|
|
|
|
.BR strace (1))
|
|
|
|
would not want to show this extra post-execve
|
|
|
|
.B SIGTRAP
|
|
|
|
signal to the user, and would suppress its delivery to the tracee (if
|
|
|
|
.B SIGTRAP
|
|
|
|
is set to
|
|
|
|
.BR SIG_DFL ,
|
|
|
|
it is a killing signal).
|
2012-03-05 19:54:38 +00:00
|
|
|
However, determining
|
2011-09-26 17:33:04 +00:00
|
|
|
.I which
|
|
|
|
.B SIGTRAP
|
|
|
|
to suppress is not easy.
|
|
|
|
Setting the
|
|
|
|
.B PTRACE_O_TRACEEXEC
|
2015-02-11 13:20:35 +00:00
|
|
|
option or using
|
|
|
|
.B PTRACE_SEIZE
|
|
|
|
and thus suppressing this extra
|
2011-09-26 17:33:04 +00:00
|
|
|
.B SIGTRAP
|
|
|
|
is the recommended approach.
|
2011-09-24 06:29:34 +00:00
|
|
|
.SS Real parent
|
2011-09-26 17:33:04 +00:00
|
|
|
The ptrace API (ab)uses the standard UNIX parent/child signaling over
|
|
|
|
.BR waitpid (2).
|
|
|
|
This used to cause the real parent of the process to stop receiving
|
|
|
|
several kinds of
|
|
|
|
.BR waitpid (2)
|
|
|
|
notifications when the child process is traced by some other process.
|
|
|
|
.LP
|
|
|
|
Many of these bugs have been fixed, but as of Linux 2.6.38 several still
|
|
|
|
exist; see BUGS below.
|
|
|
|
.LP
|
|
|
|
As of Linux 2.6.38, the following is believed to work correctly:
|
|
|
|
.IP * 3
|
2012-02-26 18:36:30 +00:00
|
|
|
exit/death by signal is reported first to the tracer, then,
|
|
|
|
when the tracer consumes the
|
2011-09-26 17:33:04 +00:00
|
|
|
.BR waitpid (2)
|
|
|
|
result, to the real parent (to the real parent only when the
|
|
|
|
whole multithreaded process exits).
|
|
|
|
If the tracer and the real parent are the same process,
|
|
|
|
the report is sent only once.
|
getent.1, intro.1, time.1, _exit.2, _syscall.2, accept.2, access.2, acct.2, adjtimex.2, alarm.2, alloc_hugepages.2, arch_prctl.2, bdflush.2, bind.2, brk.2, cacheflush.2, capget.2, chdir.2, chmod.2, chown.2, chroot.2, clock_getres.2, clock_nanosleep.2, clone.2, close.2, connect.2, create_module.2, delete_module.2, dup.2, epoll_create.2, epoll_ctl.2, epoll_wait.2, eventfd.2, execve.2, exit_group.2, faccessat.2, fchmodat.2, fchownat.2, fcntl.2, flock.2, fork.2, fstatat.2, fsync.2, futex.2, futimesat.2, get_kernel_syms.2, get_robust_list.2, get_thread_area.2, getcpu.2, getdents.2, getdomainname.2, getgid.2, getgroups.2, gethostname.2, getitimer.2, getpagesize.2, getpeername.2, getpid.2, getpriority.2, getresuid.2, getrlimit.2, getrusage.2, getsid.2, getsockname.2, getsockopt.2, gettid.2, gettimeofday.2, getuid.2, getunwind.2, getxattr.2, idle.2, init_module.2, inotify_add_watch.2, inotify_init.2, inotify_rm_watch.2, intro.2, io_cancel.2, io_destroy.2, io_getevents.2, io_setup.2, io_submit.2, ioctl.2, ioctl_list.2, ioperm.2, iopl.2, ioprio_set.2, ipc.2, kcmp.2, kill.2, killpg.2, link.2, linkat.2, listen.2, listxattr.2, llseek.2, lookup_dcookie.2, lseek.2, madvise.2, migrate_pages.2, mincore.2, mkdir.2, mkdirat.2, mknod.2, mknodat.2, mlock.2, mmap.2, mmap2.2, modify_ldt.2, mount.2, move_pages.2, mprotect.2, mq_getsetattr.2, mremap.2, msgctl.2, msgget.2, msgop.2, msync.2, nanosleep.2, nfsservctl.2, nice.2, open.2, openat.2, outb.2, pause.2, pciconfig_read.2, perf_event_open.2, perfmonctl.2, personality.2, pipe.2, pivot_root.2, poll.2, posix_fadvise.2, prctl.2, pread.2, process_vm_readv.2, ptrace.2, query_module.2, quotactl.2, read.2, readahead.2, readdir.2, readlink.2, readlinkat.2, readv.2, reboot.2, recv.2, remap_file_pages.2, removexattr.2, rename.2, renameat.2, rmdir.2, rt_sigqueueinfo.2, sched_get_priority_max.2, sched_rr_get_interval.2, sched_setaffinity.2, sched_setparam.2, sched_setscheduler.2, sched_yield.2, select.2, semctl.2, semget.2, semop.2, send.2, sendfile.2, set_thread_area.2, set_tid_address.2, seteuid.2, setfsgid.2, setfsuid.2, setgid.2, setpgid.2, setresuid.2, setreuid.2, setsid.2, setuid.2, setup.2, setxattr.2, shmctl.2, shmget.2, shmop.2, shutdown.2, sigaction.2, sigaltstack.2, signal.2, signalfd.2, sigpending.2, sigprocmask.2, sigreturn.2, sigsuspend.2, sigwaitinfo.2, socket.2, socketcall.2, socketpair.2, splice.2, stat.2, statfs.2, stime.2, swapon.2, symlink.2, symlinkat.2, sync.2, sync_file_range.2, sysctl.2, sysfs.2, sysinfo.2, syslog.2, tee.2, time.2, timerfd_create.2, times.2, tkill.2, truncate.2, umask.2, umount.2, uname.2, unimplemented.2, unlink.2, unlinkat.2, uselib.2, ustat.2, utime.2, utimensat.2, vfork.2, vhangup.2, vm86.2, vmsplice.2, wait.2, wait4.2, write.2, CPU_SET.3, INFINITY.3, MB_CUR_MAX.3, MB_LEN_MAX.3, __setfpucw.3, a64l.3, abort.3, abs.3, acos.3, acosh.3, addseverity.3, adjtime.3, aio_cancel.3, aio_error.3, aio_fsync.3, aio_read.3, aio_return.3, aio_suspend.3, aio_write.3, alloca.3, argz_add.3, asin.3, asinh.3, asprintf.3, assert.3, assert_perror.3, atan.3, atan2.3, atanh.3, atexit.3, atof.3, atoi.3, backtrace.3, basename.3, bcmp.3, bcopy.3, bindresvport.3, bsd_signal.3, bsearch.3, bstring.3, btowc.3, btree.3, byteorder.3, bzero.3, cabs.3, cacos.3, cacosh.3, canonicalize_file_name.3, carg.3, casin.3, casinh.3, catan.3, catanh.3, catgets.3, catopen.3, cbrt.3, ccos.3, ccosh.3, ceil.3, cerf.3, cexp.3, cexp2.3, cfree.3, cimag.3, clearenv.3, clock.3, clock_getcpuclockid.3, clog.3, clog10.3, clog2.3, closedir.3, cmsg.3, confstr.3, conj.3, copysign.3, cos.3, cosh.3, cpow.3, cproj.3, creal.3, crypt.3, csin.3, csinh.3, csqrt.3, ctan.3, ctanh.3, ctermid.3, ctime.3, daemon.3, dbopen.3, des_crypt.3, difftime.3, dirfd.3, div.3, dl_iterate_phdr.3, dlopen.3, dprintf.3, drand48.3, drand48_r.3, dysize.3, ecvt.3, ecvt_r.3, encrypt.3, end.3, endian.3, envz_add.3, erf.3, erfc.3, err.3, errno.3, error.3, ether_aton.3, euidaccess.3, exec.3, exit.3, exp.3, exp10.3, exp2.3, expm1.3, fabs.3, fclose.3, fcloseall.3, fdim.3, fenv.3, ferror.3, fexecve.3, fflush.3, ffs.3, fgetgrent.3, fgetpwent.3, fgetwc.3, fgetws.3, finite.3, flockfile.3, floor.3, fma.3, fmax.3, fmemopen.3, fmin.3, fmod.3, fmtmsg.3, fnmatch.3, fopen.3, fpathconf.3, fpclassify.3, fpurge.3, fputwc.3, fputws.3, fread.3, frexp.3, fseek.3, fseeko.3, ftime.3, ftok.3, fts.3, ftw.3, futimes.3, fwide.3, gamma.3, gcvt.3, getaddrinfo.3, getaddrinfo_a.3, getauxval.3, getcontext.3, getcwd.3, getdate.3, getdirentries.3, getdtablesize.3, getenv.3, getfsent.3, getgrent.3, getgrent_r.3, getgrnam.3, getgrouplist.3, gethostbyname.3, gethostid.3, getipnodebyname.3, getline.3, getloadavg.3, getlogin.3, getmntent.3, getnameinfo.3, getnetent.3, getnetent_r.3, getopt.3, getpass.3, getprotoent.3, getprotoent_r.3, getpt.3, getpw.3, getpwent.3, getpwent_r.3, getpwnam.3, getrpcent.3, getrpcent_r.3, getrpcport.3, gets.3, getservent.3, getservent_r.3, getspnam.3, getttyent.3, getumask.3, getusershell.3, getutent.3, getw.3, getwchar.3, glob.3, grantpt.3, gsignal.3, hash.3, hsearch.3, hypot.3, iconv.3, iconv_close.3, iconv_open.3, ilogb.3, index.3, inet.3, inet_ntop.3, inet_pton.3, infnan.3, initgroups.3, insque.3, intro.3, isalpha.3, isatty.3, isgreater.3, iswalnum.3, iswalpha.3, iswblank.3, iswcntrl.3, iswctype.3, iswdigit.3, iswgraph.3, iswlower.3, iswprint.3, iswpunct.3, iswspace.3, iswupper.3, iswxdigit.3, j0.3, key_setsecret.3, ldexp.3, lgamma.3, lio_listio.3, localeconv.3, lockf.3, log.3, log10.3, log1p.3, log2.3, logb.3, login.3, longjmp.3, lrint.3, lround.3, lsearch.3, lseek64.3, makecontext.3, makedev.3, malloc.3, malloc_hook.3, mblen.3, mbrlen.3, mbrtowc.3, mbsinit.3, mbsnrtowcs.3, mbsrtowcs.3, mbstowcs.3, mbtowc.3, memccpy.3, memchr.3, memcmp.3, memcpy.3, memfrob.3, memmem.3, memmove.3, mempcpy.3, memset.3, mkdtemp.3, mkfifo.3, mkfifoat.3, mkstemp.3, mktemp.3, modf.3, mpool.3, mq_close.3, mq_getattr.3, mq_notify.3, mq_open.3, mq_receive.3, mq_send.3, mq_unlink.3, mtrace.3, nan.3, netlink.3, nextafter.3, nl_langinfo.3, offsetof.3, on_exit.3, opendir.3, openpty.3, perror.3, popen.3, posix_fallocate.3, posix_memalign.3, posix_openpt.3, pow.3, pow10.3, printf.3, profil.3, program_invocation_name.3, psignal.3, pthread_kill_other_threads_np.3, ptsname.3, putenv.3, putgrent.3, putpwent.3, puts.3, putwchar.3, qecvt.3, qsort.3, queue.3, raise.3, rand.3, random.3, random_r.3, rcmd.3, re_comp.3, readdir.3, realpath.3, recno.3, regex.3, remainder.3, remove.3, remquo.3, resolver.3, rewinddir.3, rexec.3, rint.3, round.3, rpc.3, rpmatch.3, rtime.3, rtnetlink.3, scalb.3, scalbln.3, scandir.3, scandirat.3, scanf.3, seekdir.3, sem_close.3, sem_destroy.3, sem_getvalue.3, sem_init.3, sem_open.3, sem_post.3, sem_unlink.3, sem_wait.3, setaliasent.3, setbuf.3, setenv.3, setjmp.3, setlocale.3, setlogmask.3, setnetgrent.3, shm_open.3, siginterrupt.3, signbit.3, significand.3, sigpause.3, sigqueue.3, sigset.3, sigsetops.3, sigvec.3, sin.3, sincos.3, sinh.3, sleep.3, sockatmark.3, sqrt.3, statvfs.3, stdarg.3, stdin.3, stdio.3, stdio_ext.3, stpcpy.3, stpncpy.3, strcasecmp.3, strcat.3, strchr.3, strcmp.3, strcoll.3, strcpy.3, strdup.3, strerror.3, strfmon.3, strfry.3, strftime.3, string.3, strlen.3, strnlen.3, strpbrk.3, strptime.3, strsep.3, strsignal.3, strspn.3, strstr.3, strtod.3, strtoimax.3, strtok.3, strtol.3, strtoul.3, strverscmp.3, strxfrm.3, swab.3, sysconf.3, syslog.3, system.3, sysv_signal.3, tan.3, tanh.3, tcgetpgrp.3, tcgetsid.3, telldir.3, tempnam.3, termios.3, tgamma.3, timegm.3, timeradd.3, tmpfile.3, tmpnam.3, toascii.3, toupper.3, towctrans.3, towlower.3, towupper.3, trunc.3, tsearch.3, ttyname.3, ttyslot.3, tzset.3, ualarm.3, ulimit.3, ungetwc.3, unlocked_stdio.3, unlockpt.3, updwtmp.3, usleep.3, wcpcpy.3, wcpncpy.3, wcrtomb.3, wcscasecmp.3, wcscat.3, wcschr.3, wcscmp.3, wcscpy.3, wcscspn.3, wcsdup.3, wcslen.3, wcsncasecmp.3, wcsncat.3, wcsncmp.3, wcsncpy.3, wcsnlen.3, wcsnrtombs.3, wcspbrk.3, wcsrchr.3, wcsrtombs.3, wcsspn.3, wcsstr.3, wcstoimax.3, wcstok.3, wcstombs.3, wcswidth.3, wctob.3, wctomb.3, wctrans.3, wctype.3, wcwidth.3, wmemchr.3, wmemcmp.3, wmemcpy.3, wmemmove.3, wmemset.3, wordexp.3, wprintf.3, xcrypt.3, xdr.3, y0.3, cciss.4, console.4, console_codes.4, console_ioctl.4, dsp56k.4, fd.4, full.4, hd.4, hpsa.4, initrd.4, intro.4, lp.4, mem.4, mouse.4, null.4, pts.4, ram.4, random.4, rtc.4, sk98lin.4, st.4, tty.4, ttyS.4, tty_ioctl.4, vcs.4, wavelan.4, acct.5, charmap.5, dir_colors.5, filesystems.5, ftpusers.5, group.5, host.conf.5, hosts.5, hosts.equiv.5, intro.5, issue.5, locale.5, motd.5, networks.5, nologin.5, nscd.conf.5, passwd.5, proc.5, protocols.5, resolv.conf.5, rpc.5, securetty.5, services.5, shells.5, termcap.5, ttytype.5, utmp.5, armscii-8.7, arp.7, ascii.7, bootparam.7, capabilities.7, charsets.7, complex.7, cp1251.7, credentials.7, ddp.7, environ.7, epoll.7, fifo.7, futex.7, glob.7, hier.7, icmp.7, inotify.7, intro.7, ip.7, ipv6.7, iso_8859-1.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-15.7, iso_8859-16.7, iso_8859-2.7, iso_8859-3.7, iso_8859-4.7, iso_8859-5.7, iso_8859-6.7, iso_8859-7.7, iso_8859-8.7, iso_8859-9.7, koi8-r.7, koi8-u.7, locale.7, mailaddr.7, man.7, mq_overview.7, netdevice.7, netlink.7, numa.7, packet.7, path_resolution.7, pipe.7, posixoptions.7, pthreads.7, pty.7, raw.7, regex.7, rtld-audit.7, rtnetlink.7, sem_overview.7, shm_overview.7, sigevent.7, signal.7, socket.7, standards.7, suffixes.7, svipc.7, tcp.7, termio.7, time.7, udp.7, udplite.7, unicode.7, unix.7, uri.7, utf-8.7, x25.7, nscd.8, sync.8, tzselect.8, zdump.8, zic.8: Global fix: remove unneeded double quotes in .SH headings
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2013-02-24 18:01:36 +00:00
|
|
|
.SH RETURN VALUE
|
2014-02-19 10:30:24 +00:00
|
|
|
On success, the
|
2013-07-02 11:20:04 +00:00
|
|
|
.B PTRACE_PEEK*
|
2014-02-19 10:30:24 +00:00
|
|
|
requests return the requested data (but see NOTES),
|
|
|
|
while other requests return zero.
|
2013-07-02 11:20:04 +00:00
|
|
|
.LP
|
2007-05-19 04:30:20 +00:00
|
|
|
On error, all requests return \-1, and
|
|
|
|
.I errno
|
|
|
|
is set appropriately.
|
2007-06-21 05:38:48 +00:00
|
|
|
Since the value returned by a successful
|
2007-09-20 16:26:31 +00:00
|
|
|
.B PTRACE_PEEK*
|
2011-09-26 17:33:04 +00:00
|
|
|
request may be \-1, the caller must clear
|
2007-05-19 04:30:20 +00:00
|
|
|
.I errno
|
2011-09-26 17:33:04 +00:00
|
|
|
before the call, and then check it afterward
|
|
|
|
to determine whether or not an error occurred.
|
2007-05-19 04:30:20 +00:00
|
|
|
.SH ERRORS
|
|
|
|
.TP
|
|
|
|
.B EBUSY
|
2011-09-26 17:33:04 +00:00
|
|
|
(i386 only) There was an error with allocating or freeing a debug register.
|
2007-05-19 04:30:20 +00:00
|
|
|
.TP
|
|
|
|
.B EFAULT
|
|
|
|
There was an attempt to read from or write to an invalid area in
|
2011-09-26 17:33:04 +00:00
|
|
|
the tracer's or the tracee's memory,
|
2007-05-19 04:30:20 +00:00
|
|
|
probably because the area wasn't mapped or accessible.
|
|
|
|
Unfortunately, under Linux, different variations of this fault
|
2007-06-22 19:42:52 +00:00
|
|
|
will return
|
|
|
|
.B EIO
|
|
|
|
or
|
|
|
|
.B EFAULT
|
|
|
|
more or less arbitrarily.
|
2007-05-19 04:30:20 +00:00
|
|
|
.TP
|
|
|
|
.B EINVAL
|
|
|
|
An attempt was made to set an invalid option.
|
|
|
|
.TP
|
|
|
|
.B EIO
|
2011-09-26 17:33:04 +00:00
|
|
|
.I request
|
|
|
|
is invalid, or an attempt was made to read from or
|
|
|
|
write to an invalid area in the tracer's or the tracee's memory,
|
2007-05-19 04:30:20 +00:00
|
|
|
or there was a word-alignment violation,
|
|
|
|
or an invalid signal was specified during a restart request.
|
|
|
|
.TP
|
|
|
|
.B EPERM
|
|
|
|
The specified process cannot be traced.
|
|
|
|
This could be because the
|
2011-09-24 06:29:34 +00:00
|
|
|
tracer has insufficient privileges (the required capability is
|
2007-05-19 04:30:20 +00:00
|
|
|
.BR CAP_SYS_PTRACE );
|
2010-01-16 17:24:09 +00:00
|
|
|
unprivileged processes cannot trace processes that they
|
2007-05-19 04:30:20 +00:00
|
|
|
cannot send signals to or those running
|
|
|
|
set-user-ID/set-group-ID programs, for obvious reasons.
|
2011-09-26 17:33:04 +00:00
|
|
|
Alternatively, the process may already be being traced,
|
|
|
|
or (on kernels before 2.6.26) be
|
2014-10-03 06:47:03 +00:00
|
|
|
.BR init (1)
|
2007-05-19 04:30:20 +00:00
|
|
|
(PID 1).
|
|
|
|
.TP
|
|
|
|
.B ESRCH
|
|
|
|
The specified process does not exist, or is not currently being traced
|
2011-09-26 17:33:04 +00:00
|
|
|
by the caller, or is not stopped
|
|
|
|
(for requests that require a stopped tracee).
|
getent.1, intro.1, time.1, _exit.2, _syscall.2, accept.2, access.2, acct.2, adjtimex.2, alarm.2, alloc_hugepages.2, arch_prctl.2, bdflush.2, bind.2, brk.2, cacheflush.2, capget.2, chdir.2, chmod.2, chown.2, chroot.2, clock_getres.2, clock_nanosleep.2, clone.2, close.2, connect.2, create_module.2, delete_module.2, dup.2, epoll_create.2, epoll_ctl.2, epoll_wait.2, eventfd.2, execve.2, exit_group.2, faccessat.2, fchmodat.2, fchownat.2, fcntl.2, flock.2, fork.2, fstatat.2, fsync.2, futex.2, futimesat.2, get_kernel_syms.2, get_robust_list.2, get_thread_area.2, getcpu.2, getdents.2, getdomainname.2, getgid.2, getgroups.2, gethostname.2, getitimer.2, getpagesize.2, getpeername.2, getpid.2, getpriority.2, getresuid.2, getrlimit.2, getrusage.2, getsid.2, getsockname.2, getsockopt.2, gettid.2, gettimeofday.2, getuid.2, getunwind.2, getxattr.2, idle.2, init_module.2, inotify_add_watch.2, inotify_init.2, inotify_rm_watch.2, intro.2, io_cancel.2, io_destroy.2, io_getevents.2, io_setup.2, io_submit.2, ioctl.2, ioctl_list.2, ioperm.2, iopl.2, ioprio_set.2, ipc.2, kcmp.2, kill.2, killpg.2, link.2, linkat.2, listen.2, listxattr.2, llseek.2, lookup_dcookie.2, lseek.2, madvise.2, migrate_pages.2, mincore.2, mkdir.2, mkdirat.2, mknod.2, mknodat.2, mlock.2, mmap.2, mmap2.2, modify_ldt.2, mount.2, move_pages.2, mprotect.2, mq_getsetattr.2, mremap.2, msgctl.2, msgget.2, msgop.2, msync.2, nanosleep.2, nfsservctl.2, nice.2, open.2, openat.2, outb.2, pause.2, pciconfig_read.2, perf_event_open.2, perfmonctl.2, personality.2, pipe.2, pivot_root.2, poll.2, posix_fadvise.2, prctl.2, pread.2, process_vm_readv.2, ptrace.2, query_module.2, quotactl.2, read.2, readahead.2, readdir.2, readlink.2, readlinkat.2, readv.2, reboot.2, recv.2, remap_file_pages.2, removexattr.2, rename.2, renameat.2, rmdir.2, rt_sigqueueinfo.2, sched_get_priority_max.2, sched_rr_get_interval.2, sched_setaffinity.2, sched_setparam.2, sched_setscheduler.2, sched_yield.2, select.2, semctl.2, semget.2, semop.2, send.2, sendfile.2, set_thread_area.2, set_tid_address.2, seteuid.2, setfsgid.2, setfsuid.2, setgid.2, setpgid.2, setresuid.2, setreuid.2, setsid.2, setuid.2, setup.2, setxattr.2, shmctl.2, shmget.2, shmop.2, shutdown.2, sigaction.2, sigaltstack.2, signal.2, signalfd.2, sigpending.2, sigprocmask.2, sigreturn.2, sigsuspend.2, sigwaitinfo.2, socket.2, socketcall.2, socketpair.2, splice.2, stat.2, statfs.2, stime.2, swapon.2, symlink.2, symlinkat.2, sync.2, sync_file_range.2, sysctl.2, sysfs.2, sysinfo.2, syslog.2, tee.2, time.2, timerfd_create.2, times.2, tkill.2, truncate.2, umask.2, umount.2, uname.2, unimplemented.2, unlink.2, unlinkat.2, uselib.2, ustat.2, utime.2, utimensat.2, vfork.2, vhangup.2, vm86.2, vmsplice.2, wait.2, wait4.2, write.2, CPU_SET.3, INFINITY.3, MB_CUR_MAX.3, MB_LEN_MAX.3, __setfpucw.3, a64l.3, abort.3, abs.3, acos.3, acosh.3, addseverity.3, adjtime.3, aio_cancel.3, aio_error.3, aio_fsync.3, aio_read.3, aio_return.3, aio_suspend.3, aio_write.3, alloca.3, argz_add.3, asin.3, asinh.3, asprintf.3, assert.3, assert_perror.3, atan.3, atan2.3, atanh.3, atexit.3, atof.3, atoi.3, backtrace.3, basename.3, bcmp.3, bcopy.3, bindresvport.3, bsd_signal.3, bsearch.3, bstring.3, btowc.3, btree.3, byteorder.3, bzero.3, cabs.3, cacos.3, cacosh.3, canonicalize_file_name.3, carg.3, casin.3, casinh.3, catan.3, catanh.3, catgets.3, catopen.3, cbrt.3, ccos.3, ccosh.3, ceil.3, cerf.3, cexp.3, cexp2.3, cfree.3, cimag.3, clearenv.3, clock.3, clock_getcpuclockid.3, clog.3, clog10.3, clog2.3, closedir.3, cmsg.3, confstr.3, conj.3, copysign.3, cos.3, cosh.3, cpow.3, cproj.3, creal.3, crypt.3, csin.3, csinh.3, csqrt.3, ctan.3, ctanh.3, ctermid.3, ctime.3, daemon.3, dbopen.3, des_crypt.3, difftime.3, dirfd.3, div.3, dl_iterate_phdr.3, dlopen.3, dprintf.3, drand48.3, drand48_r.3, dysize.3, ecvt.3, ecvt_r.3, encrypt.3, end.3, endian.3, envz_add.3, erf.3, erfc.3, err.3, errno.3, error.3, ether_aton.3, euidaccess.3, exec.3, exit.3, exp.3, exp10.3, exp2.3, expm1.3, fabs.3, fclose.3, fcloseall.3, fdim.3, fenv.3, ferror.3, fexecve.3, fflush.3, ffs.3, fgetgrent.3, fgetpwent.3, fgetwc.3, fgetws.3, finite.3, flockfile.3, floor.3, fma.3, fmax.3, fmemopen.3, fmin.3, fmod.3, fmtmsg.3, fnmatch.3, fopen.3, fpathconf.3, fpclassify.3, fpurge.3, fputwc.3, fputws.3, fread.3, frexp.3, fseek.3, fseeko.3, ftime.3, ftok.3, fts.3, ftw.3, futimes.3, fwide.3, gamma.3, gcvt.3, getaddrinfo.3, getaddrinfo_a.3, getauxval.3, getcontext.3, getcwd.3, getdate.3, getdirentries.3, getdtablesize.3, getenv.3, getfsent.3, getgrent.3, getgrent_r.3, getgrnam.3, getgrouplist.3, gethostbyname.3, gethostid.3, getipnodebyname.3, getline.3, getloadavg.3, getlogin.3, getmntent.3, getnameinfo.3, getnetent.3, getnetent_r.3, getopt.3, getpass.3, getprotoent.3, getprotoent_r.3, getpt.3, getpw.3, getpwent.3, getpwent_r.3, getpwnam.3, getrpcent.3, getrpcent_r.3, getrpcport.3, gets.3, getservent.3, getservent_r.3, getspnam.3, getttyent.3, getumask.3, getusershell.3, getutent.3, getw.3, getwchar.3, glob.3, grantpt.3, gsignal.3, hash.3, hsearch.3, hypot.3, iconv.3, iconv_close.3, iconv_open.3, ilogb.3, index.3, inet.3, inet_ntop.3, inet_pton.3, infnan.3, initgroups.3, insque.3, intro.3, isalpha.3, isatty.3, isgreater.3, iswalnum.3, iswalpha.3, iswblank.3, iswcntrl.3, iswctype.3, iswdigit.3, iswgraph.3, iswlower.3, iswprint.3, iswpunct.3, iswspace.3, iswupper.3, iswxdigit.3, j0.3, key_setsecret.3, ldexp.3, lgamma.3, lio_listio.3, localeconv.3, lockf.3, log.3, log10.3, log1p.3, log2.3, logb.3, login.3, longjmp.3, lrint.3, lround.3, lsearch.3, lseek64.3, makecontext.3, makedev.3, malloc.3, malloc_hook.3, mblen.3, mbrlen.3, mbrtowc.3, mbsinit.3, mbsnrtowcs.3, mbsrtowcs.3, mbstowcs.3, mbtowc.3, memccpy.3, memchr.3, memcmp.3, memcpy.3, memfrob.3, memmem.3, memmove.3, mempcpy.3, memset.3, mkdtemp.3, mkfifo.3, mkfifoat.3, mkstemp.3, mktemp.3, modf.3, mpool.3, mq_close.3, mq_getattr.3, mq_notify.3, mq_open.3, mq_receive.3, mq_send.3, mq_unlink.3, mtrace.3, nan.3, netlink.3, nextafter.3, nl_langinfo.3, offsetof.3, on_exit.3, opendir.3, openpty.3, perror.3, popen.3, posix_fallocate.3, posix_memalign.3, posix_openpt.3, pow.3, pow10.3, printf.3, profil.3, program_invocation_name.3, psignal.3, pthread_kill_other_threads_np.3, ptsname.3, putenv.3, putgrent.3, putpwent.3, puts.3, putwchar.3, qecvt.3, qsort.3, queue.3, raise.3, rand.3, random.3, random_r.3, rcmd.3, re_comp.3, readdir.3, realpath.3, recno.3, regex.3, remainder.3, remove.3, remquo.3, resolver.3, rewinddir.3, rexec.3, rint.3, round.3, rpc.3, rpmatch.3, rtime.3, rtnetlink.3, scalb.3, scalbln.3, scandir.3, scandirat.3, scanf.3, seekdir.3, sem_close.3, sem_destroy.3, sem_getvalue.3, sem_init.3, sem_open.3, sem_post.3, sem_unlink.3, sem_wait.3, setaliasent.3, setbuf.3, setenv.3, setjmp.3, setlocale.3, setlogmask.3, setnetgrent.3, shm_open.3, siginterrupt.3, signbit.3, significand.3, sigpause.3, sigqueue.3, sigset.3, sigsetops.3, sigvec.3, sin.3, sincos.3, sinh.3, sleep.3, sockatmark.3, sqrt.3, statvfs.3, stdarg.3, stdin.3, stdio.3, stdio_ext.3, stpcpy.3, stpncpy.3, strcasecmp.3, strcat.3, strchr.3, strcmp.3, strcoll.3, strcpy.3, strdup.3, strerror.3, strfmon.3, strfry.3, strftime.3, string.3, strlen.3, strnlen.3, strpbrk.3, strptime.3, strsep.3, strsignal.3, strspn.3, strstr.3, strtod.3, strtoimax.3, strtok.3, strtol.3, strtoul.3, strverscmp.3, strxfrm.3, swab.3, sysconf.3, syslog.3, system.3, sysv_signal.3, tan.3, tanh.3, tcgetpgrp.3, tcgetsid.3, telldir.3, tempnam.3, termios.3, tgamma.3, timegm.3, timeradd.3, tmpfile.3, tmpnam.3, toascii.3, toupper.3, towctrans.3, towlower.3, towupper.3, trunc.3, tsearch.3, ttyname.3, ttyslot.3, tzset.3, ualarm.3, ulimit.3, ungetwc.3, unlocked_stdio.3, unlockpt.3, updwtmp.3, usleep.3, wcpcpy.3, wcpncpy.3, wcrtomb.3, wcscasecmp.3, wcscat.3, wcschr.3, wcscmp.3, wcscpy.3, wcscspn.3, wcsdup.3, wcslen.3, wcsncasecmp.3, wcsncat.3, wcsncmp.3, wcsncpy.3, wcsnlen.3, wcsnrtombs.3, wcspbrk.3, wcsrchr.3, wcsrtombs.3, wcsspn.3, wcsstr.3, wcstoimax.3, wcstok.3, wcstombs.3, wcswidth.3, wctob.3, wctomb.3, wctrans.3, wctype.3, wcwidth.3, wmemchr.3, wmemcmp.3, wmemcpy.3, wmemmove.3, wmemset.3, wordexp.3, wprintf.3, xcrypt.3, xdr.3, y0.3, cciss.4, console.4, console_codes.4, console_ioctl.4, dsp56k.4, fd.4, full.4, hd.4, hpsa.4, initrd.4, intro.4, lp.4, mem.4, mouse.4, null.4, pts.4, ram.4, random.4, rtc.4, sk98lin.4, st.4, tty.4, ttyS.4, tty_ioctl.4, vcs.4, wavelan.4, acct.5, charmap.5, dir_colors.5, filesystems.5, ftpusers.5, group.5, host.conf.5, hosts.5, hosts.equiv.5, intro.5, issue.5, locale.5, motd.5, networks.5, nologin.5, nscd.conf.5, passwd.5, proc.5, protocols.5, resolv.conf.5, rpc.5, securetty.5, services.5, shells.5, termcap.5, ttytype.5, utmp.5, armscii-8.7, arp.7, ascii.7, bootparam.7, capabilities.7, charsets.7, complex.7, cp1251.7, credentials.7, ddp.7, environ.7, epoll.7, fifo.7, futex.7, glob.7, hier.7, icmp.7, inotify.7, intro.7, ip.7, ipv6.7, iso_8859-1.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-15.7, iso_8859-16.7, iso_8859-2.7, iso_8859-3.7, iso_8859-4.7, iso_8859-5.7, iso_8859-6.7, iso_8859-7.7, iso_8859-8.7, iso_8859-9.7, koi8-r.7, koi8-u.7, locale.7, mailaddr.7, man.7, mq_overview.7, netdevice.7, netlink.7, numa.7, packet.7, path_resolution.7, pipe.7, posixoptions.7, pthreads.7, pty.7, raw.7, regex.7, rtld-audit.7, rtnetlink.7, sem_overview.7, shm_overview.7, sigevent.7, signal.7, socket.7, standards.7, suffixes.7, svipc.7, tcp.7, termio.7, time.7, udp.7, udplite.7, unicode.7, unix.7, uri.7, utf-8.7, x25.7, nscd.8, sync.8, tzselect.8, zdump.8, zic.8: Global fix: remove unneeded double quotes in .SH headings
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2013-02-24 18:01:36 +00:00
|
|
|
.SH CONFORMING TO
|
2008-07-15 13:39:17 +00:00
|
|
|
SVr4, 4.3BSD.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NOTES
|
|
|
|
Although arguments to
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR ptrace ()
|
2007-04-12 22:42:49 +00:00
|
|
|
are interpreted according to the prototype given,
|
2007-07-09 22:01:31 +00:00
|
|
|
glibc currently declares
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR ptrace ()
|
2011-09-26 17:33:04 +00:00
|
|
|
as a variadic function with only the
|
|
|
|
.I request
|
|
|
|
argument fixed.
|
2012-08-03 04:28:46 +00:00
|
|
|
It is recommended to always supply four arguments,
|
|
|
|
even if the requested operation does not use them,
|
|
|
|
setting unused/ignored arguments to
|
|
|
|
.I 0L
|
|
|
|
or
|
|
|
|
.IR "(void\ *)\ 0".
|
2011-09-26 17:33:04 +00:00
|
|
|
.LP
|
|
|
|
In Linux kernels before 2.6.26,
|
|
|
|
.\" See commit 00cd5c37afd5f431ac186dd131705048c0a11fdb
|
2014-10-03 06:47:03 +00:00
|
|
|
.BR init (1),
|
2011-09-26 17:33:04 +00:00
|
|
|
the process with PID 1, may not be traced.
|
|
|
|
.LP
|
2015-02-05 13:23:17 +00:00
|
|
|
A tracees parent continues to be the tracer even if that tracer calls
|
|
|
|
.BR execve (2).
|
|
|
|
.LP
|
2011-09-26 17:33:04 +00:00
|
|
|
The layout of the contents of memory and the USER area are
|
|
|
|
quite operating-system- and architecture-specific.
|
2008-05-21 20:23:25 +00:00
|
|
|
The offset supplied, and the data returned,
|
|
|
|
might not entirely match with the definition of
|
|
|
|
.IR "struct user" .
|
|
|
|
.\" See http://lkml.org/lkml/2008/5/8/375
|
2004-11-03 13:51:07 +00:00
|
|
|
.LP
|
2011-09-26 17:33:04 +00:00
|
|
|
The size of a "word" is determined by the operating-system variant
|
2012-05-06 19:57:02 +00:00
|
|
|
(e.g., for 32-bit Linux it is 32 bits).
|
2012-03-05 17:16:37 +00:00
|
|
|
.LP
|
2004-11-03 13:51:07 +00:00
|
|
|
This page documents the way the
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR ptrace ()
|
2007-04-12 22:42:49 +00:00
|
|
|
call works currently in Linux.
|
2014-05-15 12:20:26 +00:00
|
|
|
Its behavior differs significantly on other flavors of UNIX.
|
2006-03-25 21:28:28 +00:00
|
|
|
In any case, use of
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR ptrace ()
|
2011-09-26 17:33:04 +00:00
|
|
|
is highly specific to the operating system and architecture.
|
2015-10-08 12:00:52 +00:00
|
|
|
.\"
|
2016-06-09 20:13:53 +00:00
|
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
|
|
.\"
|
|
|
|
.SS Ptrace access mode checking
|
|
|
|
Various parts of the kernel-user-space API (not just
|
arch_prctl.2, execveat.2, fanotify_mark.2, fcntl.2, fork.2, madvise.2, mknod.2, mmap.2, modify_ldt.2, mount.2, open.2, prctl.2, ptrace.2, restart_syscall.2, seccomp.2, semop.2, set_thread_area.2, symlink.2, umount.2, unlink.2, error.3, getnetent.3, getprotoent.3, getservent.3, getutent.3, glob.3, login.3, setjmp.3, setnetgrent.3, wordexp.3, epoll.7: Remove section number from page self reference
Fix places where pages refer to the function that they describe
and include a section number in that reference. Such references
cause some HTML-rendering tools to create self-references in the
page.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2016-08-07 16:40:35 +00:00
|
|
|
.BR ptrace ()
|
2016-06-24 09:49:09 +00:00
|
|
|
operations), require so-called "ptrace access mode" checks,
|
|
|
|
whose outcome determines whether an operation is permitted
|
|
|
|
(or, in a few cases, causes a "read" operation to return sanitized data).
|
|
|
|
These checks are performed in cases where one process can
|
|
|
|
inspect sensitive information about,
|
|
|
|
or in some cases modify the state of, another process.
|
|
|
|
The checks are based on factors such as the credentials and capabilities
|
|
|
|
of the two processes,
|
|
|
|
whether or not the "target" process is dumpable,
|
|
|
|
and the results of checks performed by any enabled Linux Security Module
|
|
|
|
(LSM)\(emfor example, SELinux, Yama, or Smack\(emand by the commoncap LSM
|
2016-06-22 19:12:57 +00:00
|
|
|
(which is always invoked).
|
2016-06-24 08:41:49 +00:00
|
|
|
|
|
|
|
Prior to Linux 2.6.27, all access checks were of a single type.
|
2016-06-09 20:13:53 +00:00
|
|
|
Since Linux 2.6.27,
|
|
|
|
.\" commit 006ebb40d3d65338bd74abb03b945f8d60e362bd
|
|
|
|
two access mode levels are distinguished:
|
|
|
|
.TP
|
|
|
|
.BR PTRACE_MODE_READ
|
|
|
|
For "read" operations or other operations that are less dangerous,
|
|
|
|
such as:
|
|
|
|
.BR get_robust_list (2);
|
|
|
|
.BR kcmp (2);
|
|
|
|
reading
|
|
|
|
.IR /proc/[pid]/auxv ,
|
|
|
|
.IR /proc/[pid]/environ ,
|
|
|
|
or
|
|
|
|
.IR /proc/[pid]/stat ;
|
|
|
|
or
|
|
|
|
.BR readlink (2)
|
|
|
|
of a
|
|
|
|
.IR /proc/[pid]/ns/*
|
|
|
|
file.
|
|
|
|
.TP
|
|
|
|
.BR PTRACE_MODE_ATTACH
|
|
|
|
For "write" operations, or other operations that are more dangerous,
|
|
|
|
such as: ptrace attaching
|
|
|
|
.RB ( PTRACE_ATTACH )
|
|
|
|
to another process
|
|
|
|
or calling
|
|
|
|
.BR process_vm_writev (2).
|
|
|
|
.RB ( PTRACE_MODE_ATTACH
|
|
|
|
was effectively the default before Linux 2.6.27.)
|
2016-06-24 08:33:01 +00:00
|
|
|
.\"
|
|
|
|
.\" Regarding the above description of the distinction between
|
|
|
|
.\" PTRACE_MODE_READ and PTRACE_MODE_ATTACH, Stephen Smalley notes:
|
|
|
|
.\"
|
|
|
|
.\" That was the intent when the distinction was introduced, but it doesn't
|
|
|
|
.\" appear to have been properly maintained, e.g. there is now a common
|
|
|
|
.\" helper lock_trace() that is used for
|
|
|
|
.\" /proc/pid/{stack,syscall,personality} but checks PTRACE_MODE_ATTACH, and
|
|
|
|
.\" PTRACE_MODE_ATTACH is also used in timerslack_ns_write/show(). Likely
|
|
|
|
.\" should review and make them consistent. There was also some debate
|
|
|
|
.\" about proper handling of /proc/pid/fd. Arguably that one might belong
|
|
|
|
.\" back in the _ATTACH camp.
|
|
|
|
.\"
|
2016-06-09 20:13:53 +00:00
|
|
|
.PP
|
|
|
|
Since Linux 4.5,
|
|
|
|
.\" commit caaee6234d05a58c5b4d05e7bf766131b810a657
|
2016-06-22 19:12:57 +00:00
|
|
|
the above access mode checks are combined (ORed) with
|
2016-06-09 20:13:53 +00:00
|
|
|
one of the following modifiers:
|
|
|
|
.TP
|
|
|
|
.B PTRACE_MODE_FSCREDS
|
|
|
|
Use the caller's filesystem UID and GID (see
|
|
|
|
.BR credentials (7))
|
|
|
|
or effective capabilities for LSM checks.
|
|
|
|
.TP
|
|
|
|
.B PTRACE_MODE_REALCREDS
|
|
|
|
Use the caller's real UID and GID or permitted capabilities for LSM checks.
|
|
|
|
This was effectively the default before Linux 4.5.
|
|
|
|
.PP
|
|
|
|
Because combining one of the credential modifiers with one of
|
|
|
|
the aforementioned access modes is typical,
|
|
|
|
some macros are defined in the kernel sources for the combinations:
|
|
|
|
.TP
|
|
|
|
.B PTRACE_MODE_READ_FSCREDS
|
|
|
|
Defined as
|
|
|
|
.BR "PTRACE_MODE_READ | PTRACE_MODE_FSCREDS" .
|
|
|
|
.TP
|
|
|
|
.B PTRACE_MODE_READ_REALCREDS
|
|
|
|
Defined as
|
|
|
|
.BR "PTRACE_MODE_READ | PTRACE_MODE_REALCREDS" .
|
|
|
|
.TP
|
|
|
|
.B PTRACE_MODE_ATTACH_FSCREDS
|
|
|
|
Defined as
|
|
|
|
.BR "PTRACE_MODE_ATTACH | PTRACE_MODE_FSCREDS" .
|
|
|
|
.TP
|
|
|
|
.B PTRACE_MODE_ATTACH_REALCREDS
|
|
|
|
Defined as
|
|
|
|
.BR "PTRACE_MODE_ATTACH | PTRACE_MODE_REALCREDS" .
|
|
|
|
.PP
|
|
|
|
One further modifier can be ORed with the access mode:
|
|
|
|
.TP
|
|
|
|
.BR PTRACE_MODE_NOAUDIT " (since Linux 3.3)"
|
|
|
|
.\" commit 69f594a38967f4540ce7a29b3fd214e68a8330bd
|
|
|
|
.\" Just for /proc/pid/stat
|
|
|
|
Don't audit this access mode check.
|
2016-06-24 08:27:53 +00:00
|
|
|
This modifier is employed for ptrace access mode checks
|
|
|
|
(such as checks when reading
|
|
|
|
.IR /proc/[pid]/stat )
|
|
|
|
that merely cause the output to be filtered or sanitized,
|
|
|
|
rather than causing an error to be returned to the caller.
|
|
|
|
In these cases, accessing the file is not a security violation and
|
|
|
|
there is no reason to generate a security audit record.
|
|
|
|
This modifier suppresses the generation of
|
|
|
|
such an audit record for the particular access check.
|
2016-06-09 20:13:53 +00:00
|
|
|
.PP
|
2016-06-24 08:43:26 +00:00
|
|
|
Note that all of the
|
|
|
|
.BR PTRACE_MODE_*
|
|
|
|
constants described in this subsection are kernel-internal,
|
|
|
|
and not visible to user space.
|
|
|
|
The constant names are mentioned here in order to label the various kinds of
|
|
|
|
ptrace access mode checks that are performed for various system calls
|
|
|
|
and accesses to various pseudofiles (e.g., under
|
|
|
|
.IR /proc ).
|
2016-06-24 08:44:45 +00:00
|
|
|
These names are used in other manual pages to provide a simple
|
2016-06-24 08:43:26 +00:00
|
|
|
shorthand for labeling the different kernel checks.
|
|
|
|
|
2016-06-09 20:13:53 +00:00
|
|
|
The algorithm employed for ptrace access mode checking determines whether
|
|
|
|
the calling process is allowed to perform the corresponding action
|
2016-06-23 04:30:37 +00:00
|
|
|
on the target process.
|
|
|
|
(In the case of opening
|
|
|
|
.IR /proc/[pid]
|
|
|
|
files, the "calling process" is the one opening the file,
|
|
|
|
and the process with the corresponding PID is the "target process".)
|
|
|
|
The algorithm is as follows:
|
2016-06-09 20:13:53 +00:00
|
|
|
.IP 1. 4
|
|
|
|
If the calling thread and the target thread are in the same
|
|
|
|
thread group, access is always allowed.
|
|
|
|
.IP 2.
|
|
|
|
If the access mode specifies
|
|
|
|
.BR PTRACE_MODE_FSCREDS ,
|
2016-06-23 07:41:03 +00:00
|
|
|
then, for the check in the next step,
|
|
|
|
employ the caller's filesystem UID and GID.
|
|
|
|
(As noted in
|
|
|
|
.BR credentials (7),
|
|
|
|
the filesystem UID and GID almost always have the same values
|
|
|
|
as the corresponding effective IDs.)
|
|
|
|
|
|
|
|
Otherwise, the access mode specifies
|
2016-06-09 20:13:53 +00:00
|
|
|
.BR PTRACE_MODE_REALCREDS ,
|
2016-06-23 07:41:03 +00:00
|
|
|
so use the caller's real UID and GID for the checks in the next step.
|
|
|
|
(Most APIs that check the caller's UID and GID use the effective IDs.
|
|
|
|
For historical reasons, the
|
|
|
|
.BR PTRACE_MODE_REALCREDS
|
|
|
|
check uses the real IDs instead.)
|
2016-06-09 20:13:53 +00:00
|
|
|
.IP 3.
|
|
|
|
Deny access if
|
|
|
|
.I neither
|
|
|
|
of the following is true:
|
|
|
|
.RS
|
|
|
|
.IP \(bu 2
|
|
|
|
The real, effective, and saved-set user IDs of the target
|
|
|
|
match the caller's user ID,
|
|
|
|
.IR and
|
|
|
|
the real, effective, and saved-set group IDs of the target
|
|
|
|
match the caller's group ID.
|
|
|
|
.IP \(bu
|
|
|
|
The caller has the
|
|
|
|
.B CAP_SYS_PTRACE
|
2016-06-22 18:57:08 +00:00
|
|
|
capability in the user namespace of the target.
|
2016-06-09 20:13:53 +00:00
|
|
|
.RE
|
|
|
|
.IP 4.
|
|
|
|
Deny access if the target process "dumpable" attribute has a value other than 1
|
|
|
|
.RB ( SUID_DUMP_USER ;
|
|
|
|
see the discussion of
|
|
|
|
.BR PR_SET_DUMPABLE
|
|
|
|
in
|
|
|
|
.BR prctl (2)),
|
|
|
|
and the caller does not have the
|
|
|
|
.BR CAP_SYS_PTRACE
|
|
|
|
capability in the user namespace of the target process.
|
|
|
|
.IP 5.
|
|
|
|
The kernel LSM
|
|
|
|
.IR security_ptrace_access_check ()
|
|
|
|
interface is invoked to see if ptrace access is permitted.
|
2016-06-25 06:31:28 +00:00
|
|
|
The results depend on the LSM(s).
|
2016-06-22 19:12:57 +00:00
|
|
|
The implementation of this interface in the commoncap LSM performs
|
2016-06-09 20:13:53 +00:00
|
|
|
the following steps:
|
|
|
|
.\" (in cap_ptrace_access_check()):
|
|
|
|
.RS
|
|
|
|
.IP a) 3
|
|
|
|
If the access mode includes
|
|
|
|
.BR PTRACE_MODE_FSCREDS ,
|
|
|
|
then use the caller's
|
|
|
|
.I effective
|
|
|
|
capability set
|
|
|
|
in the following check;
|
|
|
|
otherwise (the access mode specifies
|
|
|
|
.BR PTRACE_MODE_REALCREDS ,
|
|
|
|
so) use the caller's
|
|
|
|
.I permitted
|
|
|
|
capability set.
|
|
|
|
.IP b)
|
|
|
|
Deny access if
|
|
|
|
.I neither
|
|
|
|
of the following is true:
|
|
|
|
.RS
|
|
|
|
.IP \(bu 2
|
2016-06-22 18:57:08 +00:00
|
|
|
The caller and the target process are in the same user namespace,
|
|
|
|
and the caller's capabilities are a proper superset of the target process's
|
2016-06-09 20:13:53 +00:00
|
|
|
.I permitted
|
|
|
|
capabilities.
|
|
|
|
.IP \(bu
|
|
|
|
The caller has the
|
|
|
|
.B CAP_SYS_PTRACE
|
|
|
|
capability in the target process's user namespace.
|
|
|
|
.RE
|
|
|
|
.IP
|
2016-06-22 19:12:57 +00:00
|
|
|
Note that the commoncap LSM does not distinguish between
|
2016-06-09 20:13:53 +00:00
|
|
|
.B PTRACE_MODE_READ
|
|
|
|
and
|
|
|
|
.BR PTRACE_MODE_ATTACH .
|
|
|
|
.RE
|
|
|
|
.IP 6.
|
|
|
|
If access has not been denied by any of the preceding steps,
|
|
|
|
then access is allowed.
|
|
|
|
.\"
|
|
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
|
|
.\"
|
2015-10-08 12:00:52 +00:00
|
|
|
.SS /proc/sys/kernel/yama/ptrace_scope
|
2016-06-25 07:25:09 +00:00
|
|
|
On systems with the Yama Linux Security Module (LSM) installed
|
|
|
|
(i.e., the kernel was configured with
|
|
|
|
.BR CONFIG_SECURITY_YAMA ),
|
|
|
|
the
|
2015-10-08 12:00:52 +00:00
|
|
|
.I /proc/sys/kernel/yama/ptrace_scope
|
2016-06-25 06:41:05 +00:00
|
|
|
file (available since Linux 3.4)
|
2015-10-08 12:00:52 +00:00
|
|
|
.\" commit 2d514487faf188938a4ee4fb3464eeecfbdcf8eb
|
|
|
|
can be used to restrict the ability to trace a process with
|
arch_prctl.2, execveat.2, fanotify_mark.2, fcntl.2, fork.2, madvise.2, mknod.2, mmap.2, modify_ldt.2, mount.2, open.2, prctl.2, ptrace.2, restart_syscall.2, seccomp.2, semop.2, set_thread_area.2, symlink.2, umount.2, unlink.2, error.3, getnetent.3, getprotoent.3, getservent.3, getutent.3, glob.3, login.3, setjmp.3, setnetgrent.3, wordexp.3, epoll.7: Remove section number from page self reference
Fix places where pages refer to the function that they describe
and include a section number in that reference. Such references
cause some HTML-rendering tools to create self-references in the
page.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2016-08-07 16:40:35 +00:00
|
|
|
.BR ptrace ()
|
2015-10-08 12:00:52 +00:00
|
|
|
(and thus also the ability to use tools such as
|
|
|
|
.BR strace (1)
|
|
|
|
and
|
|
|
|
.BR gdb (1)).
|
|
|
|
The goal of such restrictions is to prevent attack escalation whereby
|
|
|
|
a compromised process can ptrace-attach to other sensitive processes
|
|
|
|
(e.g., a GPG agent or an SSH session) owned by the user in order
|
2016-06-29 05:02:50 +00:00
|
|
|
to gain additional credentials that may exist in memory
|
|
|
|
and thus expand the scope of the attack.
|
2015-10-08 12:00:52 +00:00
|
|
|
|
2016-06-25 07:25:09 +00:00
|
|
|
More precisely, the Yama LSM limits two types of operations:
|
|
|
|
.IP * 3
|
|
|
|
Any operation that performs a ptrace access mode
|
|
|
|
.BR PTRACE_MODE_ATTACH
|
|
|
|
check\(emfor example,
|
|
|
|
.BR ptrace ()
|
|
|
|
.BR PTRACE_ATTACH .
|
|
|
|
(See the "Ptrace access mode checking" discussion above.)
|
|
|
|
|
|
|
|
.IP *
|
|
|
|
.BR ptrace ()
|
|
|
|
.BR PTRACE_TRACEME .
|
|
|
|
.PP
|
|
|
|
A process that has the
|
2015-10-08 12:00:52 +00:00
|
|
|
.B CAP_SYS_PTRACE
|
2016-06-25 07:25:09 +00:00
|
|
|
capability can update the
|
|
|
|
.IR /proc/sys/kernel/yama/ptrace_scope
|
|
|
|
file with one of the following values:
|
2015-10-08 12:00:52 +00:00
|
|
|
.TP
|
|
|
|
0 ("classic ptrace permissions")
|
2016-06-25 07:25:09 +00:00
|
|
|
No additional restrictions on operations that perform
|
|
|
|
.BR PTRACE_MODE_ATTACH
|
|
|
|
checks (beyond those imposed by the commoncap and other LSMs).
|
2015-10-08 12:00:52 +00:00
|
|
|
|
|
|
|
The use of
|
|
|
|
.BR PTRACE_TRACEME
|
|
|
|
is unchanged.
|
|
|
|
.TP
|
2016-06-25 07:25:09 +00:00
|
|
|
1 ("restricted ptrace") [default value]
|
|
|
|
When performing an operation that requires a
|
|
|
|
.BR PTRACE_MODE_ATTACH
|
2016-06-28 05:05:21 +00:00
|
|
|
check, the calling process must either have the
|
|
|
|
.B CAP_SYS_PTRACE
|
|
|
|
capability in the user namespace of the target process or
|
2016-06-29 04:47:16 +00:00
|
|
|
it must have a predefined relationship with the target process.
|
2015-10-08 12:00:52 +00:00
|
|
|
By default,
|
2016-06-25 07:25:09 +00:00
|
|
|
the predefined relationship is that the target process
|
2016-06-29 05:02:50 +00:00
|
|
|
must be a descendant of the caller.
|
2016-06-25 07:25:09 +00:00
|
|
|
|
|
|
|
A target process can employ the
|
2015-10-08 12:00:52 +00:00
|
|
|
.BR prctl (2)
|
|
|
|
.B PR_SET_PTRACER
|
2016-06-29 05:02:50 +00:00
|
|
|
operation to declare an additional PID that is allowed to perform
|
2016-06-25 07:25:09 +00:00
|
|
|
.BR PTRACE_MODE_ATTACH
|
|
|
|
operations on the target.
|
|
|
|
See the kernel source file
|
2015-10-08 12:00:52 +00:00
|
|
|
.IR Documentation/security/Yama.txt
|
2016-06-25 07:25:09 +00:00
|
|
|
for further details.
|
2015-10-08 12:00:52 +00:00
|
|
|
|
|
|
|
The use of
|
|
|
|
.BR PTRACE_TRACEME
|
|
|
|
is unchanged.
|
|
|
|
.TP
|
|
|
|
2 ("admin-only attach")
|
|
|
|
Only processes with the
|
|
|
|
.B CAP_SYS_PTRACE
|
2016-06-28 05:05:21 +00:00
|
|
|
capability in the user namespace of the target process may perform
|
2016-06-25 07:25:09 +00:00
|
|
|
.BR PTRACE_MODE_ATTACH
|
|
|
|
operations or trace children that employ
|
2015-10-08 12:00:52 +00:00
|
|
|
.BR PTRACE_TRACEME .
|
|
|
|
.TP
|
|
|
|
3 ("no attach")
|
2016-06-25 07:25:09 +00:00
|
|
|
No process may perform
|
|
|
|
.BR PTRACE_MODE_ATTACH
|
|
|
|
operations or trace children that employ
|
2015-10-08 12:00:52 +00:00
|
|
|
.BR PTRACE_TRACEME .
|
|
|
|
|
|
|
|
Once this value has been written to the file, it cannot be changed.
|
2016-06-28 05:05:21 +00:00
|
|
|
.PP
|
|
|
|
With respect to values 1 and 2,
|
2016-06-29 05:02:50 +00:00
|
|
|
note that creating a new user namespace effectively removes the
|
|
|
|
protection offered by Yama.
|
|
|
|
This is because a process in the parent user namespace whose effective
|
|
|
|
UID matches the UID of the creator of a child namespace
|
|
|
|
has all capabilities (including
|
|
|
|
.BR CAP_SYS_PTRACE )
|
|
|
|
when performing operations within the child user namespace
|
|
|
|
(and further-removed descendants of that namespace).
|
|
|
|
Consequently, when a process tries to use user namespaces to sandbox itself,
|
|
|
|
it inadvertently weakens the protections offered by the Yama LSM.
|
2015-10-08 12:00:52 +00:00
|
|
|
.\"
|
2016-06-25 07:25:09 +00:00
|
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
|
|
.\"
|
_exit.2, access.2, brk.2, chmod.2, clone.2, epoll_wait.2, eventfd.2, fork.2, getgroups.2, gethostname.2, getpid.2, getpriority.2, killpg.2, mmap.2, poll.2, posix_fadvise.2, pread.2, ptrace.2, readv.2, sched_setaffinity.2, select.2, seteuid.2, setgid.2, setresuid.2, setreuid.2, setuid.2, sigaction.2, signalfd.2, sigpending.2, sigprocmask.2, sigreturn.2, sigsuspend.2, sigwaitinfo.2, stat.2, timer_create.2, uname.2, wait.2, wait4.2, mq_notify.3, mq_open.3, sigqueue.3, man-pages.7: Remove "ABI" from "C library/kernel ABI differences" subheadings
The "ABI" doesn't really convey anything significant in
the title. These subsections are about describing differences
between the kernel and (g)libc interfaces.
Reported-by: Andries E. Brouwer <Andries.Brouwer@cwi.nl>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-05-08 11:08:00 +00:00
|
|
|
.SS C library/kernel differences
|
2014-05-16 06:07:42 +00:00
|
|
|
At the system call level, the
|
|
|
|
.BR PTRACE_PEEKTEXT ,
|
|
|
|
.BR PTRACE_PEEKDATA ,
|
|
|
|
and
|
|
|
|
.BR PTRACE_PEEKUSER
|
|
|
|
requests have a different API: they store the result
|
|
|
|
at the address specified by the
|
|
|
|
.I data
|
|
|
|
parameter, and the return value is the error flag.
|
|
|
|
The glibc wrapper function provides the API given in DESCRIPTION above,
|
|
|
|
with the result being returned via the function return value.
|
2007-05-18 16:06:42 +00:00
|
|
|
.SH BUGS
|
2007-06-21 05:38:48 +00:00
|
|
|
On hosts with 2.6 kernel headers,
|
2007-09-20 16:26:31 +00:00
|
|
|
.B PTRACE_SETOPTIONS
|
2011-09-26 17:33:04 +00:00
|
|
|
is declared with a different value than the one for 2.4.
|
|
|
|
This leads to applications compiled with 2.6 kernel
|
2007-05-18 16:06:42 +00:00
|
|
|
headers failing when run on 2.4 kernels.
|
2007-06-21 05:38:48 +00:00
|
|
|
This can be worked around by redefining
|
2007-09-20 16:26:31 +00:00
|
|
|
.B PTRACE_SETOPTIONS
|
2007-06-21 05:38:48 +00:00
|
|
|
to
|
|
|
|
.BR PTRACE_OLDSETOPTIONS ,
|
|
|
|
if that is defined.
|
2011-09-24 06:29:34 +00:00
|
|
|
.LP
|
2011-09-26 17:33:04 +00:00
|
|
|
Group-stop notifications are sent to the tracer, but not to real parent.
|
2011-09-24 06:29:34 +00:00
|
|
|
Last confirmed on 2.6.38.6.
|
|
|
|
.LP
|
2011-09-26 17:33:04 +00:00
|
|
|
If a thread group leader is traced and exits by calling
|
|
|
|
.BR _exit (2),
|
2011-10-01 05:39:39 +00:00
|
|
|
.\" Note from Denys Vlasenko:
|
|
|
|
.\" Here "exits" means any kind of death - _exit, exit_group,
|
|
|
|
.\" signal death. Signal death and exit_group cases are trivial,
|
|
|
|
.\" though: since signal death and exit_group kill all other threads
|
|
|
|
.\" too, "until all other threads exit" thing happens rather soon
|
|
|
|
.\" in these cases. Therefore, only _exit presents observably
|
|
|
|
.\" puzzling behavior to ptrace users: thread leader _exit's,
|
|
|
|
.\" but WIFEXITED isn't reported! We are trying to explain here
|
|
|
|
.\" why it is so.
|
2011-09-26 17:33:04 +00:00
|
|
|
a
|
|
|
|
.B PTRACE_EVENT_EXIT
|
|
|
|
stop will happen for it (if requested), but the subsequent
|
|
|
|
.B WIFEXITED
|
|
|
|
notification will not be delivered until all other threads exit.
|
|
|
|
As explained above, if one of other threads calls
|
|
|
|
.BR execve (2),
|
|
|
|
the death of the thread group leader will
|
|
|
|
.I never
|
|
|
|
be reported.
|
|
|
|
If the execed thread is not traced by this tracer,
|
|
|
|
the tracer will never know that
|
|
|
|
.BR execve (2)
|
2011-09-24 06:29:34 +00:00
|
|
|
happened.
|
2011-09-26 17:33:04 +00:00
|
|
|
One possible workaround is to
|
|
|
|
.B PTRACE_DETACH
|
|
|
|
the thread group leader instead of restarting it in this case.
|
|
|
|
Last confirmed on 2.6.38.6.
|
adjtimex.2, bind.2, cacheflush.2, clone.2, fallocate.2, fanotify_init.2, fanotify_mark.2, flock.2, futex.2, getdents.2, getpriority.2, getrlimit.2, gettid.2, gettimeofday.2, ioprio_set.2, kexec_load.2, migrate_pages.2, modify_ldt.2, mount.2, move_pages.2, mprotect.2, msgop.2, nfsservctl.2, perf_event_open.2, pread.2, ptrace.2, recvmmsg.2, rename.2, restart_syscall.2, sched_setattr.2, send.2, shmop.2, shutdown.2, sigaction.2, signalfd.2, syscalls.2, timer_create.2, timerfd_create.2, tkill.2, vmsplice.2, wait.2, aio_init.3, confstr.3, exit.3, fmemopen.3, fopen.3, getaddrinfo.3, getauxval.3, getspnam.3, isalpha.3, isatty.3, mallinfo.3, malloc.3, mallopt.3, psignal.3, pthread_attr_setinheritsched.3, qecvt.3, queue.3, rtnetlink.3, strerror.3, strftime.3, toupper.3, towlower.3, towupper.3, initrd.4, locale.5, proc.5, bootparam.7, capabilities.7, ddp.7, fanotify.7, icmp.7, inotify.7, ip.7, ipv6.7, netdevice.7, netlink.7, path_resolution.7, rtld-audit.7, rtnetlink.7, sched.7, signal.7, socket.7, svipc.7, tcp.7, unix.7, ld.so.8: srcfix: Update FIXMEs
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2014-08-21 21:47:44 +00:00
|
|
|
.\" FIXME . need to test/verify this scenario
|
2011-09-26 17:33:04 +00:00
|
|
|
.LP
|
|
|
|
A
|
|
|
|
.B SIGKILL
|
|
|
|
signal may still cause a
|
|
|
|
.B PTRACE_EVENT_EXIT
|
|
|
|
stop before actual signal death.
|
|
|
|
This may be changed in the future;
|
|
|
|
.B SIGKILL
|
|
|
|
is meant to always immediately kill tasks even under ptrace.
|
2015-05-12 10:43:48 +00:00
|
|
|
Last confirmed on Linux 3.13.
|
2012-03-19 18:18:20 +00:00
|
|
|
.LP
|
2012-03-19 18:29:29 +00:00
|
|
|
Some system calls return with
|
2012-03-19 18:18:20 +00:00
|
|
|
.B EINTR
|
2012-03-19 18:29:29 +00:00
|
|
|
if a signal was sent to a tracee, but delivery was suppressed by the tracer.
|
|
|
|
(This is very typical operation: it is usually
|
2012-03-19 18:18:20 +00:00
|
|
|
done by debuggers on every attach, in order to not introduce
|
2012-03-19 18:29:29 +00:00
|
|
|
a bogus
|
|
|
|
.BR SIGSTOP ).
|
|
|
|
As of Linux 3.2.9, the following system calls are affected
|
|
|
|
(this list is likely incomplete):
|
2012-03-19 18:18:20 +00:00
|
|
|
.BR epoll_wait (2),
|
2012-03-19 18:29:29 +00:00
|
|
|
and
|
2012-03-19 18:18:20 +00:00
|
|
|
.BR read (2)
|
2012-03-19 18:29:29 +00:00
|
|
|
from an
|
|
|
|
.BR inotify (7)
|
|
|
|
file descriptor.
|
2012-08-03 04:28:46 +00:00
|
|
|
The usual symptom of this bug is that when you attach to
|
|
|
|
a quiescent process with the command
|
2012-08-13 22:39:21 +00:00
|
|
|
|
2013-09-05 11:08:35 +00:00
|
|
|
strace \-p <process-ID>
|
2012-08-03 04:28:46 +00:00
|
|
|
|
|
|
|
then, instead of the usual
|
|
|
|
and expected one-line output such as
|
|
|
|
.nf
|
|
|
|
|
|
|
|
restart_syscall(<... resuming interrupted call ...>_
|
|
|
|
|
|
|
|
.fi
|
|
|
|
or
|
|
|
|
.nf
|
|
|
|
|
|
|
|
select(6, [5], NULL, [5], NULL_
|
|
|
|
|
|
|
|
.fi
|
|
|
|
('_' denotes the cursor position), you observe more than one line.
|
|
|
|
For example:
|
|
|
|
.nf
|
|
|
|
|
|
|
|
clock_gettime(CLOCK_MONOTONIC, {15370, 690928118}) = 0
|
|
|
|
epoll_wait(4,_
|
|
|
|
|
|
|
|
.fi
|
|
|
|
What is not visible here is that the process was blocked in
|
|
|
|
.BR epoll_wait (2)
|
|
|
|
before
|
|
|
|
.BR strace (1)
|
|
|
|
has attached to it.
|
|
|
|
Attaching caused
|
|
|
|
.BR epoll_wait (2)
|
eventfd.2, futex.2, mmap2.2, open.2, pciconfig_read.2, ptrace.2, reboot.2, request_key.2, sched_rr_get_interval.2, splice.2, stat.2, sync_file_range.2, syscalls.2, timer_create.2, vm86.2, pthread_attr_setscope.3, core.5, proc.5, aio.7, futex.7, netlink.7, time.7: Global fix: "userspace" ==> "user space" or "user-space"
Existing pages variously use "userspace or "user space".
But, "userspace" is not quite an English word.
So change "userspace" to "user space" or, when used
attributively, "user-space".
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2012-10-21 06:04:42 +00:00
|
|
|
to return to user space with the error
|
2012-08-03 04:28:46 +00:00
|
|
|
.BR EINTR .
|
|
|
|
In this particular case, the program reacted to
|
|
|
|
.B EINTR
|
2012-08-13 07:22:34 +00:00
|
|
|
by checking the current time, and then executing
|
2012-08-03 04:28:46 +00:00
|
|
|
.BR epoll_wait (2)
|
|
|
|
again.
|
|
|
|
(Programs which do not expect such "stray"
|
|
|
|
.BR EINTR
|
|
|
|
errors may behave in an unintended way upon an
|
|
|
|
.BR strace (1)
|
|
|
|
attach.)
|
getent.1, intro.1, time.1, _exit.2, _syscall.2, accept.2, access.2, acct.2, adjtimex.2, alarm.2, alloc_hugepages.2, arch_prctl.2, bdflush.2, bind.2, brk.2, cacheflush.2, capget.2, chdir.2, chmod.2, chown.2, chroot.2, clock_getres.2, clock_nanosleep.2, clone.2, close.2, connect.2, create_module.2, delete_module.2, dup.2, epoll_create.2, epoll_ctl.2, epoll_wait.2, eventfd.2, execve.2, exit_group.2, faccessat.2, fchmodat.2, fchownat.2, fcntl.2, flock.2, fork.2, fstatat.2, fsync.2, futex.2, futimesat.2, get_kernel_syms.2, get_robust_list.2, get_thread_area.2, getcpu.2, getdents.2, getdomainname.2, getgid.2, getgroups.2, gethostname.2, getitimer.2, getpagesize.2, getpeername.2, getpid.2, getpriority.2, getresuid.2, getrlimit.2, getrusage.2, getsid.2, getsockname.2, getsockopt.2, gettid.2, gettimeofday.2, getuid.2, getunwind.2, getxattr.2, idle.2, init_module.2, inotify_add_watch.2, inotify_init.2, inotify_rm_watch.2, intro.2, io_cancel.2, io_destroy.2, io_getevents.2, io_setup.2, io_submit.2, ioctl.2, ioctl_list.2, ioperm.2, iopl.2, ioprio_set.2, ipc.2, kcmp.2, kill.2, killpg.2, link.2, linkat.2, listen.2, listxattr.2, llseek.2, lookup_dcookie.2, lseek.2, madvise.2, migrate_pages.2, mincore.2, mkdir.2, mkdirat.2, mknod.2, mknodat.2, mlock.2, mmap.2, mmap2.2, modify_ldt.2, mount.2, move_pages.2, mprotect.2, mq_getsetattr.2, mremap.2, msgctl.2, msgget.2, msgop.2, msync.2, nanosleep.2, nfsservctl.2, nice.2, open.2, openat.2, outb.2, pause.2, pciconfig_read.2, perf_event_open.2, perfmonctl.2, personality.2, pipe.2, pivot_root.2, poll.2, posix_fadvise.2, prctl.2, pread.2, process_vm_readv.2, ptrace.2, query_module.2, quotactl.2, read.2, readahead.2, readdir.2, readlink.2, readlinkat.2, readv.2, reboot.2, recv.2, remap_file_pages.2, removexattr.2, rename.2, renameat.2, rmdir.2, rt_sigqueueinfo.2, sched_get_priority_max.2, sched_rr_get_interval.2, sched_setaffinity.2, sched_setparam.2, sched_setscheduler.2, sched_yield.2, select.2, semctl.2, semget.2, semop.2, send.2, sendfile.2, set_thread_area.2, set_tid_address.2, seteuid.2, setfsgid.2, setfsuid.2, setgid.2, setpgid.2, setresuid.2, setreuid.2, setsid.2, setuid.2, setup.2, setxattr.2, shmctl.2, shmget.2, shmop.2, shutdown.2, sigaction.2, sigaltstack.2, signal.2, signalfd.2, sigpending.2, sigprocmask.2, sigreturn.2, sigsuspend.2, sigwaitinfo.2, socket.2, socketcall.2, socketpair.2, splice.2, stat.2, statfs.2, stime.2, swapon.2, symlink.2, symlinkat.2, sync.2, sync_file_range.2, sysctl.2, sysfs.2, sysinfo.2, syslog.2, tee.2, time.2, timerfd_create.2, times.2, tkill.2, truncate.2, umask.2, umount.2, uname.2, unimplemented.2, unlink.2, unlinkat.2, uselib.2, ustat.2, utime.2, utimensat.2, vfork.2, vhangup.2, vm86.2, vmsplice.2, wait.2, wait4.2, write.2, CPU_SET.3, INFINITY.3, MB_CUR_MAX.3, MB_LEN_MAX.3, __setfpucw.3, a64l.3, abort.3, abs.3, acos.3, acosh.3, addseverity.3, adjtime.3, aio_cancel.3, aio_error.3, aio_fsync.3, aio_read.3, aio_return.3, aio_suspend.3, aio_write.3, alloca.3, argz_add.3, asin.3, asinh.3, asprintf.3, assert.3, assert_perror.3, atan.3, atan2.3, atanh.3, atexit.3, atof.3, atoi.3, backtrace.3, basename.3, bcmp.3, bcopy.3, bindresvport.3, bsd_signal.3, bsearch.3, bstring.3, btowc.3, btree.3, byteorder.3, bzero.3, cabs.3, cacos.3, cacosh.3, canonicalize_file_name.3, carg.3, casin.3, casinh.3, catan.3, catanh.3, catgets.3, catopen.3, cbrt.3, ccos.3, ccosh.3, ceil.3, cerf.3, cexp.3, cexp2.3, cfree.3, cimag.3, clearenv.3, clock.3, clock_getcpuclockid.3, clog.3, clog10.3, clog2.3, closedir.3, cmsg.3, confstr.3, conj.3, copysign.3, cos.3, cosh.3, cpow.3, cproj.3, creal.3, crypt.3, csin.3, csinh.3, csqrt.3, ctan.3, ctanh.3, ctermid.3, ctime.3, daemon.3, dbopen.3, des_crypt.3, difftime.3, dirfd.3, div.3, dl_iterate_phdr.3, dlopen.3, dprintf.3, drand48.3, drand48_r.3, dysize.3, ecvt.3, ecvt_r.3, encrypt.3, end.3, endian.3, envz_add.3, erf.3, erfc.3, err.3, errno.3, error.3, ether_aton.3, euidaccess.3, exec.3, exit.3, exp.3, exp10.3, exp2.3, expm1.3, fabs.3, fclose.3, fcloseall.3, fdim.3, fenv.3, ferror.3, fexecve.3, fflush.3, ffs.3, fgetgrent.3, fgetpwent.3, fgetwc.3, fgetws.3, finite.3, flockfile.3, floor.3, fma.3, fmax.3, fmemopen.3, fmin.3, fmod.3, fmtmsg.3, fnmatch.3, fopen.3, fpathconf.3, fpclassify.3, fpurge.3, fputwc.3, fputws.3, fread.3, frexp.3, fseek.3, fseeko.3, ftime.3, ftok.3, fts.3, ftw.3, futimes.3, fwide.3, gamma.3, gcvt.3, getaddrinfo.3, getaddrinfo_a.3, getauxval.3, getcontext.3, getcwd.3, getdate.3, getdirentries.3, getdtablesize.3, getenv.3, getfsent.3, getgrent.3, getgrent_r.3, getgrnam.3, getgrouplist.3, gethostbyname.3, gethostid.3, getipnodebyname.3, getline.3, getloadavg.3, getlogin.3, getmntent.3, getnameinfo.3, getnetent.3, getnetent_r.3, getopt.3, getpass.3, getprotoent.3, getprotoent_r.3, getpt.3, getpw.3, getpwent.3, getpwent_r.3, getpwnam.3, getrpcent.3, getrpcent_r.3, getrpcport.3, gets.3, getservent.3, getservent_r.3, getspnam.3, getttyent.3, getumask.3, getusershell.3, getutent.3, getw.3, getwchar.3, glob.3, grantpt.3, gsignal.3, hash.3, hsearch.3, hypot.3, iconv.3, iconv_close.3, iconv_open.3, ilogb.3, index.3, inet.3, inet_ntop.3, inet_pton.3, infnan.3, initgroups.3, insque.3, intro.3, isalpha.3, isatty.3, isgreater.3, iswalnum.3, iswalpha.3, iswblank.3, iswcntrl.3, iswctype.3, iswdigit.3, iswgraph.3, iswlower.3, iswprint.3, iswpunct.3, iswspace.3, iswupper.3, iswxdigit.3, j0.3, key_setsecret.3, ldexp.3, lgamma.3, lio_listio.3, localeconv.3, lockf.3, log.3, log10.3, log1p.3, log2.3, logb.3, login.3, longjmp.3, lrint.3, lround.3, lsearch.3, lseek64.3, makecontext.3, makedev.3, malloc.3, malloc_hook.3, mblen.3, mbrlen.3, mbrtowc.3, mbsinit.3, mbsnrtowcs.3, mbsrtowcs.3, mbstowcs.3, mbtowc.3, memccpy.3, memchr.3, memcmp.3, memcpy.3, memfrob.3, memmem.3, memmove.3, mempcpy.3, memset.3, mkdtemp.3, mkfifo.3, mkfifoat.3, mkstemp.3, mktemp.3, modf.3, mpool.3, mq_close.3, mq_getattr.3, mq_notify.3, mq_open.3, mq_receive.3, mq_send.3, mq_unlink.3, mtrace.3, nan.3, netlink.3, nextafter.3, nl_langinfo.3, offsetof.3, on_exit.3, opendir.3, openpty.3, perror.3, popen.3, posix_fallocate.3, posix_memalign.3, posix_openpt.3, pow.3, pow10.3, printf.3, profil.3, program_invocation_name.3, psignal.3, pthread_kill_other_threads_np.3, ptsname.3, putenv.3, putgrent.3, putpwent.3, puts.3, putwchar.3, qecvt.3, qsort.3, queue.3, raise.3, rand.3, random.3, random_r.3, rcmd.3, re_comp.3, readdir.3, realpath.3, recno.3, regex.3, remainder.3, remove.3, remquo.3, resolver.3, rewinddir.3, rexec.3, rint.3, round.3, rpc.3, rpmatch.3, rtime.3, rtnetlink.3, scalb.3, scalbln.3, scandir.3, scandirat.3, scanf.3, seekdir.3, sem_close.3, sem_destroy.3, sem_getvalue.3, sem_init.3, sem_open.3, sem_post.3, sem_unlink.3, sem_wait.3, setaliasent.3, setbuf.3, setenv.3, setjmp.3, setlocale.3, setlogmask.3, setnetgrent.3, shm_open.3, siginterrupt.3, signbit.3, significand.3, sigpause.3, sigqueue.3, sigset.3, sigsetops.3, sigvec.3, sin.3, sincos.3, sinh.3, sleep.3, sockatmark.3, sqrt.3, statvfs.3, stdarg.3, stdin.3, stdio.3, stdio_ext.3, stpcpy.3, stpncpy.3, strcasecmp.3, strcat.3, strchr.3, strcmp.3, strcoll.3, strcpy.3, strdup.3, strerror.3, strfmon.3, strfry.3, strftime.3, string.3, strlen.3, strnlen.3, strpbrk.3, strptime.3, strsep.3, strsignal.3, strspn.3, strstr.3, strtod.3, strtoimax.3, strtok.3, strtol.3, strtoul.3, strverscmp.3, strxfrm.3, swab.3, sysconf.3, syslog.3, system.3, sysv_signal.3, tan.3, tanh.3, tcgetpgrp.3, tcgetsid.3, telldir.3, tempnam.3, termios.3, tgamma.3, timegm.3, timeradd.3, tmpfile.3, tmpnam.3, toascii.3, toupper.3, towctrans.3, towlower.3, towupper.3, trunc.3, tsearch.3, ttyname.3, ttyslot.3, tzset.3, ualarm.3, ulimit.3, ungetwc.3, unlocked_stdio.3, unlockpt.3, updwtmp.3, usleep.3, wcpcpy.3, wcpncpy.3, wcrtomb.3, wcscasecmp.3, wcscat.3, wcschr.3, wcscmp.3, wcscpy.3, wcscspn.3, wcsdup.3, wcslen.3, wcsncasecmp.3, wcsncat.3, wcsncmp.3, wcsncpy.3, wcsnlen.3, wcsnrtombs.3, wcspbrk.3, wcsrchr.3, wcsrtombs.3, wcsspn.3, wcsstr.3, wcstoimax.3, wcstok.3, wcstombs.3, wcswidth.3, wctob.3, wctomb.3, wctrans.3, wctype.3, wcwidth.3, wmemchr.3, wmemcmp.3, wmemcpy.3, wmemmove.3, wmemset.3, wordexp.3, wprintf.3, xcrypt.3, xdr.3, y0.3, cciss.4, console.4, console_codes.4, console_ioctl.4, dsp56k.4, fd.4, full.4, hd.4, hpsa.4, initrd.4, intro.4, lp.4, mem.4, mouse.4, null.4, pts.4, ram.4, random.4, rtc.4, sk98lin.4, st.4, tty.4, ttyS.4, tty_ioctl.4, vcs.4, wavelan.4, acct.5, charmap.5, dir_colors.5, filesystems.5, ftpusers.5, group.5, host.conf.5, hosts.5, hosts.equiv.5, intro.5, issue.5, locale.5, motd.5, networks.5, nologin.5, nscd.conf.5, passwd.5, proc.5, protocols.5, resolv.conf.5, rpc.5, securetty.5, services.5, shells.5, termcap.5, ttytype.5, utmp.5, armscii-8.7, arp.7, ascii.7, bootparam.7, capabilities.7, charsets.7, complex.7, cp1251.7, credentials.7, ddp.7, environ.7, epoll.7, fifo.7, futex.7, glob.7, hier.7, icmp.7, inotify.7, intro.7, ip.7, ipv6.7, iso_8859-1.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-15.7, iso_8859-16.7, iso_8859-2.7, iso_8859-3.7, iso_8859-4.7, iso_8859-5.7, iso_8859-6.7, iso_8859-7.7, iso_8859-8.7, iso_8859-9.7, koi8-r.7, koi8-u.7, locale.7, mailaddr.7, man.7, mq_overview.7, netdevice.7, netlink.7, numa.7, packet.7, path_resolution.7, pipe.7, posixoptions.7, pthreads.7, pty.7, raw.7, regex.7, rtld-audit.7, rtnetlink.7, sem_overview.7, shm_overview.7, sigevent.7, signal.7, socket.7, standards.7, suffixes.7, svipc.7, tcp.7, termio.7, time.7, udp.7, udplite.7, unicode.7, unix.7, uri.7, utf-8.7, x25.7, nscd.8, sync.8, tzselect.8, zdump.8, zic.8: Global fix: remove unneeded double quotes in .SH headings
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2013-02-24 18:01:36 +00:00
|
|
|
.SH SEE ALSO
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR gdb (1),
|
|
|
|
.BR strace (1),
|
2011-09-26 17:33:04 +00:00
|
|
|
.BR clone (2),
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR execve (2),
|
|
|
|
.BR fork (2),
|
2011-09-26 17:33:04 +00:00
|
|
|
.BR gettid (2),
|
2015-10-08 10:59:06 +00:00
|
|
|
.BR prctl (2),
|
2015-01-18 06:26:17 +00:00
|
|
|
.BR seccomp (2),
|
2011-09-26 17:33:04 +00:00
|
|
|
.BR sigaction (2),
|
|
|
|
.BR tgkill (2),
|
|
|
|
.BR vfork (2),
|
|
|
|
.BR waitpid (2),
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR exec (3),
|
2011-09-26 17:33:04 +00:00
|
|
|
.BR capabilities (7),
|
|
|
|
.BR signal (7)
|