Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Syslog(3)	      User Contributed Perl Documentation	     Syslog(3)

NAME
       Unix::Syslog - Perl interface to	the UNIX syslog(3) calls

SYNOPSIS
	use Unix::Syslog qw(:macros);  # Syslog	macros
	use Unix::Syslog qw(:subs);    # Syslog	functions

	openlog	$ident,	$option, $facility;
	syslog $priority, $format, @formatargs;
	closelog;
	$oldmask = setlogmask $mask_priority;

DESCRIPTION
       This module provides an interface to the	system logger syslogd(8) via
       Perl's XSUBs. The implementation	attempts to resemble the native	libc-
       functions of your system, so that anyone	being familiar with syslog.h
       should be able to use this module right away.

       In contrary to Sys::Syslog(3), this modules does	not open a network
       connection to send the messages.	This can help you to avoid opening
       security	holes in your computer (see "FAQ").

       The subs	imported by the	tag "macros" are simply	wrappers around	the
       most important "#defines" in your system's C header file	syslog.h. The
       macros return integer values that are used to specify options,
       facilities and priorities in a more or less portable way. They also
       provide general information about your local syslog mechanism. Check
       syslog(3) and your local	syslog.h for information about the macros,
       options and facilities available	on your	system.

       The following functions are provided:

       openlog $ident, $option,	$facility
	   opens a connection to the system logger.  $ident is an identifier
	   string that syslogd(8) prints into every message. It	usually	equals
	   the process name. $option is	an integer value that is the result of
	   ORed	options. $facility is an integer value that specifies the part
	   of the system the message should be associated with (e.g. kernel
	   message, mail subsystem).

       syslog $priority, $format, @formatargs
	   Generates a log message and passes it to the	system logger. If
	   "syslog()" is called	without	calling	"openlog()" first, probably
	   system dependent default values will	be used	as arguments for an
	   implicit call to "openlog()".

	   $priority is	an integer value that specifies	the priority of	the
	   message. Alternatively $priority can	be the ORed value of a
	   priority and	a facility. In that case a previously selected
	   facility will be overridden.

	   In the case that "syslog()" is called without calling "openlog()"
	   first and priority does not specify both a priority and a facility,
	   a default facility will be used. This behaviour is most likely
	   system dependent and	the user should	not rely on any	particular
	   value in that case.

	   $format is a	format string in the style of printf(3). Additionally
	   to the usual	printf directives %m can be specified in the string.
	   It will be replaced implicitly by the contents of the Perl variable
	   $! ($ERRNO).	@formatargs is a list of values	that the format
	   directives will be replaced with subsequently.

       closelog
	   closes the connection to the	system logger.

       setlogmask $mask_priority
	   sets	the priority mask and returns the old mask. Logging is enabled
	   for the priorities indicated	by the bits in the mask	that are set
	   and is disabled where the bits are not set. Macros are provided to
	   specify valid and portable arguments	to "setlogmask()". Usually the
	   default log mask allows all messages	to be logged.

       priorityname $priority
	   returns a string containing the name	of $priority as	string.	If
	   this	functionality has not been enabled at installation, the
	   function returns undef.

       facilityname $facility
	   returns a string containing the name	of $facility as	string.	If
	   this	functionality has not been enabled at installation, the
	   function returns undef.

       NOTE: The behaviour of this module is system dependent. It is highly
       recommended to consult your system manual for available macros and the
       behaviour of the	provided functions.

RETURN VALUES
       The functions openlog(),	syslog() and closelog()	return the undefined
       value. The function setlogmask returns the previous mask	value.

EXAMPLES
       Open a channel to syslogd specifying an identifier (usually the process
       name) some options and the facility:
	 "openlog "test.pl", LOG_PID | LOG_PERROR, LOG_LOCAL7;"

       Generate	log message of specified priority using	a printf-type
       formatted string:
	 "syslog LOG_INFO, "This is message number %d",	42;"

       Set log priority	mask to	block all messages but those of	priority
       "LOG_DEBUG":
	 "$oldmask = setlogmask(LOG_MASK(LOG_DEBUG))"

       Set log priority	mask to	block all messages with	a higher priority than
       "LOG_ERR":
	 "$oldmask = setlogmask(LOG_UPTO(LOG_ERR))"

       Close channel to	syslogd:
	 "closelog;"

FAQ
       1.  What	is the benefit of using	this module instead of Sys::Syslog?

	   Sys::Syslog always opens a network connection to the	syslog
	   service. At least on	Linux systems this may lead to some trouble,
	   because

	   o   Linux syslogd (from package sysklogd) does not listen to	the
	       network by default. Most	people working on stand-alone machines
	       (including me) didn't see any reason why	to enable this option.
	       Others didn't enable it for security reasons.

	       OS-independent, some sysadmins may run a	firewall on their
	       network that blocks connections to port 514/udp.

	   o   By default Linux	syslogd	doesn't	forward	messages which have
	       already already received	from the network to other log hosts.
	       There are reasons not to	enable this option unless it is	really
	       necessary. Looping messages resulting from a misconfiguration
	       may break down your (log-)system.

	   Peter Stamfest <peter.stamfest@eunet.at> pointed out	some other
	   advantages of Unix::Syslog, I didn't	came across my self.

	   o   LOG_PERROR works.

	   o   works with perl -Tw without warnings and	problems due to
	       tainted data as it is the case for Sys::Syslog in some special
	       applications. [Especially when running a	script as root]

       2.  Well, is there any reason to	use Sys::Syslog	any longer?

	   Yes!	In contrary to Unix::Syslog, Sys::Syslog works even if you
	   don't have a	syslog daemon running on your system as	long as	you
	   are connected to a log host via a network and have access to	the
	   syslog.h header file	of your	log host to generate the initial files
	   for Sys::Syslog (see	Sys::Syslog(3) for details). Unix::Syslog only
	   logs	to your	local syslog daemon which in turn may be configured to
	   distribute the message over the network.

       3.  Are calls to	the functions provided by Unix::Syslog compatible to
	   those of Sys::Syslog?

	   Currently not. Sys::Syslog requires strings to specify many of the
	   arguments to	the functions, while Unix::Syslog uses numeric
	   constants accessed via macros as defined in syslog.h. Although the
	   strings used	by Sys::Syslog are also	defined	in syslog.h, it	seems
	   that	most people got	used to	the numeric arguments. I will
	   implement the string	based calls if there are enough	people
	   ($min_people	> 10**40) complaining about the	lack of	compatibility.

SEE ALSO
       syslog(3), Sys::Syslog(3), syslogd(8), perl(1)

AUTHOR
       Marcus Harnisch <marcus.harnisch@gmx.net>

perl v5.32.0			  2008-05-18			     Syslog(3)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | EXAMPLES | FAQ | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Unix::Syslog&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help