Sys::Syslog(3perl)

📦
version 5.44.0 · 14 versions
, in arch rolling

💖 Sys::Syslog — the 3perl manual, bestie edition 💖

Okay so you know that Sys::Syslog page from the Perl Programmers Reference Guide? Yeah. We're doing it. Grab a snack, this is a long one but it's literally so good. 🍓

✨ NAME ✨

Sys::Syslog — it's the Perl interface to the UNIX syslog(3) calls. That's it. That's the whole vibe. 🦋

🌸 VERSION 🌸

This is the docs for version 0.36. Iconic number, no notes. 💅

🎀 SYNOPSIS 🎀

Copy this exactly, bestie, I'm not playing around:

use Sys::Syslog;                        # all except setlogsock()
use Sys::Syslog qw(:standard :macros);  # standard functions & macros

openlog($ident, $logopt, $facility);    # don't forget this
syslog($priority, $format, @args);
$oldmask = setlogmask($mask_priority);
closelog();

Not me emphasising the # don't forget this comment because it is SO real. That comment came from the manpage itself and it is speaking truth. 🔥

🌈 DESCRIPTION 🌈

Sys::Syslog is an interface to the UNIX syslog(3) program. You call syslog() with a string priority and a list of printf() args, exactly like syslog(3) does. Same energy, but Perl-flavoured. Periodt. ✨

👑 EXPORTS 👑

Sys::Syslog exports the following Exporter tags:

  • :standard — exports the standard syslog(3) functions:
openlog closelog setlogmask syslog
  • :extended — exports the Perl-specific functions for syslog(3):
setlogsock
  • :macros — exports the symbols matching most of your syslog(3) macros, plus the LOG_UPTO() and LOG_MASK() functions. Wanna know which constants you get and what they mean? Peep "CONSTANTS" bestie. 👀

By default, Sys::Syslog exports the symbols from the :standard tag. That's the default default. 💜

💅 FUNCTIONS 💅

💖 openlog($ident, $logopt, $facility)

Opens the syslog. Let's break down the cast:

  • $ident — gets prepended to every single message. It's the little name tag your logs wear. 🎀
  • $logopt — holds zero or more of the options detailed below.
  • $facility — says which part of the system you're reporting about, like LOG_USER or LOG_LOCAL0. Scroll to "Facilities" for the well-known list, and check your own syslog(3) docs for what your system actually supports. There's useful links in "SEE ALSO" too. A facility can be given as a string or as a numeric macro.
Heads up: this function will croak if it can't connect to the syslog daemon. Like, it will not be chill about it. 😭

Also, important glow-up: openlog() now takes three arguments, just like openlog(3). We love consistency.

And fr fr, use openlog() before you call syslog(). Trust.

Options

  • cons — this one is straight up ignored, because the failover mechanism will drop down to the console automatically anyway if all other media fail. It's giving retired. 💀
  • ndelay — opens the connection immediately. Normally the connection only gets opened when the first message is logged, but with this? Right now. Instant. Main character energy. ⚡
  • noeol — when set to true, no end of line character ("\n") gets appended to the message. Handy for some syslog daemons. Added in Sys::Syslog 0.29. ✨
  • nofatal — when set to true, openlog() and syslog() will only emit warnings instead of dying when the connection to the syslog can't be established. Added in Sys::Syslog 0.15. Softer launch, no drama. 🫶
  • nonul — when set to true, no NUL character ("\0") is appended to the message. Useful for some syslog daemons. Added in Sys::Syslog 0.29. 🦋
  • nowait — don't wait for child processes that may have been created while logging the message. Quick note though: the GNU C library doesn't create a child process, so on Linux this option has no effect. Rip. 🙈
  • perror — writes the message to standard error output as well as to the system log. Double posting, but make it intentional. Added in Sys::Syslog 0.22. 💜
  • pid — include the PID with each message. Who said that? Now you know. 🔍

Examples

Open the syslog with options ndelay and pid, and facility LOCAL0:

