diff options
Diffstat (limited to 'script/mwrap-perl')
-rw-r--r-- | script/mwrap-perl | 78 |
1 files changed, 78 insertions, 0 deletions
diff --git a/script/mwrap-perl b/script/mwrap-perl index 78e71e3..53eaa10 100644 --- a/script/mwrap-perl +++ b/script/mwrap-perl @@ -6,6 +6,10 @@ use Devel::Mwrap; my ($so) = grep(m!/Mwrap\.so\z!, @DynaLoader::dl_shared_objects); defined($so) or die 'Mwrap.so not loaded'; my $cur = $ENV{LD_PRELOAD}; +if (!@ARGV || ($ARGV[0] // '') =~ /\A(?:-h|--help)\z/) { + require Pod::Usage; + Pod::Usage::pod2usage(@ARGV ? 0 : 1); +} if (defined $cur) { my @cur = split(/[: \t]+/, $cur); if (!grep(/\A\Q$so\E\z/, @cur)) { @@ -17,3 +21,77 @@ if (defined $cur) { $ENV{LD_PRELOAD} = $so; } exec @ARGV; +__END__ +=head1 NAME + +mwrap-perl - run any command under mwrap + +=head1 SYNOPSIS + + # to trace a long-running program and access it via $DIRECTORY/$PID.sock: + MWRAP=socket_dir:$DIRECTORY mwrap-perl COMMAND + + # to trace a short-lived command and dump its output to a log: + MWRAP=dump_path:$FILENAME mwrap-perl COMMAND + +=head1 DESCRIPTION + +mwrap-perl is a command-line to automatically add Mwrap.so as an +LD_PRELOAD for any command. It will resolve malloc-family calls +to a Perl file and line number, and it can also provide a backtrace +of native (C/C++) functions for non-Perl programs. + +=head1 ENVIRONMENT + +C<MWRAP> is the only environment variable read. It contains multiple +options delimited by C<,> with names and values delimited by C<:> + +=item socket_dir:$DIRECTORY + +This launches an embedded HTTP server in each process and binds it +to C<$DIRECTORY/$PID.sock>. C<curl --unix-socket $DIRECTORY/$PID.sock> +or L<mwrap-rproxy(1p)> may be used to access various endpoints in +the HTTP server. + +=item: bt:$DEPTH + +The backtrace depth for L<backtrace(3)> in addition to the Perl +file and line number where C<$DEPTH> is a non-negative number. + +The maximum allowed value is 32, though values of 5 or less are +typically useful. Increasing this to even 2 or 3 can significantly +increase the amount of memory mwrap (and liburcu) itself uses. + +This is only useful in conjunction with C<socket_dir> + +Default: 0 + +=item dump_path:$FILENAME + +Dumps the output + + total_bytes call_count location + +In the future, dumping to a self-describing CSV will be supported + +=back + +=head1 CONTACT + +Feedback welcome via plain-text mail to L<mailto:mwrap-perl@80x24.org> + +Mail archives are hosted at L<https://80x24.org/mwrap-perl/> + +=head1 COPYRIGHT + +Copyright all contributors L<mailto:mwrap-perl@80x24.org> + +License: GPL-2.0+ L<https://www.gnu.org/licenses/gpl-2.0.txt> + +Source code is at L<https://80x24.org/mwrap-perl.git/> + +=head1 SEE ALSO + +L<mwrap-rproxy(1)>, L<Devel::Mwrap(3pm)> + +=cut |