tcl-syslog(3tcl)

📦
version 2.0.2 · 2 versions
, in ubuntu stonking

💖 tcl-syslog — the manual page, but make it a group chat 💖

okay bestie, sit down, hydrate, and let me tell you about tcl-syslog(3tcl) — the Syslog interface for Tcl. yes it's real, yes it's iconic, and yes we're gonna go through every single line together. no skipping. 🫶

✨ NAME ✨

tcl-syslog — the Syslog interface for Tcl 💅

🌸 SYNOPSIS 🌸

like, here's the whole shape of it:

package require syslog

::syslog::open ?-ident ident? ?-facility facility? ?-pid? ?-perror? ?-console? ?-nodelay?
::syslog::close
::syslog::log ?-level level? ?-priority level? ?-facility facility? ?-format message_format? message
::syslog::configure ?-ident ident? ?-facility facility? ?-pid? ?-perror? ?-console? ?-nodelay?
::syslog::configure ?-level level? ?-priority level? ?-facility facility? ?-format message_format?
::syslog::cget
::syslog::cget -global

syslog ?-ident ident? ?-facility facility? ?-pid? ?-perror? ?-console? ?-nodelay? ?-level level? message

the ?question marks? mean "optional, bestie, you don't gotta". the rest you type exactly. periodt. ✨

🦋 DESCRIPTION 🦋

so. Syslog is a standard for forwarding log messages to local and other logging services that live on a TCP/IP network. it's typically used for computer system management and security auditing — usually to aggregate log messages in a central repository, which is giving "let's put all our receipts in one folder". it's standardized inside the Syslog working group of the IETF. and it's available in all POSIX compliant and POSIX-like Operating Systems. all of them. no cap. 👑

this package provides a Tcl interface to the standard syslog service. it creates a Tcl namespace with commands for:

  • opening and closing the connection to syslogd,
  • sending messages to the syslog service,
  • and querying configuration.

the current version also provides the global namespace command syslog for compatibility with earlier versions of the package. and bestie, listen: it is deprecated and kept only for backward compatibility. it's that one friend who still shows up but we're gently phasing out. 🙈

🎀 COMMANDS 🎀

💜 ::syslog::open

Establish the process-wide connection to the syslog facility (calls openlog). this one should be called once per process (typically at startup, like your morning routine). options set here are global and shared among threads.

okay so the options:

  • -ident ident — optional tag used by syslog to identify the process or log context. it's the little name tag at the party. 🏷️
  • -pid — if rsyslog or the logger log line formatting rules don't already show the pid, it can be added by specifying this option.
  • -perror — print the message also to stderr.
  • -console — write directly to the system console if syslogd is unavailable.
  • -nodelay — open the connection immediately instead of waiting for the first message. impatient queen behaviour, we respect it.
  • -facility facility — set the default facility for this process. valid facilities are:
  • auth — security/authorization messages
  • authpriv — security/authorization messages (private)
  • cron — clock daemon (cron and at)
  • daemon — system daemons without separate facility value
  • ftp — ftp daemon
  • kern — kernel messages
  • local0 — local use (0)
  • local1 — local use (1)
  • local2 — local use (2)
  • local3 — local use (3)
  • local4 — local use (4)
  • local5 — local use (5)
  • local6 — local use (6)
  • local7 — local use (7)
  • lpr — line printer subsystem
  • mail — mail subsystem
  • news — USENET news subsystem
  • syslog — messages generated internally by syslogd(8)
  • user — generic user-level messages
  • uucp — UUCP subsystem

the default facility is user. 🌿

🌈 ::syslog::close

Close the process-wide connection to syslog (calls closelog). it is safe to call this multiple times, but unwise if the code is supposed to log more lines. it will work, but it comes at the cost of re-establishing the connection to the syslog service. it's giving "leaving the group chat and then getting re-added 30 seconds later". 😭

⭐ ::syslog::log

Send a log message. options set here are per-thread (interpreter-local) and persist across subsequent calls in the same thread. yes, they remember. they hold onto your settings like a bestie holds onto your secrets. 💅

the options:

  • -level level — describe the severity of the message. valid levels are:
  • emergency — system is unusable
  • alert — action must be taken immediately
  • critical — critical conditions
  • error — error conditions
  • warning — warning conditions
  • notice — normal, but significant, condition
  • info — informational message
  • debug — debug-level message