openlog($name, "ndelay,pid", "local0");

Same thing, but this time using the macro that corresponds to LOCAL0:

openlog($name, "ndelay,pid", LOG_LOCAL0);

💖 syslog($priority, $message) / syslog($priority, $format, @args)

If $priority permits, this logs $message, or sprintf($format, @args), with one extra little bonus: %m in $message or $format gets replaced with $! — that's the latest error message. Chef's kiss. 😌

$priority can specify just a level, or a level and a facility. Levels and facilities can be given as strings or as macros. And when you're using the eventlog mechanism, the priorities get mapped like this: DEBUG and INFO → event type informational, NOTICE and WARNING → warning, and ERR through EMERG → error. Cute little translation layer. 🌈

If you didn't call openlog() before using syslog(), then syslog() will try to guess $ident by extracting the shortest prefix of $format that ends in a ":". It's doing its best, okay? 🥺

Examples

# informational level
syslog("info", $message);
syslog(LOG_INFO, $message);

# information level, Local0 facility
syslog("info|local0", $message);
syslog(LOG_INFO|LOG_LOCAL0, $message);

Note

Okay so Sys::Syslog version v0.07 and older passed $message as the formatting string to sprintf() even when no formatting arguments were provided. If the code calling syslog() might run with older versions of this module, make sure you call the function like syslog($priority, "%s", $message) instead of syslog($priority, $message). This protects you against hostile formatting sequences that could show up if $message contains tainted data. 🛡️

Security bestie moment. Do not skip this. Protect yourself. 💀

💖 setlogmask($mask_priority)

Sets the log mask for the current process to $mask_priority, and returns the old mask.

If the mask argument is 0, the current log mask is not modified. (Not a single thing changes. It stays exactly as it was.) See "Levels" for the list of available levels. And you can use the LOG_UPTO() function to allow all levels up to a given priority — but note that it only accepts the numeric macros as arguments. Okay? Okay. 💜

Examples

Only log errors:

setlogmask( LOG_MASK(LOG_ERR) );

Log everything except informational messages:

setlogmask( ~(LOG_MASK(LOG_INFO)) );

Log critical messages, errors and warnings:

setlogmask( LOG_MASK(LOG_CRIT)
          | LOG_MASK(LOG_ERR)
          | LOG_MASK(LOG_WARNING) );

Log all messages up to debug:

setlogmask( LOG_UPTO(LOG_DEBUG) );

💖 setlogsock()

Sets the socket type and options to be used for the next call to openlog() or syslog(). Returns true on success, undef on failure.

Being Perl-specific, this function has evolved over time — it's been through some eras, honestly. It can currently be called like this:

  • setlogsock($sock_type)
  • setlogsock($sock_type, $stream_location) (added in Perl 5.004_02)
  • setlogsock($sock_type, $stream_location, $sock_timeout) (added in Sys::Syslog 0.25)
  • setlogsock(\%options) (added in Sys::Syslog 0.28)

The available options are

  • type — equivalent to $sock_type, selects the socket type (or "mechanism"). You can pass an array reference here to specify several mechanisms to try, in the given order. 💫
  • path — equivalent to $stream_location, sets the stream location. Defaults to the standard Unix location, or _PATH_LOG.
  • timeout — equivalent to $sock_timeout, sets the socket timeout in seconds. Defaults to 0 on all systems except Mac OS X where it's set to 0.25 sec. (Mac said "let me cook" 🍎)
  • host — sets the hostname to send the messages to. Defaults to the local host.
  • port — sets the TCP or UDP port to connect to. Defaults to the first standard syslog port available on the system.

