summaryrefslogtreecommitdiffstats
path: root/upstream/debian-unstable/man1/perldtrace.1
diff options
context:
space:
mode:
Diffstat (limited to 'upstream/debian-unstable/man1/perldtrace.1')
-rw-r--r--upstream/debian-unstable/man1/perldtrace.1278
1 files changed, 278 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man1/perldtrace.1 b/upstream/debian-unstable/man1/perldtrace.1
new file mode 100644
index 00000000..c8a9a52d
--- /dev/null
+++ b/upstream/debian-unstable/man1/perldtrace.1
@@ -0,0 +1,278 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds C`
+. ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+. if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. if !\nF==2 \{\
+. nr % 0
+. nr F 2
+. \}
+. \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLDTRACE 1"
+.TH PERLDTRACE 1 2024-01-12 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH NAME
+perldtrace \- Perl's support for DTrace
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 2
+\& # dtrace \-Zn \*(Aqperl::sub\-entry, perl::sub\-return { trace(copyinstr(arg0)) }\*(Aq
+\& dtrace: description \*(Aqperl::sub\-entry, perl::sub\-return \*(Aq matched 10 probes
+\&
+\& # perl \-E \*(Aqsub outer { inner(@_) } sub inner { say shift } outer("hello")\*(Aq
+\& hello
+\&
+\& (dtrace output)
+\& CPU ID FUNCTION:NAME
+\& 0 75915 Perl_pp_entersub:sub\-entry BEGIN
+\& 0 75915 Perl_pp_entersub:sub\-entry import
+\& 0 75922 Perl_pp_leavesub:sub\-return import
+\& 0 75922 Perl_pp_leavesub:sub\-return BEGIN
+\& 0 75915 Perl_pp_entersub:sub\-entry outer
+\& 0 75915 Perl_pp_entersub:sub\-entry inner
+\& 0 75922 Perl_pp_leavesub:sub\-return inner
+\& 0 75922 Perl_pp_leavesub:sub\-return outer
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+DTrace is a framework for comprehensive system\- and application-level
+tracing. Perl is a DTrace \fIprovider\fR, meaning it exposes several
+\&\fIprobes\fR for instrumentation. You can use these in conjunction
+with kernel-level probes, as well as probes from other providers
+such as MySQL, in order to diagnose software defects, or even just
+your application's bottlenecks.
+.PP
+Perl must be compiled with the \f(CW\*(C`\-Dusedtrace\*(C'\fR option in order to
+make use of the provided probes. While DTrace aims to have no
+overhead when its instrumentation is not active, Perl's support
+itself cannot uphold that guarantee, so it is built without DTrace
+probes under most systems. One notable exception is that Mac OS X
+ships a \fI/usr/bin/perl\fR with DTrace support enabled.
+.SH HISTORY
+.IX Header "HISTORY"
+.IP 5.10.1 4
+.IX Item "5.10.1"
+Perl's initial DTrace support was added, providing \f(CW\*(C`sub\-entry\*(C'\fR and
+\&\f(CW\*(C`sub\-return\*(C'\fR probes.
+.IP 5.14.0 4
+.IX Item "5.14.0"
+The \f(CW\*(C`sub\-entry\*(C'\fR and \f(CW\*(C`sub\-return\*(C'\fR probes gain a fourth argument: the
+package name of the function.
+.IP 5.16.0 4
+.IX Item "5.16.0"
+The \f(CW\*(C`phase\-change\*(C'\fR probe was added.
+.IP 5.18.0 4
+.IX Item "5.18.0"
+The \f(CW\*(C`op\-entry\*(C'\fR, \f(CW\*(C`loading\-file\*(C'\fR, and \f(CW\*(C`loaded\-file\*(C'\fR probes were added.
+.SH PROBES
+.IX Header "PROBES"
+.IP "sub\-entry(SUBNAME, FILE, LINE, PACKAGE)" 4
+.IX Item "sub-entry(SUBNAME, FILE, LINE, PACKAGE)"
+Traces the entry of any subroutine. Note that all of the variables
+refer to the subroutine that is being invoked; there is currently
+no way to get ahold of any information about the subroutine's
+\&\fIcaller\fR from a DTrace action.
+.Sp
+.Vb 4
+\& :*perl*::sub\-entry {
+\& printf("%s::%s entered at %s line %d\en",
+\& copyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg2);
+\& }
+.Ve
+.IP "sub\-return(SUBNAME, FILE, LINE, PACKAGE)" 4
+.IX Item "sub-return(SUBNAME, FILE, LINE, PACKAGE)"
+Traces the exit of any subroutine. Note that all of the variables
+refer to the subroutine that is returning; there is currently no
+way to get ahold of any information about the subroutine's \fIcaller\fR
+from a DTrace action.
+.Sp
+.Vb 4
+\& :*perl*::sub\-return {
+\& printf("%s::%s returned at %s line %d\en",
+\& copyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg2);
+\& }
+.Ve
+.IP "phase\-change(NEWPHASE, OLDPHASE)" 4
+.IX Item "phase-change(NEWPHASE, OLDPHASE)"
+Traces changes to Perl's interpreter state. You can internalize this
+as tracing changes to Perl's \f(CW\*(C`${^GLOBAL_PHASE}\*(C'\fR variable, especially
+since the values for \f(CW\*(C`NEWPHASE\*(C'\fR and \f(CW\*(C`OLDPHASE\*(C'\fR are the strings that
+\&\f(CW\*(C`${^GLOBAL_PHASE}\*(C'\fR reports.
+.Sp
+.Vb 4
+\& :*perl*::phase\-change {
+\& printf("Phase changed from %s to %s\en",
+\& copyinstr(arg1), copyinstr(arg0));
+\& }
+.Ve
+.IP op\-entry(OPNAME) 4
+.IX Item "op-entry(OPNAME)"
+Traces the execution of each opcode in the Perl runloop. This probe
+is fired before the opcode is executed. When the Perl debugger is
+enabled, the DTrace probe is fired \fIafter\fR the debugger hooks (but
+still before the opcode itself is executed).
+.Sp
+.Vb 3
+\& :*perl*::op\-entry {
+\& printf("About to execute opcode %s\en", copyinstr(arg0));
+\& }
+.Ve
+.IP loading\-file(FILENAME) 4
+.IX Item "loading-file(FILENAME)"
+Fires when Perl is about to load an individual file, whether from
+\&\f(CW\*(C`use\*(C'\fR, \f(CW\*(C`require\*(C'\fR, or \f(CW\*(C`do\*(C'\fR. This probe fires before the file is
+read from disk. The filename argument is converted to local filesystem
+paths instead of providing \f(CW\*(C`Module::Name\*(C'\fR\-style names.
+.Sp
+.Vb 3
+\& :*perl*:loading\-file {
+\& printf("About to load %s\en", copyinstr(arg0));
+\& }
+.Ve
+.IP loaded\-file(FILENAME) 4
+.IX Item "loaded-file(FILENAME)"
+Fires when Perl has successfully loaded an individual file, whether
+from \f(CW\*(C`use\*(C'\fR, \f(CW\*(C`require\*(C'\fR, or \f(CW\*(C`do\*(C'\fR. This probe fires after the file
+is read from disk and its contents evaluated. The filename argument
+is converted to local filesystem paths instead of providing
+\&\f(CW\*(C`Module::Name\*(C'\fR\-style names.
+.Sp
+.Vb 3
+\& :*perl*:loaded\-file {
+\& printf("Successfully loaded %s\en", copyinstr(arg0));
+\& }
+.Ve
+.SH EXAMPLES
+.IX Header "EXAMPLES"
+.IP "Most frequently called functions" 4
+.IX Item "Most frequently called functions"
+.Vb 1
+\& # dtrace \-qZn \*(Aqsub\-entry { @[strjoin(strjoin(copyinstr(arg3),"::"),copyinstr(arg0))] = count() } END {trunc(@, 10)}\*(Aq
+\&
+\& Class::MOP::Attribute::slots 400
+\& Try::Tiny::catch 411
+\& Try::Tiny::try 411
+\& Class::MOP::Instance::inline_slot_access 451
+\& Class::MOP::Class::Immutable::Trait:::around 472
+\& Class::MOP::Mixin::AttributeCore::has_initializer 496
+\& Class::MOP::Method::Wrapped::_\|_ANON_\|_ 544
+\& Class::MOP::Package::_package_stash 737
+\& Class::MOP::Class::initialize 1128
+\& Class::MOP::get_metaclass_by_name 1204
+.Ve
+.IP "Trace function calls" 4
+.IX Item "Trace function calls"
+.Vb 1
+\& # dtrace \-qFZn \*(Aqsub\-entry, sub\-return { trace(copyinstr(arg0)) }\*(Aq
+\&
+\& 0 \-> Perl_pp_entersub BEGIN
+\& 0 <\- Perl_pp_leavesub BEGIN
+\& 0 \-> Perl_pp_entersub BEGIN
+\& 0 \-> Perl_pp_entersub import
+\& 0 <\- Perl_pp_leavesub import
+\& 0 <\- Perl_pp_leavesub BEGIN
+\& 0 \-> Perl_pp_entersub BEGIN
+\& 0 \-> Perl_pp_entersub dress
+\& 0 <\- Perl_pp_leavesub dress
+\& 0 \-> Perl_pp_entersub dirty
+\& 0 <\- Perl_pp_leavesub dirty
+\& 0 \-> Perl_pp_entersub whiten
+\& 0 <\- Perl_pp_leavesub whiten
+\& 0 <\- Perl_dounwind BEGIN
+.Ve
+.IP "Function calls during interpreter cleanup" 4
+.IX Item "Function calls during interpreter cleanup"
+.Vb 1
+\& # dtrace \-Zn \*(Aqphase\-change /copyinstr(arg0) == "END"/ { self\->ending = 1 } sub\-entry /self\->ending/ { trace(copyinstr(arg0)) }\*(Aq
+\&
+\& CPU ID FUNCTION:NAME
+\& 1 77214 Perl_pp_entersub:sub\-entry END
+\& 1 77214 Perl_pp_entersub:sub\-entry END
+\& 1 77214 Perl_pp_entersub:sub\-entry cleanup
+\& 1 77214 Perl_pp_entersub:sub\-entry _force_writable
+\& 1 77214 Perl_pp_entersub:sub\-entry _force_writable
+.Ve
+.IP "System calls at compile time" 4
+.IX Item "System calls at compile time"
+.Vb 1
+\& # dtrace \-qZn \*(Aqphase\-change /copyinstr(arg0) == "START"/ { self\->interesting = 1 } phase\-change /copyinstr(arg0) == "RUN"/ { self\->interesting = 0 } syscall::: /self\->interesting/ { @[probefunc] = count() } END { trunc(@, 3) }\*(Aq
+\&
+\& lseek 310
+\& read 374
+\& stat64 1056
+.Ve
+.IP "Perl functions that execute the most opcodes" 4
+.IX Item "Perl functions that execute the most opcodes"
+.Vb 1
+\& # dtrace \-qZn \*(Aqsub\-entry { self\->fqn = strjoin(copyinstr(arg3), strjoin("::", copyinstr(arg0))) } op\-entry /self\->fqn != ""/ { @[self\->fqn] = count() } END { trunc(@, 3) }\*(Aq
+\&
+\& warnings::unimport 4589
+\& Exporter::Heavy::_rebuild_cache 5039
+\& Exporter::import 14578
+.Ve
+.SH REFERENCES
+.IX Header "REFERENCES"
+.IP "DTrace Dynamic Tracing Guide" 4
+.IX Item "DTrace Dynamic Tracing Guide"
+<http://dtrace.org/guide/preface.html>
+.IP "DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD" 4
+.IX Item "DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD"
+<https://www.amazon.com/DTrace\-Dynamic\-Tracing\-Solaris\-FreeBSD/dp/0132091518/>
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+.IP Devel::DTrace::Provider 4
+.IX Item "Devel::DTrace::Provider"
+This CPAN module lets you create application-level DTrace probes written in
+Perl.
+.SH AUTHORS
+.IX Header "AUTHORS"
+Shawn M Moore \f(CW\*(C`sartak@gmail.com\*(C'\fR
generated by cgit v1.2.3 (git 2.39.1) at 2024-12-03 16:40:08 +0000