1 files changed, 147 insertions, 0 deletions
diff --git a/script/mwrap-perl b/script/mwrap-perl
new file mode 100644
index 0000000..182b0bd
--- /dev/null
+++ b/script/mwrap-perl
@@ -0,0 +1,147 @@
+#!/usr/bin/perl -w
+# Copyright (C) mwrap hackers <mwrap-perl@80x24.org>
+# License: GPL-3.0+ <https://www.gnu.org/licenses/gpl-3.0.txt>
+use v5.12;
+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)) {
+                # drop old redundant versions
+                my @keep = grep(!m!/Mwrap\.so$!, @cur);
+                $ENV{LD_PRELOAD} = join(':', $so, @keep);
+        }
+} else {
+        $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 $DIR/$PID.sock:
+  MWRAP=socket_dir:$DIR 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<:>
+
+=over 4
+
+=item socket_dir:$DIR
+
+This launches an embedded HTTP server in each process and binds it
+to C<$DIR/$PID.sock>.  C<curl --unix-socket $DIR/$PID.sock http://0/$PID/>
+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>
+
+This may be changed via POST request (see below).
+
+Default: 0
+
+=item dump_path:$FILENAME
+
+Dumps the output at exit to a given filename:
+
+        total_bytes        call_count        location
+
+In the future, dumping to a self-describing CSV will be supported.
+
+=item dump_fd:$DESCRIPTOR
+
+As with dump_path, but dumps the output to a given file descriptor.
+
+=back
+
+=head1 HTTP POST API
+
+In addition to the various GET endpoints linked via C<http://0/$PID/>,
+there are some POST endpoints which are typically accessed via
+C<curl --unix-socket $DIR/$PID.sock>
+
+=over 4
+
+=item POST http://0/$PID/reset
+
+C<curl --unix-socket $DIR/$PID.sock -XPOST http://0/$PID/reset>
+
+Reset all internal counters.  This is not done atomically and does
+not release any memory.
+
+=item POST http://0/$PID/trim
+
+C<curl --unix-socket $DIR/$PID.sock -XPOST http://0/$PID/trim>
+
+Runs L<malloc_trim(3)> with a 0 pad value to release unused memory
+back to the kernel.  In our malloc implementation, this is done
+lazily to avoid contention and does not happen unless sleeping threads.
+
+=item POST http://0/$PID/ctl
+
+Set various internal knobs.  Currently, C<X-Mwrap-BT> is the
+only knob supported:
+
+C<curl --unix-socket $DIR/$PID.sock -XPOST -HX-Mwrap-BT:1 http://0/$PID/ctl>
+
+Using the C<X-Mwrap-BT> header allows changing the aforementioned
+C<bt:> value to a specified depth level.  As with C<bt:>, only make small
+adjustments as the memory cost can increase exponentially with each step.
+
+It is typically a good idea to reset (C<http://0/$PID/reset>) after changing
+the depth on a running process.
+
+Headers other than C<X-Mwrap-BT> may be accepted in the future to
+tweak other settings.
+
+=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-3.0+ L<https://www.gnu.org/licenses/gpl-3.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