LOG(4D) Devices LOG(4D)
NAME
log - interface to STREAMS error logging and event tracing
SYNOPSIS
#include <sys/strlog.h> #include <sys/log.h>DESCRIPTION
log is a STREAMS software device driver that provides an interface for
console logging and for the STREAMS error logging and event tracing
processes (see
strerr(8), and
strace(8)).
log presents two separate
interfaces: a function call interface in the kernel through which STREAMS
drivers and modules submit log messages; and a set of
ioctl(2) requests and
STREAMS messages for interaction with a user level console logger, an error
logger, a trace logger, or processes that need to submit their own log
messages.
Kernel Interface
Log messages are generated within the kernel by calls to the function
strlog(9F).
User Interface
log is implemented as a cloneable device, it clones itself without
intervention from the system clone device. Each open of
/dev/log obtains a
separate stream to
log. In order to receive log messages, a process must
first notify
log whether it is an error logger, trace logger, or console
logger using a STREAMS I_STR
ioctl(2) call (see below). For the console
logger, the I_STR
ioctl(2) has an
ic_cmd field of I_CONSLOG, with no
accompanying data. For the error logger, the I_STR
ioctl(2) has an
ic_cmd field of I_ERRLOG, with no accompanying data. For the trace logger, the
ioctl(2) has an
ic_cmd field of I_TRCLOG, and must be accompanied by a data
buffer containing an array of one or more struct
trace_ids elements.
struct trace_ids {
short ti_mid;
short ti_sid;
char ti_level;
};
Each
trace_ids structure specifies a
mid,
sid, and
level from which
messages will be accepted.
strlog(9F) will accept messages whose
mid and
sid exactly match those in the
trace_ids structure, and whose level is less
than or equal to the level given in the
trace_ids structure. A value of -1
in any of the fields of the
trace_ids structure indicates that any value is
accepted for that field.
Once the logger process has identified itself using the
ioctl(2) call,
log will begin sending up messages subject to the restrictions noted above.
These messages are obtained using the
getmsg(2) function. The control part
of this message contains a
log_ctl structure, which specifies the
mid,
sid,
level,
flags, time in ticks since boot that the message was submitted, the
corresponding time in seconds since Jan. 1, 1970, a sequence number, and a
priority. The time in seconds since 1970 is provided so that the date and
time of the message can be easily computed, and the time in ticks since
boot is provided so that the relative timing of log messages can be
determined.
struct log_ctl {
short mid;
short sid;
char level; /* level of message for tracing */
short flags; /* message disposition */
#if defined(_LP64) || defined(_I32LPx)
clock32_t ltime; /* time in machine ticks since boot */
time32_t ttime; /* time in seconds since 1970 */
#else
clock_t ltime;
time_t ttime;
#endif
int seq_no; /* sequence number */
int pri; /* priority = (facility|level) */
};
The priority consists of a priority code and a facility code, found in
<
sys/syslog.h>. If SL_CONSOLE is set in
flags, the priority code is set as
follows:
+o If SL_WARN is set, the priority code is set to LOG_WARNING
+o If SL_FATAL is set, the priority code is set to LOG_CRIT
+o If SL_ERROR is set, the priority code is set to LOG_ERR
+o If SL_NOTE is set, the priority code is set to LOG_NOTICE
+o If SL_TRACE is set, the priority code is set to LOG_DEBUG
+o If only SL_CONSOLE is set, the priority code is set to LOG_INFO
Messages originating from the kernel have the facility code set to
LOG_KERN. Most messages originating from user processes will have the
facility code set to LOG_USER.
Different sequence numbers are maintained for the error and trace logging
streams, and are provided so that gaps in the sequence of messages can be
determined (during times of high message traffic some messages may not be
delivered by the logger to avoid hogging system resources). The data part
of the message contains the unexpanded text of the format string (null
terminated), followed by NLOGARGS words for the arguments to the format
string, aligned on the first word boundary following the format string.
A process may also send a message of the same structure to
log, even if it
is not an error or trace logger. The only fields of the
log_ctl structure
in the control part of the message that are accepted are the
level,
flags,
and
pri fields; all other fields are filled in by
log before being
forwarded to the appropriate logger. The data portion must contain a null
terminated format string, and any arguments (up to NLOGARGS) must be
packed, 32-bits each, on the next 32-bit boundary following the end of the
format string.
ENXIO is returned for I_TRCLOG
ioctl(2) without any
trace_ids structures,
or for any unrecognized
ioctl(2) calls. The driver silently ignores
incorrectly formatted log messages sent to the driver by a user process (no
error results).
Processes that wish to write a message to the console logger may direct
their output to
/dev/conslog, using either
write(2) or
putmsg(2).
Driver Configuration
The following driver configuration properties may be defined in the
log.conf file:
msgid=
1 Each message will be preceded by a message ID as described in
syslogd(8).
msgid=
0 Message IDs will not be generated.
FILES
/dev/log Log driver.
/dev/conslog Write only instance of the log driver, for console
logging.
/kernel/drv/log.conf Log configuration file.
EXAMPLES
Example 1 I_ERRLOG registration.
struct strioctl ioc;
ioc.ic_cmd = I_ERRLOG;
ioc.ic_timout = 0; /* default timeout (15 secs.) */
ioc.ic_len = 0;
ioc.ic_dp = NULL;
ioctl(log, I_STR, &ioc);
Example 2 I_TRCLOG registration.
struct trace_ids tid[2];
tid[0].ti_mid = 2;
tid[0].ti_sid = 0;
tid[0].ti_level = 1;
tid[1].ti_mid = 1002;
tid[1].ti_sid = -1; /* any sub-id will be allowed */
tid[1].ti_level = -1; /* any level will be allowed */
ioc.ic_cmd = I_TRCLOG;
ioc.ic_timout = 0;
ioc.ic_len = 2 * sizeof(struct trace_ids);
ioc.ic_dp = (char *)tid;
ioctl(log, I_STR, &ioc);
Example 3 Submitting a log message (no arguments)
struct strbuf ctl, dat;
struct log_ctl lc;
char *message = "Don't forget to pick up some milk "
"on the way home";
ctl.len = ctl.maxlen = sizeof(lc);
ctl.buf = (char *)&lc;
dat.len = dat.maxlen = strlen(message);
dat.buf = message;
lc.level = 0;
lc.flags = SL_ERROR|SL_NOTIFY;
putmsg(log, &ctl, &dat, 0);
SEE ALSO
getmsg(2),
ioctl(2),
putmsg(2),
write(2),
strace(8),
strerr(8),
strlog(9F) STREAMS Programming Guideillumos July 8, 2022 illumos