The available mechanisms are

  • native — use the native C functions from your syslog(3) library (added in Sys::Syslog 0.15).
  • eventlog — send messages to the Win32 events logger (Win32 only; added in Sys::Syslog 0.19).
  • tcp — connect to a TCP socket, on the syslog/tcp or syslogng/tcp service. See also the host, port and timeout options.
  • udp — connect to a UDP socket, on the syslog/udp service. See also the host, port and timeout options.
  • inet — connect to an INET socket, either TCP or UDP, tried in that order. See also the host, port and timeout options.
  • unix — connect to a UNIX domain socket (on some systems, a character special device). The name of that socket is given by the path option, or if that's omitted, the value returned by the _PATH_LOG macro (if your system defines it), /dev/log or /dev/conslog, whichever is writable.
  • stream — connect to the stream indicated by the path option, or if omitted, the value returned by the _PATH_LOG macro (if your system defines it), /dev/log or /dev/conslog, whichever is writable. For example, Solaris and IRIX systems may prefer stream instead of unix.
  • pipe — connect to the named pipe indicated by the path option, or if omitted, to the value returned by the _PATH_LOG macro (if your system defines it), or /dev/log (added in Sys::Syslog 0.21). HP-UX is a system that uses such a named pipe.
  • console — send messages directly to the console, as for the cons option of openlog().

The default is to try native, tcp, udp, unix, pipe, stream, console. Under systems with the Win32 API, eventlog gets added as the first mechanism to try if Win32::EventLog is available. 🌟

Giving an invalid value for $sock_type will croak. Don't test it. 🫠

Examples

Select the UDP socket mechanism:

setlogsock("udp");

Send messages using the TCP socket mechanism on a custom port:

setlogsock({ type => "tcp", port => 2486 });

Send messages to a remote host using the TCP socket mechanism:

setlogsock({ type => "tcp", host => $loghost });

Try the native, UDP socket then UNIX domain socket mechanisms:

setlogsock(["native", "udp", "unix"]);

Note

Now that the native mechanism is supported by Sys::Syslog and selected by default, using the setlogsock() function is discouraged, because the other mechanisms are less portable across operating systems. Authors of modules and programs that use this function — especially in its cargo-cult form, setlogsock("unix") — are advised to remove any occurrence of it unless they specifically want to use a given mechanism (like TCP or UDP to connect to a remote host).

Not me calling out the setlogsock("unix") cargo cult BY NAME. The manpage said it, not me. 😭

💖 closelog()

Closes the log file and returns true on success. Short, sweet, slays. 💅

🥊 THE RULES OF SYS::SYSLOG 🥊

