PYTHON-PTRACE(1)                 python-ptrace                PYTHON-PTRACE(1)

NAME
       python-ptrace - python-ptrace Documentation No Maintenance Intended

       This project is no longer maintained and is looking for a new
       maintainer.

       python-ptrace is a debugger using ptrace (Linux, BSD and Darwin system
       call to trace processes) written in Python.

       o python-ptrace documentation

       o python-ptrace at GitHub

       o python-ptrace at the Python Cheeseshop (PyPI)

       python-ptrace is an opensource project written in Python under GNU
       GPLv2 license. It supports Python 3.6 and newer.

FEATURES

       o High level Python object API : PtraceDebugger and PtraceProcess

       o Able to control multiple processes: catch fork events on Linux

       o Read/write bytes to arbitrary address: take care of memory alignment
         and split bytes to cpu word

       o Execution step by step using ptrace_singlestep() or hardware
         interruption 3

       o Can use distorm disassembler

       o Dump registers, memory mappings, stack, etc.

       o Syscall tracer and parser (strace.py command)

       Status:

       o Supported operating systems: Linux, FreeBSD, OpenBSD

       o Supported architectures: x86, x86_64 (Linux), PPC (Linux), ARM (Linux
         EAPI)

       Missing features:

       o Symbols: it's not possible to break on a function or read a variable
         value

       o No C language support: debugger shows assembler code, not your C (C++
         or other language) code!

       o No thread support

