ptrace Command: Tutorial & Examples

ptrace is a powerful system call in Linux that allows one process (the tracer) to control another (the tracee). It has a wide range of uses, from implementing breakpoint debugging and syscall tracing in tools like strace and gdb, to providing a mechanism for security sandboxes.

Why is ptrace important?

Understanding ptrace is important because it is a fundamental mechanism for observing and controlling the execution of processes in Linux. It is widely used in debugging tools, system call analysis tools, and security technologies. Furthermore, knowing how to use ptrace can be very helpful in troubleshooting certain types of system issues such as system call failures and unexpected process behavior.

How does ptrace work?

ptrace works by allowing a tracer process to manipulate the execution of a tracee process. When the tracer process invokes ptrace, it specifies an action to take, which can include reading or writing the tracee's memory or registers, controlling its execution (for example, by single-stepping or continuing execution), or receiving notifications about its system calls.

Here's how you might use ptrace to start tracing a process:

#include <sys/ptrace.h>
#include <unistd.h>
#include <sys/types.h>

pid_t pid = fork();
if (pid == 0) {
    ptrace(PTRACE_TRACEME, 0, NULL, NULL);
    execl("/bin/ls", "ls", NULL);
} else {
    ptrace(PTRACE_CONT, pid, NULL, NULL);

This is a simple C program that creates a child process and uses ptrace to trace it. The child process starts by calling ptrace(PTRACE_TRACEME, 0, NULL, NULL), which tells the kernel to allow the parent process to trace it. It then replaces its image with the /bin/ls program using execl. The parent process waits for the child to stop (which it does immediately after the execl), then continues its execution with ptrace(PTRACE_CONT, pid, NULL, NULL).

Common ptrace operations and parameters

ptrace supports a variety of operations, which are specified as the first argument to the ptrace function. Some of the most commonly used ones include:

  • PTRACE_TRACEME: Used by a process to request that it be traced by its parent.
  • PTRACE_PEEKTEXT, PTRACE_PEEKDATA, PTRACE_PEEKUSER: Used to read the tracee's memory or registers.
  • PTRACE_POKETEXT, PTRACE_POKEDATA, PTRACE_POKEUSER: Used to write the tracee's memory or registers.
  • PTRACE_CONT: Used to continue the tracee's execution.
  • PTRACE_SINGLESTEP: Used to single-step the tracee's execution.

Potential problems and pitfalls with ptrace

While ptrace is a powerful tool, it can be tricky to use correctly. Here are a few common pitfalls and how to avoid them:

  1. Understanding the tracee's state: When a tracee is stopped (for example, because it hit a breakpoint or because it received a signal), it's important to understand its state before resuming it. This often involves reading its registers or inspecting its memory. Failing to do so can lead to misinterpretations of the tracee's behavior.
  2. Handling signals: Signals sent to a tracee can interfere with its normal operation or with the tracing process. It's important to handle signals correctly to prevent them from causing unexpected problems.
  3. Dealing with multi-threaded applications: Tracing multi-threaded applications with ptrace can be complex, since each thread has its own set of registers and can be scheduled independently. Special care must be taken to ensure that all threads are correctly traced and their states correctly interpreted.


While ptrace can be challenging to use, it provides a powerful mechanism for observing and controlling the execution of processes in Linux. By understanding how ptrace works and how to use it effectively, you can gain a deeper understanding of the Linux kernel and the behavior of Linux applications.

Except where otherwise noted, content on this site is licensed under a CC BY-SA 4.0 license CC BY SA