diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/.gitignore | 2 | ||||
| -rw-r--r-- | Documentation/GNUmakefile | 63 | ||||
| -rw-r--r-- | Documentation/mwrap.pod | 123 |
3 files changed, 188 insertions, 0 deletions
diff --git a/Documentation/.gitignore b/Documentation/.gitignore new file mode 100644 index 0000000..1b0e502 --- /dev/null +++ b/Documentation/.gitignore @@ -0,0 +1,2 @@ +mwrap.txt +mwrap.1 diff --git a/Documentation/GNUmakefile b/Documentation/GNUmakefile new file mode 100644 index 0000000..14480da --- /dev/null +++ b/Documentation/GNUmakefile @@ -0,0 +1,63 @@ +# Copyright (C) all contributors <mwrap-public@80x24.org> +# License: GPL-3.0+ <https://www.gnu.org/licenses/gpl-3.0.txt> +all:: + +INSTALL = install +POD2MAN = pod2man +VERSION := $(shell cd .. && ./VERSION-GEN) +release := mwrap $(VERSION) +POD2MAN_OPTS = -v -r '$(release)' --stderr -d 1993-10-02 -c 'mwrap user manual' +pod2man = $(POD2MAN) $(POD2MAN_OPTS) +POD2TEXT = pod2text +POD2TEXT_OPTS = --stderr +pod2text = $(POD2TEXT) $(POD2TEXT_OPTS) + +m1 = mwrap +m5 = +m7 = + +man1 := $(addsuffix .1, $(m1)) +man5 := $(addsuffix .5, $(m5)) +man7 := $(addsuffix .7, $(m7)) + +all:: man + +man: $(man1) $(man5) $(man7) + +prefix ?= $(HOME) +mandir ?= $(prefix)/share/man +man1dir = $(mandir)/man1 +man5dir = $(mandir)/man5 +man7dir = $(mandir)/man7 + +gem-man: man + $(INSTALL) -d -m 755 ../man + test -z "$(man1)" || $(INSTALL) -m 644 $(man1) ../man + test -z "$(man5)" || $(INSTALL) -m 644 $(man5) ../man + test -z "$(man7)" || $(INSTALL) -m 644 $(man7) ../man + +install-man: man + $(INSTALL) -d -m 755 $(DESTDIR)$(man1dir) + $(INSTALL) -d -m 755 $(DESTDIR)$(man5dir) + test -z "$(man7)" || $(INSTALL) -d -m 755 $(DESTDIR)$(man7dir) + $(INSTALL) -m 644 $(man1) $(DESTDIR)$(man1dir) + $(INSTALL) -m 644 $(man5) $(DESTDIR)$(man5dir) + test -z "$(man7)" || $(INSTALL) -m 644 $(man7) $(DESTDIR)$(man7dir) + +%.1 %.5 %.7 : %.pod + $(pod2man) -s $(subst .,,$(suffix $@)) $< $@+ && mv $@+ $@ + +mantxt = $(addsuffix .txt, $(m1) $(m5) $(m7)) + +txt :: $(mantxt) + +all :: txt + +%.txt : %.pod + $(pod2text) $< $@+ + touch -r $< $@+ + mv $@+ $@ + +clean:: + $(RM) $(man1) $(man5) $(man7) + $(RM) $(addsuffix .txt.gz, $(m1) $(m5) $(m7)) diff --git a/Documentation/mwrap.pod b/Documentation/mwrap.pod new file mode 100644 index 0000000..6832430 --- /dev/null +++ b/Documentation/mwrap.pod @@ -0,0 +1,123 @@ +=head1 NAME + +mwrap - 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 COMMAND + + # to trace a short-lived command and dump its output to a log: + MWRAP=dump_path:$FILENAME mwrap COMMAND + +=head1 DESCRIPTION + +mwrap is a command-line to automatically add mwrap.so as an +LD_PRELOAD for any command. It will resolve malloc-family calls +to a Ruby file and line number, and it can also provide a backtrace +of native (C/C++) functions for non-Ruby 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> +or L<mwrap-rproxy(1p)> (from L<https://80x24.org/mwrap-perl.git>) 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-public@80x24.org> + +Mail archives are hosted at L<https://80x24.org/mwrap-public/> + +=head1 COPYRIGHT + +Copyright all contributors L<mailto:mwrap-public@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.git/> + +=head1 SEE ALSO + +L<mwrap-rproxy(1)>, L<Devel::Mwrap(3pm)>, L<https://80x24.org/mwrap-perl.git> + +=cut |