ptrace(2) with PTRACE_PEEKDATA is the traditional way to read another
process’s memory. It works. It also costs one syscall per word, requires you
to attach to the process (which stops it), and makes every poke and peek
visible in strace output like a neon sign. That is fine for interactive
debugging. For anything that needs to inspect a live process without
halting it, it is the wrong tool.
process_vm_readv(2) does the same thing in one syscall, with a
scatter-gather interface on both ends, and without touching the target’s
execution state. The process keeps running while you read its memory.
Synopsis
#include <sys/uio.h>
ssize_t process_vm_readv(pid_t pid,
const struct iovec *local_iov,
unsigned long liovcnt,
const struct iovec *remote_iov,
unsigned long riovcnt,
unsigned long flags);
ssize_t process_vm_writev(pid_t pid,
const struct iovec *local_iov,
unsigned long liovcnt,
const struct iovec *remote_iov,
unsigned long riovcnt,
unsigned long flags);
local_iov describes scatter-gather buffers in your address space. remote_iov
describes the ranges to read from in pid’s address space. flags is
reserved; pass 0. Linux 3.2+.
Minimal example: read a remote stack variable
#include <sys/uio.h>
#include <stdio.h>
int read_remote_word(pid_t pid, void *remote_addr, long *out) {
struct iovec local = { .iov_base = out, .iov_len = sizeof(long) };
struct iovec remote = { .iov_base = remote_addr, .iov_len = sizeof(long) };
ssize_t n = process_vm_readv(pid, &local, 1, &remote, 1, 0);
if (n < 0) {
perror("process_vm_readv");
return -1;
}
return 0;
}
No PTRACE_ATTACH. No SIGSTOP. The target process keeps scheduling normally.
Scatter-gather on both ends
Both sides are iovec arrays, so you can pull multiple non-contiguous remote
ranges into multiple local buffers in one call:
long heap_word, stack_word;
struct iovec local[2] = {
{ &heap_word, sizeof(long) },
{ &stack_word, sizeof(long) },
};
struct iovec remote[2] = {
{ (void *)0x55a2b3c4d000, sizeof(long) }, /* somewhere in the heap */
{ (void *)0x7ffd12340008, sizeof(long) }, /* somewhere on the stack */
};
ssize_t n = process_vm_readv(pid, local, 2, remote, 2, 0);
A single syscall, two disjoint reads from the remote address space. This is
the pattern gdb and rr use when they need to snapshot a thread’s registers
and a few heap objects simultaneously.
Permissions
The kernel applies PTRACE_MODE_ATTACH_REALCREDS checks, same as ptrace(2).
In practice: you need to be able to ptrace the target. That means same UID and
no PR_SET_DUMPABLE turned off, or CAP_SYS_PTRACE. On systems with Yama
LSM (/proc/sys/kernel/yama/ptrace_scope), scope 1 or higher restricts
cross-process reads to parent processes and processes that opted in via
prctl(PR_SET_PTRACER, ...).
cat /proc/sys/kernel/yama/ptrace_scope
0 means unrestricted (same permissions as ptrace). 1 means parent-only
without an explicit opt-in. You will get EPERM if the scope blocks you, same
as you would with ptrace.
Errors you will hit
EFAULT: a range in local_iov is not mapped in your address space. You
passed a bad buffer.
ENOMEM: a range in remote_iov is not mapped in the target’s address space.
You got a stale pointer, or the range spans a hole in the remote mapping.
EPERM: permission check failed.
ESRCH: the target is gone.
None of these are fatal to your tool; catch them, skip the range, and move on.
A partial return value (less than the sum of iov_len) means some vectors
transferred and some did not. Check the return value against what you expected.
The catch: reads are not atomic
The target process keeps running. Between your read of address A and your read
of address B, the target can modify both. If you are reading a struct where
the fields have a consistency invariant between them, you can observe a torn
state. ptrace with PTRACE_ATTACH avoids this because it stops the process;
process_vm_readv does not.
For a live profiler or a checkpoint tool where you only need a statistically consistent sample, this is acceptable. For a debugger that needs to inspect a mutex’s internal state before and after a lock, it is not. Know which one you are writing.
Why bother over /proc/pid/mem
/proc/pid/mem works. It also requires an open(2) that counts as an attach
on Yama scope >= 1, and each pread(2) is a separate syscall. For bulk
inspection, process_vm_readv with a long remote_iov is faster: one syscall,
one kernel-space walk of the remote page tables, done. For interactive tooling
where you are reading one word at a time anyway, the difference is noise.
Availability
Linux 3.2 (January 2012). No wrapper in glibc until 2.15; call syscall(2)
directly on older systems. There is no equivalent in FreeBSD or OpenBSD base;
the BSDs use ptrace with PT_IO for bulk transfers, which is semantically
similar but requires an attach.
#include <sys/syscall.h>
#ifndef SYS_process_vm_readv
#define SYS_process_vm_readv 310 /* x86_64 */
#endif
Check asm/unistd.h for your architecture if you are targeting anything other
than x86-64. The syscall number differs by arch.
