.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" 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
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "Log::Report::Dispatcher::Syslog 3"
.TH Log::Report::Dispatcher::Syslog 3 2025-12-12 "perl v5.42.0" "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
Log::Report::Dispatcher::Syslog \- send messages to syslog
.SH INHERITANCE
.IX Header "INHERITANCE"
.Vb 2
\& Log::Report::Dispatcher::Syslog
\&   is a Log::Report::Dispatcher
.Ve
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 4
\&  # add syslog dispatcher
\&  dispatcher SYSLOG => \*(Aqsyslog\*(Aq, accept => \*(AqNOTICE\-\*(Aq,
\&    format_reason => \*(AqIGNORE\*(Aq,
\&    to_prio => [ \*(AqALERT\-\*(Aq => \*(Aqerr\*(Aq ];
\&
\&  # disable default dispatcher, when daemon
\&  dispatcher close => \*(Aqdefault\*(Aq;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This dispatchers produces output to syslog, based on the Sys::Syslog
module (which will NOT be automatically installed for you, because some
systems have a problem with this dependency).
.PP
The REASON for a message often uses names which are quite similar to
the log\-levels used by syslog.  However: they have a different purpose.
The REASON is used by the programmer to indicate the cause of the message:
whether it was able to handle a certain situation.  The syslog levels
are there for the user\*(Aqs of the program (with syslog usually the
system administrators).  It is not unusual to see a "normal" error
or mistake as a very serious situation in a production environment. So,
you may wish to translate any message above reason MISTAKE into a LOG_CRIT.
.PP
The default translation table is list below.  You can change the mapping
using new(to_prio).  See example in SYNOPSIS.
.PP
.Vb 6
\&  TRACE   => LOG_DEBUG    ERROR   => LOG_ERR
\&  ASSERT  => LOG_DEBUG    FAULT   => LOG_ERR
\&  INFO    => LOG_INFO     ALERT   => LOG_ALERT
\&  NOTICE  => LOG_NOTICE   FAILURE => LOG_EMERG
\&  WARNING => LOG_WARNING  PANIC   => LOG_CRIT
\&  MISTAKE => LOG_WARNING
.Ve
.PP
Extends "DESCRIPTION" in Log::Report::Dispatcher.
.SH METHODS
.IX Header "METHODS"
Extends "METHODS" in Log::Report::Dispatcher.
.SS Constructors
.IX Subsection "Constructors"
Extends "Constructors" in Log::Report::Dispatcher.
.ie n .IP "$class\->\fBnew\fR($type, $name, %options)" 4
.el .IP "\f(CW$class\fR\->\fBnew\fR($type, \f(CW$name\fR, \f(CW%options\fR)" 4
.IX Item "$class->new($type, $name, %options)"
With syslog, people tend not to include the REASON of the message
in the logs, because that is already used to determine the destination
of the message.
Improves base, see "Constructors" in Log::Report::Dispatcher
.Sp
.Vb 10
\& \-Option        \-\-Defined in             \-\-Default
\&  accept          Log::Report::Dispatcher  depend on mode
\&  charset                                  \*(Aqutf8\*(Aq
\&  facility                                 \*(Aquser\*(Aq
\&  flags                                    \*(Aqpid,nowait\*(Aq
\&  format                                   <unchanged>
\&  format_reason   Log::Report::Dispatcher  \*(AqIGNORE\*(Aq
\&  identity                                 <basename C<$0>>
\&  include_domain                           false
\&  locale          Log::Report::Dispatcher  <system locale>
\&  logsocket                                undef
\&  mode            Log::Report::Dispatcher  \*(AqNORMAL\*(Aq
\&  to_prio                                  []
.Ve
.RS 4
.ie n .IP "accept => $reasons|\e@reasons" 2
.el .IP "accept => \f(CW$reasons\fR|\e@reasons" 2
.IX Item "accept => $reasons|@reasons"
.PD 0
.ie n .IP "charset => $charset" 2
.el .IP "charset => \f(CW$charset\fR" 2
.IX Item "charset => $charset"
.PD
Translate the text\-strings into the specified \f(CW$charset\fR, otherwise the
sysadmin may get unreadable text.
.ie n .IP "facility => $facility" 2
.el .IP "facility => \f(CW$facility\fR" 2
.IX Item "facility => $facility"
The possible values for this depend (a little) on the system.  POSIX
only defines \f(CW\*(C`user\*(C'\fR, and \f(CW\*(C`local0\*(C'\fR up to \f(CW\*(C`local7\*(C'\fR.
.ie n .IP "flags => $flags" 2
.el .IP "flags => \f(CW$flags\fR" 2
.IX Item "flags => $flags"
Any combination of \f(CW$flags\fR as defined by Sys::Syslog, as comma\-separated
string.  Examples for flags are: \f(CW\*(C`pid\*(C'\fR, \f(CW\*(C`ndelay\*(C'\fR, and \f(CW\*(C`nowait\*(C'\fR.
.IP "format => CODE" 2
.IX Item "format => CODE"
[1.10] With a CODE reference you get your hands on the text before
it gets sent to syslog.  The three parameters are: the (translated) text,
the related text domain object, and the message object.  You may want to
use context information from the latter.
.Sp
[1.19] After the three positional parameters, there may be a list of
pairs (named parameters) with additional info.  This may contain a
\&\f(CW\*(C`location\*(C'\fR with an ARRAY of information produced by \fBcaller()\fR about the
origin of the exception.
.IP "format_reason => \*(AqUPPERCASE\*(Aq|\*(AqLOWERCASE\*(Aq|\*(AqUCFIRST\*(Aq|\*(AqIGNORE\*(Aq|CODE" 2
.IX Item "format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE"
.PD 0
.ie n .IP "identity => $program" 2
.el .IP "identity => \f(CW$program\fR" 2
.IX Item "identity => $program"
.IP "include_domain => BOOLEAN" 2
.IX Item "include_domain => BOOLEAN"
.PD
[1.00] Include the text\-domain of the message in each logged message.
.IP "locale => LOCALE" 2
.IX Item "locale => LOCALE"
.PD 0
.IP "logsocket => \*(Aqunix\*(Aq|\*(Aqinet\*(Aq|\*(Aqstream\*(Aq|HASH" 2
.IX Item "logsocket => 'unix'|'inet'|'stream'|HASH"
.PD
If specified, the log socket type will be initialized to this before
\&\f(CWopenlog()\fR is called.  If not specified, the system default is used.
.IP "mode => \*(AqNORMAL\*(Aq|\*(AqVERBOSE\*(Aq|\*(AqASSERT\*(Aq|\*(AqDEBUG\*(Aq|0..3" 2
.IX Item "mode => 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3"
.PD 0
.IP "to_prio => \e@PAIRS" 2
.IX Item "to_prio => @PAIRS"
.PD
See \fBreasonToPrio()\fR.
.RE
.RS 4
.RE
.SS Accessors
.IX Subsection "Accessors"
Extends "Accessors" in Log::Report::Dispatcher.
.ie n .IP "$obj\->\fBformat\fR( [CODE] )" 4
.el .IP "\f(CW$obj\fR\->\fBformat\fR( [CODE] )" 4
.IX Item "$obj->format( [CODE] )"
Returns the \f(CW\*(C`CODE\*(C'\fR ref which formats the syslog line.
.ie n .IP $obj\->\fBisDisabled\fR() 4
.el .IP \f(CW$obj\fR\->\fBisDisabled\fR() 4
.IX Item "$obj->isDisabled()"
Inherited, see "Accessors" in Log::Report::Dispatcher
.ie n .IP $obj\->\fBmode\fR() 4
.el .IP \f(CW$obj\fR\->\fBmode\fR() 4
.IX Item "$obj->mode()"
Inherited, see "Accessors" in Log::Report::Dispatcher
.ie n .IP $obj\->\fBname\fR() 4
.el .IP \f(CW$obj\fR\->\fBname\fR() 4
.IX Item "$obj->name()"
Inherited, see "Accessors" in Log::Report::Dispatcher
.ie n .IP "$obj\->\fBneeds\fR( [$reason] )" 4
.el .IP "\f(CW$obj\fR\->\fBneeds\fR( [$reason] )" 4
.IX Item "$obj->needs( [$reason] )"
Inherited, see "Accessors" in Log::Report::Dispatcher
.ie n .IP $obj\->\fBtype\fR() 4
.el .IP \f(CW$obj\fR\->\fBtype\fR() 4
.IX Item "$obj->type()"
Inherited, see "Accessors" in Log::Report::Dispatcher
.SS Logging
.IX Subsection "Logging"
Extends "Logging" in Log::Report::Dispatcher.
.ie n .IP $any\->\fBaddSkipStack\fR(@CODE) 4
.el .IP \f(CW$any\fR\->\fBaddSkipStack\fR(@CODE) 4
.IX Item "$any->addSkipStack(@CODE)"
Inherited, see "Logging" in Log::Report::Dispatcher
.ie n .IP $obj\->\fBclose\fR() 4
.el .IP \f(CW$obj\fR\->\fBclose\fR() 4
.IX Item "$obj->close()"
Inherited, see "Logging" in Log::Report::Dispatcher
.ie n .IP $any\->\fBcollectLocation\fR() 4
.el .IP \f(CW$any\fR\->\fBcollectLocation\fR() 4
.IX Item "$any->collectLocation()"
Inherited, see "Logging" in Log::Report::Dispatcher
.ie n .IP "$any\->\fBcollectStack\fR( [$maxdepth] )" 4
.el .IP "\f(CW$any\fR\->\fBcollectStack\fR( [$maxdepth] )" 4
.IX Item "$any->collectStack( [$maxdepth] )"
Inherited, see "Logging" in Log::Report::Dispatcher
.ie n .IP "$obj\->\fBlog\fR(\e%options, $reason, $message, $domain)" 4
.el .IP "\f(CW$obj\fR\->\fBlog\fR(\e%options, \f(CW$reason\fR, \f(CW$message\fR, \f(CW$domain\fR)" 4
.IX Item "$obj->log(%options, $reason, $message, $domain)"
Inherited, see "Logging" in Log::Report::Dispatcher
.ie n .IP $obj\->\fBreasonToPrio\fR($reason) 4
.el .IP \f(CW$obj\fR\->\fBreasonToPrio\fR($reason) 4
.IX Item "$obj->reasonToPrio($reason)"
Returns a level which is understood by \fBsyslog\fR\|(3), based on a translation
table.  This can be changed with new(to_prio).
.ie n .IP $obj\->\fBskipStack\fR() 4
.el .IP \f(CW$obj\fR\->\fBskipStack\fR() 4
.IX Item "$obj->skipStack()"
Inherited, see "Logging" in Log::Report::Dispatcher
.ie n .IP $any\->\fBstackTraceLine\fR(%options) 4
.el .IP \f(CW$any\fR\->\fBstackTraceLine\fR(%options) 4
.IX Item "$any->stackTraceLine(%options)"
Inherited, see "Logging" in Log::Report::Dispatcher
.ie n .IP "$obj\->\fBtranslate\fR(\e%options, $reason, $message)" 4
.el .IP "\f(CW$obj\fR\->\fBtranslate\fR(\e%options, \f(CW$reason\fR, \f(CW$message\fR)" 4
.IX Item "$obj->translate(%options, $reason, $message)"
Inherited, see "Logging" in Log::Report::Dispatcher
.SH DETAILS
.IX Header "DETAILS"
Extends "DETAILS" in Log::Report::Dispatcher.
.SH DIAGNOSTICS
.IX Header "DIAGNOSTICS"
.ie n .IP "Error: max one active syslog dispatcher, attempt for $new have $old" 4
.el .IP "Error: max one active syslog dispatcher, attempt for \f(CW$new\fR have \f(CW$old\fR" 4
.IX Item "Error: max one active syslog dispatcher, attempt for $new have $old"
Cast by \f(CWnew()\fR
.IP "Error: syslog level \*(Aq$level\*(Aq not understood" 4
.IX Item "Error: syslog level '$level' not understood"
Cast by \f(CWnew()\fR
.SH "SEE ALSO"
.IX Header "SEE ALSO"
This module is part of Log\-Report version 1.43,
built on December 05, 2025. Website: \fIhttp://perl.overmeer.net/CPAN/\fR
.SH LICENSE
.IX Header "LICENSE"
For contributors see file ChangeLog.
.PP
This software is copyright (c) 2007\-2025 by Mark Overmeer.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.