strlog(9f) [opensolaris man page]
strlog(9F) Kernel Functions for Drivers strlog(9F) NAME
strlog - submit messages to the log driver SYNOPSIS
#include <sys/stream.h> #include <sys/strlog.h> #include <sys/log.h> int strlog(short mid, short sid, char level, unsigned short flags, char *fmt, ...); INTERFACE LEVEL
Architecture independent level 1 (DDI/DKI). PARAMETERS
mid Identification number of the module or driver submitting the message (in the case of a module, its mi_idnum value from mod- ule_info(9S)). sid Identification number for a particular minor device. level Tracing level for selective screening of low priority messages. Larger values imply less important information. flags Valid flag values are: SL_ERROR Message is for error logger. SL_TRACE Message is for trace. SL_NOTIFY Mail copy of message to system administrator. SL_CONSOLE Log message to console. SL_FATAL Error is fatal. SL_WARN Error is a warning. SL_NOTE Error is a notice. fmt printf(3C) style format string. %e, %g, and %G formats are not allowed but %s is supported. DESCRIPTION
The strlog() function expands the printf(3C) style format string passed to it, that is, the conversion specifiers are replaced by the actual argument values in the format string. The 32-bit representations of the arguments (up to NLORGARGS) follow the string starting at the next 32-bit boundary following the string. Note that the 64-bit argument will be truncated to 32-bits here but will be fully repre- sented in the string. The messages can be retrieved with the getmsg(2) system call. The flags argument specifies the type of the message and where it is to be sent. strace(1M) receives messages from the log driver and sends them to the standard output. strerr(1M) receives error messages from the log driver and appends them to a file called /var/adm/streams/error.mm-dd, where mm-dd identifies the date of the error message. RETURN VALUES
The strlog() function returns 0 if it fails to submit the message to the log(7D) driver and 1 otherwise. CONTEXT
The strlog() function can be called from user, interrupt, or kernel context. FILES
/var/adm/streams/error.mm-dd Error messages dated mm-dd appended by strerr(1M) from the log driver SEE ALSO
strace(1M), strerr(1M), getmsg(2), log(7D), module_info(9S) Writing Device Drivers STREAMS Programming Guide SunOS 5.11 16 Jan 2006 strlog(9F)
Check Out this Related Man Page
log(7D) Devices 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 logging and event tracing processes (see strerr(1M), and strace(1M)). 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(): 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 message. sid is an internal sub-id number usually used to identify 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 log- ger), SL_FATAL (advisory notification of a fatal error), and SL_NOTIFY (request that a copy of the message be mailed to the system admin- istrator). 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 struc- ture. 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 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: 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 mes- sages 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 SunOS 5.10 11 Mar 1998 log(7D)