src/ocaml/ptrace_easy.mli

(** Higher-level wrapper over {!Ptrace} that hides syscall enter/exit pairing, path translation, and per-process bookkeeping (cwd and fd tables). Consumers receive a flat stream of filesystem-relevant events with paths already resolved against the tracee's cwd or directory file descriptors. Paths are absolute and lexically normalized; canonicalization through {!Unix.realpath} remains the consumer's responsibility. Syscalls that only update fd or cwd state ([close], [dup], [dup2], [dup3], [fcntl] with [F_DUPFD] or [F_DUPFD_CLOEXEC], [chdir], [fchdir]) are handled internally and do not produce events. *) type pid = int (** Decoded intent of an open-family syscall. *) type open_intent = { read : bool; write : bool; directory_only : bool; } (** Filesystem-relevant events emitted to the consumer. {b Pre_*} variants fire on syscall entry, before the kernel acts. The filesystem is still in its pre-syscall state, so a consumer can stat the referenced path to capture original metadata. {b Post_*} variants fire on syscall exit and carry the success flag. Read-only or non-destructive operations ([Stat_like], [Read_dir], [Make_dir], [Truncate]) emit a single event at exit. *) type event = | Pre_open of { pid : pid; path : string; intent : open_intent } | Post_open of { pid : pid; path : string; intent : open_intent; ok : bool } | Pre_unlink of { pid : pid; path : string } | Post_unlink of { pid : pid; path : string; ok : bool } | Pre_rename of { pid : pid; src : string; dst : string } | Post_rename of { pid : pid; src : string; dst : string; ok : bool } (** [stat], [lstat], [newfstatat], [access], [faccessat], [faccessat2], [readlink], [readlinkat]. Emitted regardless of success. *) | Stat_like of { pid : pid; path : string } (** [getdents] or [getdents64] on a successfully resolved fd. *) | Read_dir of { pid : pid; path : string } (** [mkdir] or [mkdirat] on success. *) | Make_dir of { pid : pid; path : string } (** [truncate] (path) or [ftruncate] (resolved fd) on success. *) | Truncate of { pid : pid; path : string } | Fork of { parent : pid; child : pid } | Process_exit of pid (** [trace command on_event] runs [command] under ptrace and invokes [on_event] for each event in the order they occur. Raises [Invalid_argument] for an empty command and may raise {!Unix.Unix_error} for ptrace, wait, fork, or exec failures. *) val trace : string list -> (event -> unit) -> unit