Messages in this thread | | | Date | Sat, 18 Mar 2006 07:12:10 -0500 | From | Chuck Ebbert <> | Subject | Proposed additions to the ptrace(2) manpage, take 2 |
| |
This is a revised set of updates to the ptrace(2) manpage.
Comments?
DESCRIPTION PTRACE_GETSIGINFO (since Linux 2.3.99-pre6) Retrieve information about the signal that caused the stop. Copies a siginfo_t from the child to location data in the par- ent. (addr is ignored)
PTRACE_SETSIGINFO (since Linux 2.3.99-pre6) Set signal information. Copies a siginfo_t from location data in the parent to the child. This will only affect signals that would normally be delivered to the child and were caught by the tracer. It may be difficult to tell these normal signals from synthetic ones generated by ptrace() itself. (addr is ignored)
PTRACE_SETOPTIONS (since Linux 2.4.6; see BUGS for caveats) Sets ptrace options from data in the parent. data is inter- preted as a bitmask of options, which are specified by the fol- lowing flags (addr is ignored.)
PTRACE_O_TRACESYSGOOD (since Linux 2.4.6) When delivering syscall traps, set bit 7 in the signal number (i.e. deliver (SIGTRAP | 0x80) This makes it easy for the tracer to tell the difference between normal traps and those caused by a syscall. (PTRACE_O_TRACESYS- GOOD may not work on all architectures.)
PTRACE_O_TRACEFORK (since Linux 2.5.46) Stop the child at the next fork() call with SIGTRAP | PTRACE_EVENT_FORK << 8 and automatically start tracing the newly forked process, which will start with a SIGSTOP. The pid for the new process can be retrieved with PTRACE_GETEVENTMSG.
PTRACE_O_TRACEVFORK (since Linux 2.5.46) Stop the child at the next vfork() call with SIGTRAP | PTRACE_EVENT_VFORK << 8 and automatically start tracing the the newly vforked process, which will start with a SIGSTOP. The pid for the new process can be retrieved with PTRACE_GETEVENTMSG.
PTRACE_O_TRACECLONE (since Linux 2.5.46) Stop the child at the next clone() call with SIGTRAP | PTRACE_EVENT_CLONE << 8 and automatically start tracing the newly cloned process, which will start with a SIGSTOP. The pid for the new process can be retrieved with PTRACE_GETEVENTMSG. This option may not catch clone() calls in all cases. If the child calls clone() with the CLONE_VFORK flag, PTRACE_EVENT_VFORK will be delivered instead if PTRACE_O_TRACEVFORK is set; other- wise if the child calls clone() with the exit signal set to SIGCHLD, PTRACE_EVENT_FORK will be delivered if PTRACE_O_TRACEFORK is set.
PTRACE_O_TRACEEXEC (since Linux 2.5.46) Stop the child at the next exec() call with SIGTRAP | PTRACE_EVENT_EXEC << 8.
PTRACE_O_TRACEVFORKDONE (since Linux 2.5.60) Stop the child at the completion of the next vfork() call with SIGTRAP | PTRACE_EVENT_VFORK_DONE << 8.
PTRACE_O_TRACEEXIT (since Linux 2.5.60) Stop the child at exit with SIGTRAP | PTRACE_EVENT_EXIT << 8. The childs exit status can be retrieved with PTRACE_GETEVENTMSG. This stop will be done early during process exit when registers are still available, allowing the tracer to see where the exit occurred, whereas the normal exit notification is done after the process is finished exiting. Even though context is available, the tracer cannot prevent the exit from happening at this point.
PTRACE_GETEVENTMSG (since Linux 2.5.46) Retrieve a message (as an unsigned long) about the ptrace event that just happened, to the location data in the parent. For PTRACE_EVENT_EXIT this is the childs exit code. For PTRACE_EVENT_FORK, PTRACE_EVENT_VFORK and PTRACE_EVENT_CLONE this is the pid of the new process. (addr is ignored.)
PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP (since Linux 2.6.14) For PTRACE_SYSEMU, continue and stop on entry to the next syscall, which will not be executed. For PTRACE_SYSEMU_SIN- GLESTEP, do the same but also singlestep if not a syscall. This call is used by programs like User Mode Linux who want to emu- late all of the the childs syscalls. (addr and data are ignored; not supported on all architectures.)
BUGS On hosts with 2.6 kernel headers, PTRACE_SETOPTIONS is declared with a different value than the one for 2.4. This leads to applications com- piled with such headers failing when run on 2.4 host kernels.
This can be worked around by redefining PTRACE_SETOPTIONS to PTRACE_OLDSETOPTIONS, if that is defined.
ERRORS EINVAL An attempt was made to set an invalid option.
-- Chuck "Penguins don't come from next door, they come from the Antarctic!" - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
| |