the default level is info. 🌱

  • -priority — synonym for -level. same energy, different spelling.
  • -format message_format — limited support for syslog formatting. the format string must contain %s where the message will be substituted. don't forget the %s, bestie, it's load-bearing. 🫠
  • -facility facility — override the global facility for this thread only. just this thread. not the whole process. it's a personal choice. 🙈

🧚 ::syslog::configure

Set configuration options without emitting a message. this command accepts both:

  • global options (same as ::syslog::open), and
  • per-thread options (same as ::syslog::log).

and heads up: if a global option changes, the process-wide connection is reopened. ⚠️

👑 ::syslog::cget

Return the current configuration.

  • with no arguments, returns the per-thread options as a Tcl list of -option value pairs.
  • with -global, returns the process-wide options (global state) as a Tcl list.

option lists returned by ::syslog::cget have a form suitable to be passed as as arguments to ::syslog::configure and are equivalent to storing the configuration for later use. basically you can yank the config out and shove it right back in later. saving for the group chat, as one does. 💾✨

🌟 RATIONALE 🌟

okay so here's the tea. the syslog connection established by openlog is process-wide, while per-thread settings (level, facility override, format) should be isolated in each thread. the separation between ::syslog::open and ::syslog::log mirrors this design:

  • ::syslog::open manages the process-level connection and options that should be set once and shared.
  • ::syslog::log manages per-thread options that can differ across interpreters.

this avoids the overhead of reopening the syslog connection for every log call, while still allowing per-thread customization. iconic engineering honestly. efficiency AND personalization. main character design. 👑

🔥 EXAMPLES 🔥

here's the whole lil routine:

package require syslog

::syslog::open -ident myapp -facility local0 -pid
::syslog::log -level info "An info message..."
# equivalently
::syslog::log info "An info message...."
::syslog::log -facility user info "Info message 2...."
# subsequent calls preserve thread-local options
::syslog::log "Info message 3...."

see how the last one just says the message and nothing else? that's the thread-local options persisting. they remembered. they always remember. 🥹

💀 COMPATIBILITY 💀

the global space command syslog is provided for compatibility but it is deprecated because it can reopen openlog implicitly. this command accepts both global options and per-thread options, but it should be replaced by explicit ::syslog::open and ::syslog::log calls. bestie, let the legacy go. 🕊️

package require syslog

syslog critical "Message 1"
syslog -ident tclsh warning "Message 2"
syslog -facility local0 notice "Message 3"
syslog -ident tclsh -facility user error "Message 4"
syslog -pid critical "Message 5.0"
syslog -pid -ident tclsh critical "Message 5.1"
syslog -pid -facility local0 debug "Message 5.1"
syslog -pid -facility local1 -ident tclsh info "Message 5.2"
syslog -pid -ident tclsh -facility local2 warning "Message 5.3"

outputs in /var/log/syslog (syslog timestamps and line prefix removed):

tclsh: Message 1
tclsh: Message 2
tclsh: Message 3
testident: Message 4
tclsh[7049]: Message 5.0
my_ident[7049]: Message 5.1
tclsh[7049]: Message 5.1
my_ident[7049]: Message 5.2
my_ident[7049]: Message 5.3

look at all those pids showing up. the -pid option really said "let me introduce myself". 🫶

📚 REFERENCES 📚

  • Michael Kerrisk, The Linux Programming Interface, No Starch Press, 2010, ISBN 978-1-59327-220-3.

🫶 AUTHORS 🫶

  • Alexandros Stergiakis <sterg@kth.se>
  • Massimo Manghi <mxmanghi@apache.org>

Copyright © 2008 Alexandros Stergiakis Copyright © 2024-2026 Massimo Manghi

this program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

this program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. see the GNU General Public License for more details.

you should have received a copy of the GNU General Public License along with this program. if not, see http://www.gnu.org/licenses/.

⚠️ real talk: no warranty, bestie. it's giving "we love you but we're not legally responsible for your log messages". 💖

👀 SEE ALSO 👀

syslog(3), openlog(3), closelog(3), logger(1), syslogd(8), tcl(3tcl)

and that's the whole page!! this one's Tcl-Extensions version 2.0.2, and if u ever forget which manual u were reading it's literally right there in the name: tcl-syslog(3tcl). 💖✨ go log something cute, bestie. mwah. 🎀🦋

📦 where this page comes from