NAME

IO::Trace - Log I/O of an arbitrary process.

SYNOPSIS

# Simple case:
use IO::Trace;
exit iotrace @ARGV;

# Advanced use:
use IO::Trace qw(iotrace);
my $exit_sort = iotrace qw[-f -v -s9000 -tt -e execve,clone,openat,close,read,write -o /tmp/sort.iotrace.log sort];
warn `wc /tmp/sort.iotrace.log`;
exit $exit_editor;

DESCRIPTION

This utility is intended to be used to record STDIN STDOUT STDERR actvity (read,write,close) of an arbitrary command which it spawns. It does not alter any packets on the streams.

The log file format is similar to Linux's strace utility but more platform-independent. So iotrace should work on Windows, MacOSX, GitBash, FreeBSD, Msys2, MinGW, Solaris, Cygwin, ChromeOS, as well as Linux.

This is implemented using IPC::Open3::open3 instead of Linux ptrace.

CAVEATS

It breaks terminal commands that rely on STDIN being a TTY because it is converted into a pipe.

It will NOT log reads and writes to other files opened during the command execution, like strace does. It only logs STDIN, STDOUT, STDERR.

SEE ALSO

strace - Based on this commandline utility, but this only works on Linux platform.

Capture::Tiny - Similar in that it can log STDOUT and STDERR, but this is difficult to capture STDIN.

IPC::Run - Almost powerful enough to handle what I needed, but it couldn't handle detecting closed streams very gracefully, and the STDIN exponential backoff heartbeat CODE grinder is too sloppy.

AUTHOR

Rob Brown, <bbb@cpan.org>

DEVELOPMENT

This module is maintained on github:

https://github.com/hookbot/IO-Trace

Report feature requests or bugs here:

https://github.com/hookbot/IO-Trace/issues

Pull requests welcome.

COPYRIGHT AND LICENSE

Copyright (C) 2025 by Rob Brown

This library is free software; you can redistribute it and/or modify it under the terms of The Artistic License 2.0.

DISCLAIMER

Use at your own risk! The author will not be liable for any damages caused by misuse of this application nor any illegal monitoring or logging of any private communications or data packets or IO streams.