Next: gauche.mop.instance-pool
- Instance pools, Previous: gauche.listener
- Listener, Up: Library modules - Gauche extensions [Contents][Index]
gauche.logger
- User-level loggingProvides a simple interface to log the program’s activity.
The information can be written to the specified file,
or to the system logger using syslog(3)
.
When a file is used, syslog-like prefix string is added
to each message, which is configurable. It can also takes care of
locking of the file (see the description of lock-policy
below).
{gauche.logger}
Represents the destination of log messages.
There’s one implicit global <log-drain>
instance, which is
used by default. However, you can create as many instances
by make
method as you want, in case if you want to log
to more than one destination.
Designates destination of log output. It can be one of the following values.
Pathname of the log file. The output is written to it.
current-error
#t
The output goes to the current error port.
current-output
The output goes to the current output port.
syslog
The output is sent to the system logger.
ignore
Make log-format
does nothing.
#f
The output is turned to a string and returned from
log-format
.
By default, this slot is #f
.
Specifies the prefix string that is attached to the beginning of every
message. If the message spans to several lines, the prefix is
attached to each line. The value of this slot can also be a procedure
that takes <log-drain>
object and returns a string to be used as
the prefix. The procedure is called every time prefix is needed.
When the path
slot is a symbol syslog
, the value of this slot
is ignored. System logger will attach an appropriate prefix.
When the value of the prefix slot is a string, the following character sequences
have special meanings and replaced by log-format
for appropriate
information when written out.
~T
Current time, in the format of "Mmm DD hh:mm:ss" where "Mmm" is an abbreviated month, "DD" is the day of month, "hh", "mm" and "ss" are hours (in 24 hour basis), minutes and seconds, respectively. This format is compatible with system logs.
~Y
Current 4-digit year.
~P
The program name. The default value is the basename of
(car (command-line))
(see Command-line arguments),
but you can change it by the program-name
slot described below.
~$
The process id of this program.
~U
The name of the effective user of the process.
~H
The hostname the process is running.
The default value of this slot is "~T ~P[~$]:
". For example,
if a string "this is a log message.\nline 2\nline 3" is given as the
message, it produces something like the following log entry.
Sep 1 17:30:23 myprogram[441]: this is a log message Sep 1 17:30:23 myprogram[441]: line 2 Sep 1 17:30:23 myprogram[441]: line 3
Specifies the program name written by ~P
directive of
the prefix slot.
Specifies the way the log file should be locked.
If the value of this slot is a symbol fcntl
,
the log file is locked using
fcntl() (see gauche.fcntl
- Low-level file operations).
If the value is a symbol file
, the log file is locked by
creating auxiliary lock file, whose name is generated by appending ".lock"
after the log file path. The logging
process needs a write permission to the log file directory.
Note that if the process is killed forcibly during writing the
log file, a stale lock file may remain. Log-format
silently removes the lock file if it is unusually old (currently 10 minutes).
If the value is #f
, no locking is performed.
The default value is fcntl
, except MacOSX which doesn’t
support fcntl()-style locking and thus file
is default.
The locking isn’t performed if the destination is not a file.
The value of these slots are used when the destination of the drain
is the system logger. See gauche.syslog
- Syslog, for the detailed information
about these values. The default values of these slots
are LOG_PID
, LOG_USER
and LOG_INFO
, respectively.
{gauche.logger}
Sets the destination of the default log message to the path path.
It can be a string or a boolean, as described above.
You can also set prefix and program name by corresponding keyword
arguments. See the <log-drain>
above for those parameters.
Despite its name, this function doesn’t open the specified file
immediately. The file is opened and closed every time log-format
is called.
{gauche.logger}
When called with no argument, returns the current default log-drain
log-format
uses when the explicit drain is omitted.
It may return #f
if the default log drain hasn’t been
opened by log-open
.
Calling with new <log-drain>
object or
#f
alters the default log-drain.
You can also use parameterize
(Parameters) to change
the log drain temporary.
{gauche.logger}
Formats a log message by format and arg …, by using
format
(see Output). In the first form, the output goes
to the default destination. In the second form, the output goes to
the specified drain.
The file is opened and closed every time. You can safely move
the log file while your program that touches the log file is running.
Also log-format
acquires a write lock of the log file by
sys-fcntl
(see gauche.fcntl
- Low-level file operations).
If the first form of log-format
is called before log-open
is called, log-format
does nothing.
It is useful to embed debug stubs in your code; once your code is
past the debugging stage, you just comment out log-open
and
the code runs without logging.
Next: gauche.mop.instance-pool
- Instance pools, Previous: gauche.listener
- Listener, Up: Library modules - Gauche extensions [Contents][Index]