In Files

  • syslog/lib/syslog/logger.rb
  • syslog/syslog.c


The syslog package provides a Ruby interface to the POSIX system logging facility.

Syslog messages are typically passed to a central logging daemon. The daemon may filter them; route them into different files (usually found under /var/log); place them in SQL databases; forward them to centralized logging servers via TCP or UDP; or even alert the system administrator via email, pager or text message.

Unlike application-level logging via Logger or Log4r, syslog is designed to allow secure tamper-proof logging.

The syslog protocol is standardized in RFC 5424.

Public Class Methods

close() click to toggle source

Closes the syslog facility. Raises a runtime exception if it is not open.

               static VALUE mSyslog_close(VALUE self)
    if (!syslog_opened) {
        rb_raise(rb_eRuntimeError, "syslog not opened");


    xfree((void *)syslog_ident);
    syslog_ident = NULL;
    syslog_options = syslog_facility = syslog_mask = -1;
    syslog_opened = 0;

    return Qnil;
facility() click to toggle source

Returns the facility number used in the last call to open()

               static VALUE mSyslog_facility(VALUE self)
    return syslog_opened ? INT2NUM(syslog_facility) : Qnil;
ident() click to toggle source

Returns the identity string used in the last call to open()

               static VALUE mSyslog_ident(VALUE self)
    return syslog_opened ? rb_str_new2(syslog_ident) : Qnil;
inspect() click to toggle source

Returns an inspect() string summarizing the object state.

               static VALUE mSyslog_inspect(VALUE self)
    Check_Type(self, T_MODULE);

    if (!syslog_opened)
        return rb_sprintf("<#%s: opened=false>", rb_class2name(self));

    return rb_sprintf("<#%s: opened=true, ident=\"%s\", options=%d, facility=%d, mask=%d>",
instance() click to toggle source

Returns self, for backward compatibility.

               static VALUE mSyslog_instance(VALUE self)
    return self;
log(priority, format_string, *format_args) click to toggle source

Log a message with the specified priority. Example:

Syslog.log(Syslog::LOG_CRIT, "Out of disk space")
Syslog.log(Syslog::LOG_CRIT, "User %s logged in", ENV['USER'])

The priority levels, in descending order, are:


System is unusable


Action needs to be taken immediately


A critical condition has occurred


An error occurred


Warning of a possible problem


A normal but significant condition occurred


Informational message


Debugging information

Each priority level also has a shortcut method that logs with it’s named priority. As an example, the two following statements would produce the same result:

Syslog.log(Syslog::LOG_ALERT, "Out of memory")
Syslog.alert("Out of memory")

Format strings are as for printf/sprintf, except that in addition %m is replaced with the error message string that would be returned by strerror(errno).

               static VALUE mSyslog_log(int argc, VALUE *argv, VALUE self)
    VALUE pri;

    if (argc < 2) {
        rb_raise(rb_eArgError, "wrong number of arguments (%d for 2+)", argc);

    pri = *argv++;

    if (!FIXNUM_P(pri)) {
      rb_raise(rb_eTypeError, "type mismatch: %s given", rb_class2name(CLASS_OF(pri)));

    syslog_write(FIX2INT(pri), argc, argv);

    return self;
mask() click to toggle source

Returns the log priority mask in effect. The mask is not reset by opening or closing syslog.

               static VALUE mSyslog_get_mask(VALUE self)
    return syslog_opened ? INT2NUM(syslog_mask) : Qnil;
mask=(priority_mask) click to toggle source

Sets the log priority mask. A method LOG_UPTO is defined to make it easier to set mask values. Example:

Syslog.mask = Syslog::LOG_UPTO(Syslog::LOG_ERR)

Alternatively, specific priorities can be selected and added together using binary OR. Example:

Syslog.mask = Syslog::LOG_MASK(Syslog::LOG_ERR) | Syslog::LOG_MASK(Syslog::LOG_CRIT)

The priority mask persists through calls to open() and close().

               static VALUE mSyslog_set_mask(VALUE self, VALUE mask)
    if (!syslog_opened) {
        rb_raise(rb_eRuntimeError, "must open syslog before setting log mask");

    setlogmask(syslog_mask = NUM2INT(mask));

    return mask;
open(ident, options, facility) => syslog click to toggle source

Open the syslog facility. Raises a runtime exception if it is already open.

Can be called with or without a code block. If called with a block, the Syslog object created is passed to the block.

If the syslog is already open, raises a RuntimeError.

ident is a String which identifies the calling program.

options is the logical OR of any of the following:


If there is an error while sending to the system logger, write directly to the console instead.


Open the connection now, rather than waiting for the first message to be written.


Don’t wait for any child processes created while logging messages. (Has no effect on Linux.)


Opposite of LOG_NDELAY; wait until a message is sent before opening the connection. (This is the default.)


Print the message to stderr as well as sending it to syslog. (Not in POSIX.1-2001.)


Include the current process ID with each message.

facility describes the type of program opening the syslog, and is the logical OR of any of the following which are defined for the host OS:


Security or authorization. Deprecated, use LOG_AUTHPRIV instead.


Security or authorization messages which should be kept private.


System console message.


System task scheduler (cron or at).


A system daemon which has no facility value of its own.


An FTP server.


A kernel message (not sendable by user processes, so not of much use to Ruby, but listed here for completeness).


Line printer subsystem.


Mail delivery or transport subsystem.


Usenet news system.


Network Time Protocol server.


General security message.


Messages generated internally by syslog.


Generic user-level message.


UUCP subsystem.


Locally-defined facilities.

Example:"webrick", Syslog::LOG_PID,
            Syslog::LOG_DAEMON | Syslog::LOG_LOCAL3)
               static VALUE mSyslog_open(int argc, VALUE *argv, VALUE self)
    VALUE ident, opt, fac;

    if (syslog_opened) {
        rb_raise(rb_eRuntimeError, "syslog already open");

    rb_scan_args(argc, argv, "03", &ident, &opt, &fac);

    if (NIL_P(ident)) {
        ident = rb_gv_get("$0");
    syslog_ident = strdup(RSTRING_PTR(ident));

    if (NIL_P(opt)) {
        syslog_options = LOG_PID | LOG_CONS;
    } else {
        syslog_options = NUM2INT(opt);

    if (NIL_P(fac)) {
        syslog_facility = LOG_USER;
    } else {
        syslog_facility = NUM2INT(fac);

    openlog(syslog_ident, syslog_options, syslog_facility);

    syslog_opened = 1;

    setlogmask(syslog_mask = setlogmask(0));

    /* be like {...} */
    if (rb_block_given_p()) {
        rb_ensure(rb_yield, self, mSyslog_close, self);

    return self;
reopen(ident, options, facility) => syslog click to toggle source

Closes and then reopens the syslog.

Arguments are the same as for open().

               static VALUE mSyslog_reopen(int argc, VALUE *argv, VALUE self)

    return mSyslog_open(argc, argv, self);
opened? click to toggle source

Returns true if the syslog is open.

               static VALUE mSyslog_isopen(VALUE self)
    return syslog_opened ? Qtrue : Qfalse;
options() click to toggle source

Returns the options bitmask used in the last call to open()

               static VALUE mSyslog_options(VALUE self)
    return syslog_opened ? INT2NUM(syslog_options) : Qnil;
reopen(ident, options, facility) => syslog click to toggle source

Closes and then reopens the syslog.

Arguments are the same as for open().

               static VALUE mSyslog_reopen(int argc, VALUE *argv, VALUE self)

    return mSyslog_open(argc, argv, self);

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please visit

blog comments powered by Disqus