TABLE OF CONTENTS
   Install python-ptrace
       python-ptrace supports Python 3.6 and newer.

   Linux packages

       o Debian: python-ptrace Debian package.

       o Mandriva: python-ptrace Mandriva package

       o OpenEmbedded: python-ptrace recipe

       o Arch Linux: python-ptrace Arch Linux package

       o Gentoo: dev-python/python-ptrace

       See also python-ptrace on Python Package Index (PyPI)

   Install from source
   Download tarball
       Get the latest tarball at the Python Package Index (PyPI).

   Download development version
       Download the development version using Git:

          git clone https://github.com/vstinner/python-ptrace.git

       Browse python-ptrace source code.

   Option dependency

       o distorm disassembler (optional) http://www.ragestorm.net/distorm/

   Installation
       Note: pip is strongly recommanded.

       Type as root:

          python3 setup.py install

       Or using sudo program:

          sudo python3 setup.py install

   cptrace
       For faster debug and to avoid ctypes, you can also install cptrace:
       Python binding of the ptrace() function written in C:

          python3 setup_cptrace.py install

   Run tests
   Run tests with tox
       To run all tests, just type:

          tox

       The tox project creates a clean virtual environment to run tests.

   Run tests manually
       Type:

          python3 runtests.py
          python3 test_doc.py

       It's also possible to run a specific test:

          PYTHONPATH=$PWD python3 tests/test_strace.py

   python-ptrace usage
   Hello World
       Short example attaching a running process. It gets the instruction
       pointer, executes a single step, and gets the new instruction pointer:

          import ptrace.debugger
          import signal
          import subprocess
          import sys

          def debugger_example(pid):
              debugger = ptrace.debugger.PtraceDebugger()

              print("Attach the running process %s" % pid)
              process = debugger.addProcess(pid, False)
              # process is a PtraceProcess instance
              print("IP before: %#x" % process.getInstrPointer())

              print("Execute a single step")
              process.singleStep()
              # singleStep() gives back control to the process. We have to wait
              # until the process is trapped again to retrieve the control on the
              # process.
              process.waitSignals(signal.SIGTRAP)
              print("IP after: %#x" % process.getInstrPointer())

              process.detach()
              debugger.quit()

          def main():
              args = [sys.executable, '-c', 'import time; time.sleep(60)']
              child_popen = subprocess.Popen(args)
              debugger_example(child_popen.pid)
              child_popen.kill()
              child_popen.wait()

          if __name__ == "__main__":
              main()

   API
   PtraceProcess
       The PtraceProcess class is an helper to manipulate a traced process.

       Example:

          tracer = PtraceProcess(pid)              # attach the process
          tracer.singleStep()                      # execute one instruction
          tracer.cont()                            # continue execution
          tracer.syscall()                         # break at next syscall
          tracer.detach()                          # detach process

          # Get status
          tracer.getreg('al')                      # get AL register value
          regs = tracer.getregs()                  # read all registers
          bytes = tracer.readBytes(regs.ax, 10)    # read 10 bytes
          tracer.dumpCode()                        # dump code (as assembler or hexa is the disassembler is missing)
          tracer.dumpStack()                       # dump stack (memory words around ESP)

          # Modify the process
          shellcode = '...'
          ip = tracer.getInstrPointer()            # get EIP/RIP register
          bytes = tracer.writeBytes(ip, shellcode) # write some bytes
          tracer.setreg('ebx', 0)                  # set EBX register value to zero

       Read ptrace/debugger/process.py source code to see more methods.

   Trace system calls (syscalls)
       python-ptrace can trace system calls using PTRACE_SYSCALL.

   PtraceSyscall
       ptrace.syscall module contains PtraceSyscall class: it's a parser of
       Linux syscalls similar to strace program.

       Example:

          connect(5, <sockaddr_in sin_family=AF_INET, sin_port=53, sin_addr=212.27.54.252>, 28) = 0
          open('/usr/lib/i686/cmov/libcrypto.so.0.9.8', 0, 0 <read only>) = 4
          mmap2(0xb7e87000, 81920, 3, 2066, 4, 297) = 0xb7e87000
          rt_sigaction(SIGWINCH, 0xbfb7d4a8, 0xbfb7d41c, 8) = 0

       You can get more information: result type, value address, argument
       types, and argument names.

       Examples:

          long open(const char* filename='/usr/lib/i686/cmov/libcrypto.so.0.9.8' at 0xb7efc027, int flags=0, int mode=0 <read only>) = 4
          long fstat64(unsigned long fd=4, struct stat* buf=0xbfa46e2c) = 0
          long set_robust_list(struct robust_list_head* head=0xb7be5710, size_t len_ptr=12) = 0

   strace.py
       Program strace.py is very close to strace program: display syscalls of
       a program. Example:

   Features

       o Nice output of signal: see [[signal|python-ptrace signal handling]]

       o Supports multiple processes

       o Can trace running process

       o Can display arguments name, type and address

       o Option --filename to show only syscall using file names

       o Option --socketcall to show only syscall related to network (socket
         usage)

       o Option --syscalls to list all known syscalls

   Example

          $ ./strace.py /bin/ls
          execve(/bin/ls, [['/bin/ls'],|[/* 40 vars */]]) = 756
          brk(0)                                   = 0x0805c000
          access('/etc/ld.so.nohwcap', 0)          = -2 (No such file or directory)
          mmap2(NULL, 8192, 3, 34, -1, 0)          = 0xb7f56000
          access('/etc/ld.so.preload', 4)          = -2 (No such file or directory)
          (...)
          close(1)                                 = 0
          munmap(0xb7c5c000, 4096)                 = 0
          exit_group(0)
          ---done---

   Options
       The program has many options. Example with --socketcall (display only
       network functions):

          $ ./strace.py --socketcall nc localhost 8080
          execve(/bin/nc, [['/bin/nc',|'localhost', '8080']], [[/*|40 vars */]]) = 12948
          socket(AF_FILE, SOCK_STREAM, 0)          = 3
          connect(3, <sockaddr_un sun_family=AF_FILE, sun_path=/var/run/nscd/socket>, 110) = -2 (No such file or directory)
          socket(AF_FILE, SOCK_STREAM, 0)          = 3
          connect(3, <sockaddr_un sun_family=AF_FILE, sun_path=/var/run/nscd/socket>, 110) = -2 (No such file or directory)
          socket(AF_INET, SOCK_STREAM, 6)          = 3
          setsockopt(3, SOL_SOCKET, SO_REUSEADDR, 3217455272L, 4) = 0
          connect(3, <sockaddr_in sin_family=AF_INET, sin_port=8080, sin_addr=127.0.0.1>, 16) = -111 (Connection refused)
          (...)

   gdb.py
       gdb.py is a command line debugger similar to gdb, but with fewer
       features: no symbol support, no C language support, no thread support,
       etc.

   Some commands

       o cont: continue execution

       o stepi: execute one instruction

       o step: execute one instruction, but don't enter into calls

       Type help to list all available commands.

   Features

       o print command displays value as decimal and hexadecimal, but also the
         related memory mapping (if any):

            (gdb) print $eip
            Decimal: 3086383120
            Hexadecimal: 0xb7f67810
            Address is part of mapping: 0xb7f67000-0xb7f81000 => /lib/ld-2.6.1.so (r-xp)

       o Nice output of signal: see [[signal|python-ptrace signal handling]]

       o Syscall tracer with command "sys": see python-ptrace system call
         tracer <syscall>. Short example:

            (gdb) sys
            long access(char* filename='/etc/ld.so.nohwcap' at 0xb7f7f35b, int mode=F_OK) = -2 (No such file or directory)

       o Supports multiple processes:

            (gdb) proclist
            <PtraceProcess #24187> (active)
            <PtraceProcess #24188>
            (gdb) proc
            Process ID: 24187 (parent: 24182)
            Process state: T (traced)
            Process command line: [['tests/fork_execve']
            (...)
            (gdb)|switch; proc
            Switch to <PtraceProcess #24188>
            Process ID: 24188 (parent: 24187)
            Process state: T (traced)
            Process command line: ['/bin/ls']]
            (...)

       o Allow multiple commands on the same line using ";" separator:

            (gdb) print $eax; set $ax=0xdead; print $eax
            Decimal: 0
            Hexadecimal: 0x00000000
            Set $ax to 57005
            Decimal: 57005
            Hexadecimal: 0x0000dead

       o Only written in pure Python code, so it's easy to extend

       o Expression parser supports all arithmetic operator (a+b, a/b, a<<b,
         a&b, ...), parenthesis, use of registers, etc. and pointer
         dereference (ex: print *($ebx+0xc)).

   Screenshot

          $ ./gdb.py ls
          execve(/bin/ls, [['/bin/ls'],|[/* 40 vars */]]) = 16182
          (gdb) where
          ASM 0xb7f47810: MOV EAX, ESP <==
          ASM 0xb7f47812: CALL 0xb7f47a60
          ASM 0xb7f47817: MOV EDI, EAX
          ASM 0xb7f47819: CALL 0xb7f47800
          (gdb) regs
               EBX = 0xb7f4781e
               ECX = 0x0001d2f4
               EDX = 0xb7f61ff4
               ESI = 0x00000000
               (...)
          (gdb) proc
          Process ID: 16182
          Process command line: [['/bin/ls']
          Process|environment: ['TERM=xterm', 'SHELL=/bin/bash', (...)]]
          Process working directory: /home/vstinner/prog/fusil/ptrace/trunk
          (gdb) stack
          STACK: 0xbfc58000..0xbfc6e000
          STACK -8: 0x00000000
          STACK -4: 0xb7f4781e
          STACK +0: 0x00000001
          STACK +4: 0xbfc6c6bb
          STACK +8: 0x00000000
          (gdb) maps
          MAPS: 08048000-0805b000 r-xp 00000000 08:03 2588939    /bin/ls
          MAPS: 0805b000-0805c000 rw-p 00012000 08:03 2588939    /bin/ls
          (...)
          MAPS: b7f61000-b7f63000 rw-p 00019000 08:03 1540553    /lib/ld-2.6.1.so
          MAPS: bfc58000-bfc6e000 rw-p bfc58000 00:00 0          [[stack]
          MAPS:|ffffe000-fffff000 r-xp 00000000 00:00 0          [vdso]]
          (gdb) quit
          Quit.
          Terminate <PtraceProcess pid=16182>
          Quit gdb.

   python-ptrace process events
   Process events
       All process events are based on ProcessEvent class.

       o ProcessExit: process exited with an exitcode, killed by a signal or
         exited abnormally

       o ProcessSignal: process received a signal

       o NewProcessEvent: new process created, e.g. after a fork() syscall

       Attributes:

       o All events have a "process" attribute

       o ProcessExit has "exitcode" and "signum" attributes (both can be None)

       o ProcessSignal has "signum" and "name" attributes

       For NewProcessEvent, use process.parent attribute to get the parent
       process.

       Note: ProcessSignal has a display() method to display its content. Use
       it just after receiving the message because it reads process memory to
       analyze the reasons why the signal was sent.

   Wait for any process event
       The most generic function is waitProcessEvent(): it waits for any
       process event (exit, signal or new process):

          event = debugger.waitProcessEvent()

       To wait one or more signals, use waitSignals() methods. With no
       argument, it waits for any signal. Events different than signal are
       raised as Python exception. Examples:

          signal = debugger.waitSignals()
          signal = debugger.waitSignals(SIGTRAP)
          signal = debugger.waitSignals(SIGINT, SIGTERM)

       Note: signal is a ProcessSignal object, use signal.signum to get the
       signal number.

   Wait for a specific process events
       To wait any event from a process, use waitEvent() method:

          event = process.waitEvent()

       To wait one or more signals, use waitSignals() method. With no
       argument, it waits for any signal. Other process events are raised as
       Python exception. Examples:

          signal = process.waitSignals()
          signal = process.waitSignals(SIGTRAP)
          signal = process.waitSignals(SIGINT, SIGTERM)

       Note: As debugger.waitSignals(), signal is a ProcessSignal object.

   python-ptrace signal handling
   Introduction
       PtraceSignal tries to display useful information when a signal is
       received.  Depending on the signal number, it shows different
       information.

       It uses the current instruction decoded as assembler code to understand
       why the signal is raised.

       Only Intel x86 (i386, maybe x86_64) is supported now.

       When a process receives a signal, python-ptrace tries to explain why
       the signal was emitted.

       General information (not shown for all signals, e.g. not for SIGABRT):

       o CPU instruction causing the crash

       o CPU registers related to the crash

       o Memory mappings of the memory addresses

       Categorize signals:

       o SIGFPE

         o Division by zero

       o SIGSEGV, SIGBUS

         o Invalid memory read

         o Invalid memory write

         o Stack overflow

         o Invalid memory access

       o SIGABRT

         o Program abort

       o SIGCHLD

         o Child process exit

   Examples
   Division by zero (SIGFPE)

          Signal: SIGFPE
          Division by zero
          - instruction: IDIV DWORD [[EBP-0x8]
          - register ebp=0xbfdc4a98

   Invalid memory read/write (SIGSEGV)

          Signal: SIGSEGV
          Invalid read from 0x00000008
          - instruction: MOV EAX, [EAX+0x8]]
          - mapping: 0x00000008 is not mapped in memory
          - register eax=0x00000000

          PID: 23766
          Signal: SIGSEGV
          Invalid write to 0x00000008 (size=4 bytes)
          - instruction: MOV DWORD [[EAX+0x8],|0x2a
          - mapping: 0x00000008..0x0000000b is not mapped in memory
          - register eax=0x00000000

       Given information:

       o Address of the segmentation fault

       o (if possible) Size of the invalid memory read/write

       o CPU instruction causing the crash

       o CPU registers related to the crash

       o Memory mappings of the related memory address

   Stack overflow (SIGSEGV)

          Signal: SIGSEGV
          STACK OVERFLOW! Stack pointer is in 0xbf534000-0xbfd34000 => [stack]] (rw-p)
          - instruction: MOV BYTE [[EBP-0x1004],|0x0
          - mapping: 0xbf533430 is not mapped in memory
          - register <stack ptr>=0xbf533430
          - register ebp=0xbf534448

   Child exit (SIGCHLD)

          PID: 24008
          Signal: SIGCHLD
          Child process 24009 exited normally
          Signal sent by user 1000

       Information:

       o Child process identifier

       o Child process user identifier

   Examples
       Invalid read:

          Signal: SIGSEGV
          Invalid read from 0x00000008
          - instruction: MOV EAX, [EAX+0x8]
          - mapping: (no memory mapping)
          - register eax=0x00000000

       Invalid write (MOV):

          Signal: SIGSEGV
          Invalid write to 0x00000008 (size=4 bytes)
          - instruction: MOV DWORD [EAX+0x8], 0x2a
          - mapping: (no memory mapping)
          - register eax=0x00000000

       abort():

          Signal: SIGABRT
          Program received signal SIGABRT, Aborted.

   Source code
       See:

       o ptrace/debugger/ptrace_signal.py

       o ptrace/debugger/signal_reason.py

   cptrace Python module
       Python binding for ptrace written in C.

   Example
       Dummy example:

          >>> import cptrace
          >>> cptrace.ptrace(1, 1)
          Traceback (most recent call last):
            File "<stdin>", line 1, in <module>
          ValueError: ptrace(request=1, pid=1, 0x(nil), 0x(nil)) error #1: Operation not permitted

   Authors
   Contributors

       o Anthony Gelibert <anthony.gelibert AT me.com> - fix cptrace on Apple

       o Dimitris Glynos <dimitris AT census-labs.com> - follow gdb.py
         commands

       o Jakub Wilk <jwilk AT debian.org> - fix for GNU/kFreeBSD

       o Mark Seaborn <mrs AT mythic-beasts.com> - Create -i option for strace

       o Mickael Guerin aka KAeL <mickael.guerin AT crocobox.org> - OpenBSD
         port

       o teythoon - convert all classes to new-style classes

       o

         T. Bursztyka aka Tuna <tuna AT lyua.org> - x86_64 port

       o Victor Stinner <victor.stinner AT gmail.com> - python-ptrace author
         and maintainer

   Thanks

       o procps authors (top and uptime programs)

   Changelog
   python-ptrace 0.9.9 (2024-03-13)

       o Fix arguments of pipe/pipe2 system calls for proper display in call
         format.  Patch by Jose Pereira.

       o Introduced support for three-digit minor device IDs in
         PROC_MAP_REGEX.  Patch by fab1ano.

       o Added RISCV (riscv32/riscv64) support.  Patch by Andreas Schwab and
         vimer/yuzibo.

       o Fix stray exception raised by child processes terminating with exit
         code 255.  Patch by Duane Voth/duanev.

       o Removed usage of the imp module.  Collaboration between Mario
         Haustein/hamarituc and Stephen Kitt/skitt.

   python-ptrace 0.9.8 (2021-03-17)

       o Added Arm 64bit (AArch64) support.

       o Implemented PTRACE_GETREGSET and PTRACE_SETREGSET required on AArch64
         and available on Linux.

       o Issue #66: Fix SIGTRAP|0x80 or SIGTRAP wait in syscall_state.exit
         (PTRACE_O_TRACESYSGOOD).

       o The development branch master was renamed to main.  See
         https://sfconservancy.org/news/2020/jun/23/gitbranchname/ for the
         rationale.

   python-ptrace 0.9.7 (2020-08-10)

       o Add missing module to install directives

       o Update README.rst

       o Project back in beta and maintenance

   python-ptrace 0.9.6 (2020-08-10)

       o Remove RUNNING_WINDOWS constant: python-ptrace doesn't not support
         Windows.

       o Drop Python 2.7 support. six dependency is no longer needed.

       o Add close_fds and pass_fds to createChild() function.  Patch by
         Jean-Baptiste Skutnik.

       o Enhance strace.py output for open flags and open optional parameters.
         Patch by Jean-Baptiste Skutnik.

       o Add support for PowerPC 64-bit (ppc64).  Patch by Jean-Baptiste
         Skutnik.

   python-ptrace 0.9.5 (2020-04-13)

       o Fix readProcessMappings() for device id on 3 digits. Patch by Cat
         Stevens.

       o Drop Python 2 support.

   python-ptrace 0.9.4 (2019-07-30)

       o Issue #36: Fix detaching from process object created without
         is_attached=True

       o The project now requires the six module.

       o Project moved to: https://github.com/vstinner/python-ptrace

   python-ptrace 0.9.3 (2017-09-19)

       o Issue #42: Fix test_strace.py: tolerate the openat() syscall.

   python-ptrace 0.9.2 (2017-02-12)

       o Issue #35: Fix strace.py when tracing multiple processes: use the
         correct process. Fix suggested by Daniel Trnka.

   python-ptrace 0.9.1 (2016-10-12)

       o Added tracing of processes created with the clone syscall (commonly
         known as threads).

       o gdb.py: add gcore command, dump the process memory.

       o Allow command names without absolute path.

       o Fix ptrace binding: clear errno before calling ptrace().

       o Fix PtraceSyscall.exit() for unknown error code

       o Project moved to GitHub: https://github.com/haypo/python-ptrace

       o Remove the ptrace.ctypes_errno module: use directly the
         ctypes.get_errno() function

       o Remove the ptrace.ctypes_errno module: use directly ctypes.c_int8,
         ctypes.c_uint32, ... types

   python-ptrace 0.9 (2016-04-23)

       o Add all Linux syscall prototypes

       o Add error symbols (e.g. ENOENT), in addition to error text, for
         strace

       o Fix open mode so O_RDONLY shows if it's the only file access mode

       o Python 3: fix formatting of string syscall arguments (ex: filenames),
         decode bytes from the locale encoding

       o Issue #17: syscall parser now supports O_CLOEXEC and SOCK_CLOEXEC,
         fix unit tests on Python 3.4 and newer

   python-ptrace 0.8.1 (2014-10-30)

       o Update MANIFEST.in to include all files

       o Fix to support Python 3.5

   python-ptrace 0.8 (2014-10-05)

       o Issue #9: Rewrite waitProcessEvent() and waitSignals() methods of
         PtraceProcess to not call waitpid() with pid=-1. There is a race
         condition with waitpid(-1) and fork, the status of the child process
         may be returned before the debugger is noticed of the creation of the
         new child process.

       o Issue #10: Fix PtraceProcess.readBytes() for processes not created by
         the debugger (ex: fork) if the kernel blocks access to private
         mappings of /proc/pid/mem. Fallback to PTRACE_PEEKTEXT which is
         slower but a debugger tracing the process is always allowed to use
         it.

   python-ptrace 0.7 (2013-03-05)

       o Experimental support of Python 3.3 in the same code base

       o Drop support of Python 2.5

       o Remove the ptrace.compatibility module

       o Fix Process.readStruct() and Process.readArray() on x86_64

       o Experimental support of ARM architecture (Linux EAPI), strace.py has
         been tested on Raspberry Pi (armv6l)

   python-ptrace 0.6.6 (2013-12-16)

       o Fix os_tools.RUNNING_LINUX for Python 2.x compiled on Linux kernel
         3.x

       o Support FreeBSD on x86_64

       o Add missing prototype of the unlinkat() system call. Patch written by
         Matthew Fernandez.

   python-ptrace 0.6.5 (2013-06-06)

       o syscall: fix parsing socketcall on Linux x86

       o syscall: fix prototype of socket()

   python-ptrace 0.6.4 (2012-02-26)

       o Convert all classes to new-style classes, patch written by teythoon

       o Fix compilation on Apple, patch written by Anthony Gelibert

       o Support GNU/kFreeBSD, patch written by Jakub Wilk

       o Support sockaddr_in6 (IPv6 address)

   python-ptrace 0.6.3 (2011-02-16)

       o Support distrom3

       o Support Python 3

       o Rename strace.py option --socketcall to --socket, and fix this option
         for FreeBSD and Linux/64 bits

       o Add MANIFEST.in: include all files in source distribution (tests,
         cptrace module, ...)

   python-ptrace 0.6.2 (2009-11-09)

       o Fix 64 bits sub registers (set mask for eax, ebx, ecx, edx)

   python-ptrace 0.6.1 (2009-11-07)

       o Create follow, showfollow, resetfollow, xray commands in gdb.py.
         Patch written by Dimitris Glynos

       o Project website moved to: http://bitbucket.org/haypo/python-ptrace/

       o Replace types (u)intXX_t by c_(u)intXX

       o Create MemoryMapping.search() method and MemoryMapping now keeps a
         weak reference to the process

   python-ptrace 0.6 (2009-02-13)
       User visible changes:

       o python-ptrace now depends on Python 2.5

       o Invalid memory access: add fault address in the name

       o Update Python 3.0 conversion patch

       o Create -i (--show-ip) option to strace.py: show instruction pointer

       o Add a new example (itrace.py) written by Mark Seaborn and based on
         strace.py

       API changes:

       o PtraceSyscall: store the instruction pointer at syscall enter (if the
         option instr_pointer=True, disabled by default)

       o Remove PROC_DIRNAME and procFilename() from ptrace.linux_proc

       Bugfixes:

       o Fix locateProgram() for relative path

       o Fix interpretation of memory fault on MOSVW instruction (source is
         ESI and destination is EDI, and not the inverse!)

   python-ptrace 0.5 (2008-09-13)
       Visible changes:

       o Write an example (the most simple debugger) and begin to document the
         code

       o gdb.py: create "dbginfo" command

       o Parse socket syscalls on FreeBSD

       o On invalid memory access (SIGSEGV), eval the dereference expression
         to get the fault address on OS without siginfo (e.g. FreeBSD)

       o Fixes to get minimal Windows support: fix imports, fix
         locateProgram()

       Other changes:

       o Break the API: - Rename PtraceDebugger.traceSysgood() to
         PtraceDebugger.enableSysgood() - Rename PtraceDebugger.trace_sysgood
         to PtraceDebugger.use_sysgood - Remove PtraceProcess.readCode()

       o Create createChild() function which close all files except stdin,
         stdout and stderr

       o On FreeBSD, on process exit recalls waitpid(pid) to avoid zombi
         process

   python-ptrace 0.4.2 (2008-08-28)

       o BUGFIX: Fix typo in gdb.py (commands => command_str), it wasn't
         possible to write more than one command...

       o BUGFIX: Fix typo in SignalInfo class (remove "self."). When a process
         received a signal SIGCHLD (because of a fork), the debugger exited
         because of this bug.

       o BUGFIX: Debugger._wait() return abnormal process exit as a normal
         event, the event is not raised as an exception

       o PtraceSignal: don't clear preformatted arguments (e.g. arguments of
         execve)

   python-ptrace 0.4.1 (2008-08-23)

       o The project has a new dedicated website:
         http://python-ptrace.hachoir.org/

       o Create cptrace: optional Python binding of ptrace written in C
         (faster than ptrace, the Python binding written in Python with
         ctypes)

       o Add name attribute to SignalInfo classes

       o Fixes to help Python 3.0 compatibility: don't use sys.exc_clear()
         (was useless) in writeBacktrace()

       o ProcessState: create utime, stime, starttime attributes

   python-ptrace 0.4.0 (2008-08-19)
       Visible changes:

       o Rename the project to "python-ptrace" (old name was "Ptrace)

       o strace.py: create --ignore-regex option

       o PtraceSignal: support SIGBUS, display the related registers and the
         instruction

       o Support execve() syscall tracing

       Developer changes:

       o New API is incompatible with 0.3.2

       o PtraceProcess.waitProcessEvent() accepts optional blocking=False
         argument

       o PtraceProcess.getreg()/setreg() are able to read/write i386 and
         x86-64 "sub-registers" like al or bx

       o Remove iterProc() function, replaced by openProc() with explicit call
         to .close() to make sure that files are closed

       o Create searchProcessesByName()

       o Replace CPU_PPC constant by CPU_POWERPC and create CPU_PPC32 and
         CPU_PPC64

       o Create MemoryMapping object, used by readMappings() and findStack()
         methods of PtraceProcess

       o Always define all PtraceProcess methods but raise an error if the
         function is not implemented

   TODO
   Main tasks

       o Fix strace.py --socketcall: SyscallState.enter() calls
         ignore_callback before socketcall are proceed

       o Support other backends:

            o GDB MI: http://code.google.com/p/pygdb/

            o ktrace: (FreeBSD and Darwin): would help Darwin support

            o utrace (new Linux debugger):
              http://sourceware.org/systemtap/wiki/utrace

            o vtrace?

            o PyDBG: works on Windows

       o Backtrace symbols:

         o GNU BFD?

         o elfsh?

         o addr2line program?

         o See dl_iterate_phdr() function of libdl

       o Support other disassemblers (than distorm), and so both Intel syntax
         (Intel and AT&T)

         o BFD

         o http://www.ragestorm.net/distorm/

         o libasm (ERESI)

         o libdisasm (bastard)

         o http://www.woodmann.com/collaborative/tools/index.php/Category:X86_Disassembler_Libraries

       o Support threads: other backends (than python-ptrace) already support
         threads

   Minor tasks

       o Fix gdb.py "step" command on a jump. Example where step will never
         stop:

            (gdb) where
            ASM 0xb7e3b917: JMP 0xb7e3b8c4 (eb ab)
            ASM 0xb7e3b919: LEA ESI, [ESI+0x0] (8db426 00000000)

       o Remove gdb.py "except PtraceError, err: if err.errno == ESRCH" hack,
         process death detection should be done by PtraceProcess or
         PtraceDebugger

       o Use Intel hardware breakpoints: set vtrace source code

       o Support Darwin:

         o ktrace? need to recompile Darwin kernel with KTRACE option

         o get registers:
           http://unixjunkie.blogspot.com/2006/01/darwin-ptrace-and-registers.html

         o PT_DENY_ATTACH: http://steike.com/code/debugging-itunes-with-gdb/

         o PT_DENY_ATTACH:
           http://landonf.bikemonkey.org/code/macosx/ptrace_deny_attach.20041010201303.11809.mojo.html

LINKS
   Project using python-ptrace

       o Fusil the fuzzer

   python-ptrace announces

       o fuzzing mailing list

       o reverse-engineering.net

   ptrace usage

       o Sandboxing: Plash

   Similar projects

       o vtrace: Python library (Windows and Linux) supporting threads

       o subterfuge by Mike Coleman: Python library (Linux): contains Python
         binding of ptrace written in C for Python 2.1/2.2. It doesn't work
         with Python 2.5 (old project, not maintained since 2002)

       o strace program (Linux, BSD)

       o ltrace program (Linux)

       o truss program (Solaris and BSD)

       o pytstop by Philippe Biondi: debugger similar to gdb but in very alpha
         stage (e.g. no disassembler), using ptrace Python binding written in
         C (from subterfuge)

       o strace.py by Philippe Biondi

       o Fenris: suite of tools suitable for code analysis, debugging,
         protocol analysis, reverse engineering, forensics, diagnostics,
         security audits, vulnerability research

       o PyDBG: Windows debugger written in pure Python

   Interesting articles

       o (fr) Surveiller les connexions avec auditd (2007)

       o Playing with ptrace() for fun and profit (2006)

       o PTRACE_SETOPTIONS tests (2005)

       o Process Tracing Using Ptrace (2002)

AUTHOR
       Victor Stinner

COPYRIGHT
       2024, Victor Stinner

0.9.9                           April 27, 2024                PYTHON-PTRACE(1)