.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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 "Net::SIP::Debug 3pm"
.TH Net::SIP::Debug 3pm "2021-03-01" "perl v5.32.1" "User Contributed Perl Documentation"
.\" 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"
Net::SIP::Debug \- debugging of Net::SIP
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  use Net::SIP::Debug \*(Aq1\*(Aq;
\&  use Net::SIP::Debug qw( Net::SIP*=0 Registrar=1 );
\&  Net::SIP::Debug\->level(1);
\&
\&  perl \-MNet::SIP::Debug=1 app.pl
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Provides debugging support for Net::SIP.
Debugging can be enabled/disabled globally or per package
and optional per subpackage.
.PP
It provides support for different debugging levels, e.g.
the higher the level, the more debugging is done.
The following levels are used:
.IP "\(bu" 4
1 \- Debug messages for users.
.IP "\(bu" 4
2 \- Includes short \s-1SIP\s0 packet dumps of incoming and outgoing data.
.IP "\(bu" 4
5 \- Includes detailed \s-1SIP\s0 packet dumps for incoming and outgoing data.
.IP "\(bu" 4
10 \- Includes information about call flow, e.g. why packets get dropped etc.
.IP "\(bu" 4
50 \- Detailed debugging for programmers using Net::SIP.
.IP "\(bu" 4
100 \- Detailed debugging for core developers of Net::SIP.
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.ie n .IP "import ( @ARGS )" 4
.el .IP "import ( \f(CW@ARGS\fR )" 4
.IX Item "import ( @ARGS )"
Extracts everything from arguments given to \f(CW\*(C`use\*(C'\fR which might
be usable by \fBlevel\fR and forwards rest to Exporter.
.Sp
If the argument is a reference to a subroutine it will be used
for showing the debug message instead of printing it to \s-1STDERR.\s0
In this case the usual prefixes incl the time will not be added
(useful for forwarding debug to syslog).
.ie n .IP "level ( @ARGS )" 4
.el .IP "level ( \f(CW@ARGS\fR )" 4
.IX Item "level ( @ARGS )"
Enables/disables debugging depending on \f(CW@ARGS\fR. \f(CW@ARGS\fR might
contain the following specifications:
.RS 4
.IP "\s-1NUMBER\s0" 8
.IX Item "NUMBER"
\&\s-1NUMBER\s0 will be interpreted as the debugging level.
It's used in \fBdebug\fR etc to print only debug message which a
level lower or equal to \s-1NUMBER.\s0
.IP "\s-1PACKAGE\s0" 8
.IX Item "PACKAGE"
Enables debugging for package \s-1PACKAGE. PACKAGE\s0 might be a fully
qualified package (e.g. \f(CW\*(C`Net::SIP::Registrar\*(C'\fR) or the \f(CW\*(C`Net\*(C'\fR
or \f(CW\*(C`Net::SIP\*(C'\fR might be omitted (\f(CW\*(C`Registrar\*(C'\fR). If a \f(CW\*(C`*\*(C'\fR is added
the debugging will also be enabled for subpackages, e.g.
\&\f(CW\*(C`Endpoint*\*(C'\fR will enable debugging for Net::SIP::Endpoint and
Net::SIP::Endpoint::Context too.
.IP "PACKAGE=NUMBER" 8
.IX Item "PACKAGE=NUMBER"
Similar to the previous item, but this sets debugging level to
\&\s-1NUMBER\s0 for the specified packages and thus can also be used to
selectively disable debugging for some packages.
.RE
.RS 4
.Sp
If \f(CW@ARGS\fR is empty it will return the debugging level for the package
which called this method (the first package in the caller stack
which is not Net::SIP::Debug itself).
.RE
.IP "set_prefix ( \s-1PREFIX\s0 )" 4
.IX Item "set_prefix ( PREFIX )"
Sets prefix used for debug messages to \s-1PREFIX.\s0 Default prefix
is '\s-1DEBUG:\s0' but for instance for forking applications it might
be useful to change this to \*(L"\s-1DEBUG\s0($$):\*(R" or similar.
.SH "SUBROUTINES"
.IX Header "SUBROUTINES"
.IP "DEBUG|debug ( [ \s-1LEVEL\s0 ],( \s-1MESSAGE\s0 | \s-1FMT\s0,@ARG ))" 4
.IX Item "DEBUG|debug ( [ LEVEL ],( MESSAGE | FMT,@ARG ))"
If debugging is enabled it will print debugging info to \s-1STDERR.\s0
If multiple arguments are given to the function they will be
fed into \fBsprintf\fR to create a single message.
.Sp
If the first argument looks like a number (see \fBlooks_like_number\fR
in Scalar::Util) it will be interpreted as the debug level
for this message, e.g. if it is higher than the user specified
debug level the message will not be printed.
.Sp
The \s-1MESSAGE\s0 (or the result from \f(CW\*(C`sprintf(FMT,@ARG)\*(C'\fR) will be
prefixed by the caller package, the caller function and the line
from which \s-1DEBUG\s0 was called. In front of the prefix the current time
(as float time_t) and the string \*(L"\s-1DEBUG:\*(R"\s0 will be added.
.Sp
If the message consists of multiple lines each line will be prefixed
by the prefix and all but the first line will also have a \s-1TAB\s0 added
between prefix and message data.
.Sp
The function is by default exported as \fB\s-1DEBUG\s0\fR and can by exported
as \fBdebug\fR too.
.ie n .IP "\s-1DEBUG_DUMP\s0 ( [ \s-1LEVEL\s0 ], @DATA )" 4
.el .IP "\s-1DEBUG_DUMP\s0 ( [ \s-1LEVEL\s0 ], \f(CW@DATA\fR )" 4
.IX Item "DEBUG_DUMP ( [ LEVEL ], @DATA )"
Will call \fBdebug\fR with the output from Data::Dumpers \fBDumper\fR
if debugging is enabled. If \f(CW@DATA\fR has more than one item it will
be fed as reference into \fBDumper\fR, otherwise only the single item
will be fed to \fBDumper\fR.
For the meaning of \s-1LEVEL\s0 see \fBdebug\fR.
.Sp
This function is exported by default.
.IP "stacktrace ( \s-1MESSAGE\s0 | \s-1FMT\s0,@ARG )" 4
.IX Item "stacktrace ( MESSAGE | FMT,@ARG )"
Uses the arguments in \fBdebug\fR, but instead of writing a debug
message to \s-1STDERR\s0 it will be used in Carp::longmess.
Returns string with stacktrace.
.IP "\s-1LEAK_TRACK\s0 ( \s-1REF\s0 )" 4
.IX Item "LEAK_TRACK ( REF )"
This is used internally for tracking leaks. It will rebless \s-1REF\s0 into
a new class which behaves like the old one. Calls of \s-1LEAK_TRACK\s0
and \s-1DESTROY\s0 on this class will be tracked and shown. If Devel::Peek
can be loaded it will \fBDump\fR information about the \s-1REF\s0 on each
call to \s-1LEAK_TRACK.\s0
.Sp
Exported by default.
.SH "exported Variables"
.IX Header "exported Variables"
.ie n .IP "$DEBUG" 4
.el .IP "\f(CW$DEBUG\fR" 4
.IX Item "$DEBUG"
This variable is set to false if all kind of debugging is disabled.
This variable is exported by default. It should not be changed.
It is intended to be used as a quick check to save expensive calls of debugging
functions if no debugging will be used anyway, i.e.:
.Sp
.Vb 1
\&    $DEBUG && DEBUG(...)
.Ve