log(7d)
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 log-
ging and event tracing processes (see strerr(1M), and
strace(1M)). log presents two separate interfaces: a func-
tion 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 mes-
sages.
Kernel Interface
log messages are generated within the kernel by calls to the
function strlog():
strlog(short mid,
short sid,
char level,
ushort_t flags,
char *fmt,
unsigned arg1...
);
Required definitions are contained in <sys/strlog.h>,
<sys/log.h>, and <sys/syslog.h>. mid is the STREAMS module
id number for the module or driver submitting the log mes-
sage. sid is an internal sub-id number usually used to iden-
tify a particular minor device of a driver. level is a
tracing level that allows for selective screening out of low
priority messages from the tracer. flags are any combination
of SL_ERROR (the message is for the error logger),
SL_TRACE (the message is for the tracer), SL_CONSOLE (the
message is for the console logger), SL_FATAL (advisory
notification of a fatal error), and SL_NOTIFY (request that
a copy of the message be mailed to the system administra-
tor). fmt is a printf(3C) style format string, except that
%s, %e, %E, %g, and %G conversion specifications are not
handled. Up to NLOGARGS (in this release, three) numeric or
character arguments can be provided.
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 call (see below). For
the console logger, the I_STR ioctl has an ic_cmd field of
I_CONSLOG, with no accompanying data. For the error logger,
the I_STR ioctl has an ic_cmd field of I_ERRLOG, with no
accompanying data. For the trace logger, the ioctl 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 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 mes-
sage contains a log_ctl structure, which specifies the mid,
sid, level, flags, time in ticks since boot that the mes-
sage 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: If SL_WARN is
set, the priority code is set to LOG_WARNING; If SL_FATAL is
set, the priority code is set to LOG_CRIT; If SL_ERROR is
set, the priority code is set to LOG_ERR; If SL_NOTE is
set, the priority code is set to LOG_NOTICE; If SL_TRACE
is set, the priority code is set to LOG_DEBUG; 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 ioctls without any trace_ids
structures, or for any unrecognized ioctl 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
If msgid=1, each message will be preceded by a
message ID as described in syslogd(1M).
msgid=0
If msgid=0, message IDs will not be generated.
This property is unstable and may be removed in a
future release.
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 of 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);
FILES
/dev/log
Log driver.
/dev/conslog
Write only instance of the log driver, for console
logging.
/kernel/drv/log.conf
Log configuration file.
SEE ALSO
strace(1M), strerr(1M), intro(3), getmsg(2), ioctl(2),
putmsg(2), write(2), printf(3C), strlog(9F)
STREAMS Programming Guide
Man(1) output converted with
man2html