NAME
ptrace – interface for the process trace device

SYNOPSIS
#include <u.h>
#include <libc.h>
#include <ptrace.h>
typedef enum {
CHANEND,
CHANSND,
CHANRCV,
CHANNOP,
CHANNOBLK,
} ChanOp;
typedef enum PTevent {
SAdmit = 0,      /* Edf admit */
SRelease,        /* Edf release, waiting to be scheduled */
SEdf,           /* running under EDF */
SRun,           /* running best effort */
SReady,          /* runnable but not running    */
SSleep,          /* blocked */
SYield,          /* blocked waiting for release */
SSlice,          /* slice exhausted */
SDeadline,       /* proc's deadline */
SExpel,          /* Edf expel */
SDead,          /* proc dies */
SInts,          /* Interrupt start */
SInte,          /* Interrupt end */
STrap,          /* fault */
SUser,          /* user event */
SName,          /* used to report names for pids */
Nevent,
} Tevent;
enum {
PTsize = 4 + 4 + 4 + 8 + 8,
/* STrap arg flags */
STrapRPF = 0x1000000000000000ULL,    /* page fault (read) STrap arg */
STrapWPF = 0x1000000000000000ULL,    /* page fault (write) STrap arg */
STrapSC    = 0x2000000000000000ULL,    /* sys call STrap arg */
STrapMask = 0x0FFFFFFFFFFFFFFFULL, /* bits available in arg */
};
typedef struct PTraceevent      PTraceevent;
struct PTraceevent {
u32int      pid; /* for the process */
u32int      etype;      /* Event type */
u32int      machno;     /* where the event happen */
vlong       time;       /* time stamp    */
u64int      arg; /* for this event type */
};

DESCRIPTION
This include file documents the format of the ptrace(3) device. The device reports trace events for processes with the fields documented in the PTraceevent structure. Events are read using little endian format for all values. The type of event is one of those in PTevent.

Traps report also system calls made. They have set in the arg field the STrapRPF or STrapWPF bit if they correspond to a read or write page fault, and the STrapSC bit if they correspond to a system call (OR'ed with the system call number). For page faults, the STrapMask bits are set to the faulting address using the endianness of the faulting system. Otherwise the argument is the trap number.

The SName event uses the space of the argument to store up to 8 characters with the process name for the pid reported in the event.

The SSleep state reports as its argument both the scheduling state for the sleep (in the low byte) and the program counter for the kernel (upper bytes, shifted).

SOURCE
/sys/src/9/port/devptrace.c

SEE ALSO
ptrace(3), ptrace(1).
Copyright © 2025 Plan 9 Foundation. All rights reserved.