okay bestie, fight club rules but make it logs. memorize these, fr fr.

  1. The First Rule of Sys::Syslog is: You do not call setlogsock.
  2. The Second Rule of Sys::Syslog is: You do not call setlogsock. (yes, it's on there twice, that's the whole bit, don't come for me 💅)
  3. The Third Rule of Sys::Syslog is: The program crashes, dies, calls closelog, the log is over.
  4. The Fourth Rule of Sys::Syslog is: One facility, one priority.
  5. The Fifth Rule of Sys::Syslog is: One log at a time.
  6. The Sixth Rule of Sys::Syslog is: No syslog before openlog.
  7. The Seventh Rule of Sys::Syslog is: Logs will go on as long as they have to.
  8. The Eighth, and Final Rule of Sys::Syslog is: If this is your first use of Sys::Syslog, you must read the doc.

✨ EXAMPLES ✨

bestie here's what it actually looks like when you use it, no cap:

openlog($program, 'cons,pid', 'user');
syslog('info', '%s', 'this is another test');
syslog('mail|warning', 'this is a better test: %d', time);
closelog();

syslog('debug', 'this is the last test');

Another one, because we're generous 🫶:

openlog("$program $$", 'ndelay', 'user');
syslog('notice', 'fooprogram: this is really done');

okay and here's %m doing its little cameo, it's giving very much "the errno but make it syslog":

$! = 55;
syslog('info', 'problem was %m');   # %m == $! in syslog(3)

And if you wanna log to a UDP port on $remotehost instead of logging locally? iconic behaviour, here u go:

setlogsock("udp", $remotehost);
openlog($program, 'ndelay', 'user');
syslog('info', 'something happened over here');

🌈 CONSTANTS 🌈

Facilities

  • LOG_AUDIT — audit daemon (IRIX); falls back to LOG_AUTH
  • LOG_AUTH — security/authorization messages
  • LOG_AUTHPRIV — security/authorization messages (private)
  • LOG_CONSOLE — /dev/console output (FreeBSD); falls back to LOG_USER
  • LOG_CRON — clock daemons (cron and at)
  • LOG_DAEMON — system daemons without separate facility value
  • LOG_FTP — FTP daemon
  • LOG_KERN — kernel messages
  • LOG_INSTALL — installer subsystem (Mac OS X); falls back to LOG_USER
  • LOG_LAUNCHD — launchd - general bootstrap daemon (Mac OS X); falls back to LOG_DAEMON
  • LOG_LFMT — logalert facility; falls back to LOG_USER
  • LOG_LOCAL0 through LOG_LOCAL7 — reserved for local use
  • LOG_LPR — line printer subsystem
  • LOG_MAIL — mail subsystem
  • LOG_NETINFO — NetInfo subsystem (Mac OS X); falls back to LOG_DAEMON
  • LOG_NEWS — USENET news subsystem
  • LOG_NTP — NTP subsystem (FreeBSD, NetBSD); falls back to LOG_DAEMON
  • LOG_RAS — Remote Access Service (VPN / PPP) (Mac OS X); falls back to LOG_AUTH
  • LOG_REMOTEAUTH — remote authentication/authorization (Mac OS X); falls back to LOG_AUTH
  • LOG_SECURITY — security subsystems (firewalling, etc.) (FreeBSD); falls back to LOG_AUTH
  • LOG_SYSLOG — messages generated internally by syslogd
  • LOG_USER (default) — generic user-level messages
  • LOG_UUCP — UUCP subsystem

Levels

so these go from "the world is ending" all the way down to "just chatting", bestie:

  • LOG_EMERG — system is unusable
  • LOG_ALERT — action must be taken immediately
  • LOG_CRIT — critical conditions
  • LOG_ERR — error conditions
  • LOG_WARNING — warning conditions
  • LOG_NOTICE — normal, but significant, condition
  • LOG_INFO — informational message
  • LOG_DEBUG — debug-level message

🩺 DIAGNOSTICS 🩺

vibe check on the error messages. (F) means it's fatal, like for real it dies. (W) is just a warning, a little heads up, nbd.

  • "Invalid argument passed to setlogsock" — (F) You gave setlogsock() an invalid value for $sock_type.
  • "eventlog passed to setlogsock, but no Win32 API available" — (W) You asked setlogsock() to use the Win32 event logger but the operating system running the program isn't Win32 or does not provides Win32 compatible facilities.
  • "no connection to syslog available" — (F) syslog() failed to connect to the specified socket. 😭
  • "stream passed to setlogsock, but %s is not writable" — (W) You asked setlogsock() to use a stream socket, but the given path is not writable.
  • "stream passed to setlogsock, but could not find any device" — (W) You asked setlogsock() to use a stream socket, but didn't provide a path, and Sys::Syslog was unable to find an appropriate one.
  • "tcp passed to setlogsock, but tcp service unavailable" — (W) You asked setlogsock() to use a TCP socket, but the service is not available on the system.
  • "syslog: expecting argument %s" — (F) You forgot to give syslog() the indicated argument.
  • "syslog: invalid level/facility: %s" — (F) You specified an invalid level or facility.
  • "syslog: too many levels given: %s" — (F) You specified too many levels.
  • "syslog: too many facilities given: %s" — (F) You specified too many facilities.
  • "syslog: level must be given" — (F) You forgot to specify a level.
  • "udp passed to setlogsock, but udp service unavailable" — (W) You asked setlogsock() to use a UDP socket, but the service is not available on the system.
  • "unix passed to setlogsock, but path not available" — (W) You asked setlogsock() to use a UNIX socket, but Sys::Syslog was unable to find an appropriate an appropriate device.

📜 HISTORY 📜

okay so Sys::Syslog is a core module, part of the standard Perl distribution since 1990. like, before some of us were even a thought. At this time, modules as we know them didn't exist, the Perl library was a collection of .pl files, and the one for sending syslog messages with was simply lib/syslog.pl, included with Perl 3.0. It was converted as a module with Perl 5.0, but had a version number only starting with Perl 5.6. Here is a small table with the matching Perl and Sys::Syslog versions. 🦋

Sys::Syslog     Perl
-----------     ----
   undef        5.0.0 ~ 5.5.4
   0.01         5.6.*
   0.03         5.8.0
   0.04         5.8.1, 5.8.2, 5.8.3
   0.05         5.8.4, 5.8.5, 5.8.6
   0.06         5.8.7
   0.13         5.8.8
   0.22         5.10.0
   0.27         5.8.9, 5.10.1 ~ 5.14.*
   0.29         5.16.*
   0.32         5.18.*
   0.33         5.20.*
   0.33         5.22.*

👀 SEE ALSO 👀

Other modules

  • Log::Log4perl - Perl implementation of the Log4j API
  • Log::Dispatch - Dispatches messages to one or more outputs
  • Log::Report - Report a problem, with exceptions and language support

Manual Pages

RFCs

Articles

Event Log

🫶 AUTHORS & ACKNOWLEDGEMENTS 🫶

the whole team, everybody say thank you 🙏✨

Tom Christiansen <tchrist (at) perl.com> and Larry Wall <larry (at) wall.org>.

UNIX domain sockets added by Sean Robinson <robinson_s (at) sc.maricopa.edu> with support from Tim Bunce <Tim.Bunce (at) ig.co.uk> and the perl5-porters mailing list.

Dependency on syslog.ph replaced with XS code by Tom Hughes <tom (at) compton.nu>.

Code for constant()s regenerated by Nicholas Clark <nick (at) ccl4.org>.

Failover to different communication modes by Nick Williams <Nick.Williams (at) morganstanley.com>.

Extracted from core distribution for publishing on the CPAN by Sébastien Aperghis-Tramoni <sebastien (at) aperghis.net>.

XS code for using native C functions borrowed from Unix::Syslog, written by Marcus Harnisch <marcus.harnisch (at) gmx.net>.

Yves Orton suggested and helped for making Sys::Syslog use the native event logger under Win32 systems.

Jerry D. Hedden and Reini Urban provided greatly appreciated help to debug and polish Sys::Syslog under Cygwin.

🐛 BUGS 🐛

found a bug? spotted a feature you want? please report any bugs or feature requests to bug-sys-syslog (at) rt.cpan.org, or through the web interface at http://rt.cpan.org/Public/Dist/Display.html?Name=Sys-Syslog. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. teamwork, bestie 💖

🎀 SUPPORT 🎀

You can find documentation for this module with the perldoc command.

perldoc Sys::Syslog

You can also look for information at:

  • Perl Documentation

http://perldoc.perl.org/Sys/Syslog.html

  • MetaCPAN

https://metacpan.org/module/Sys::Syslog

  • Search CPAN

http://search.cpan.org/dist/Sys-Syslog/

  • AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/Sys-Syslog

  • CPAN Ratings

http://cpanratings.perl.org/d/Sys-Syslog

  • RT: CPAN's request tracker

http://rt.cpan.org/Dist/Display.html?Queue=Sys-Syslog

The source code is available on Git Hub: https://github.com/maddingue/Sys-Syslog/

Copyright (C) 1990-2012 by Larry Wall and others.

📄 LICENSE 📄

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

and that's a wrap on Sys::Syslog(3perl) bestie 🎉 this page ships with perl v5.44.0 and is dated 2026-10-17 — go forth, log responsibly, and remember: no syslog before openlog. periodt. 💅✨🌈

📦 where this page comes from