Index for Section 7

Alphabetical listing for S

Bottom of page

strlog(7)
NAME
  strlog, log - STREAMS log driver driver

SYNOPSIS
  #include <sys/strlog.h>
  int strlog(
	  short mid,
	  short sid,
	  char level,
	  ushort flags
	  char fmt,
	  [,value]...);

PARAMETERS
  mid	    Specifies the STREAMS module ID number for the driver or module
	    submitting the log message.

  sid	    Specifies the sub-ID number of a  minor device associated with
	    the STREAMS module or driver identified by mid.

  level	    Specifies a level for screening lower-level event messages from a
	    tracer.

  flags	    Contains several flags that can be set in various combinations.
	    The flags are as follows:

	    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  Provides a notification of a fatal error.

	    SL_NOTIFY Makes a request to mail a copy of a message to the
		      system administrator.
  The following are additional flags.  The strlog interface does not use
  these flags:

	    SL_WARN   The message is a warning.

	    SL_NOTE   The message is a note.

  fmt	    A printf style format string.  This accepts the %x, %l, %o, %u,
	    %d, %c, and %s conversion specifications.

  value	    Numeric or character arguments for process-specific information.
	    There is no maximum number of arguments that can be specified.

DESCRIPTION
  The STREAMS log driver allows user-level processes, and STREAMS drivers and
  modules, to perform error logging and event tracing.	This is done via a
  user interface and a kernel interface.

  The interface that this driver presents to user-level processes is a subset
  of the ioctl() system calls and STREAMS message formats.  These processes
  can be error loggers, trace loggers, or other user processes, that generate
  error or event messages.  The user interface collects log messages from the
  log driver, and also generates log messages from user processes.

  The driver also accepts log messages from STREAMS drivers and modules in
  the kernel via its function call interface.  The kernel interface enters
  requests or calls from STREAMS drivers and modules into log messages.

  Kernel Interface

  STREAMS drivers and modules generate log messages by calls to the strlog()
  function.  Definitions used in these calls are contained in the log_ctl
  structure in the </sys/strlog.h> header file.	 The SYNOPSIS section
  describes the kernel interface.

  User Interface

  User processes access the log driver with an open() call to
  /dev/streams/log.  Each open to the device will obtain a separate stream.
  After a process opens /dev/streams/log, it indicates whether it is an error
  logger or trace logger.  It does this by issuing an I_STR ioctl() system
  call containing the appropriate data and control information in a trace_ids
  structure.

    ·  For an error logger, the I_STR ioctl() contains an ic_cmd field of
       I_ERRLOG with no data.

    ·  For a trace logger, the I_STR ioctl() contains an ic_cmd field of
       I_TRCLOG and a data buffer consisting of an array of one or more
       trace_ids structures.

  If any of the fields of the trace_ids structure contain a value of -1,
  /dev/streams/log will accept whatever value it receives in that field.
  Otherwise, strlog only accepts messages only if the values of mid and sid
  are the same as their counterparts in the trace_ids structure, and if the
  message's level is equal to or less than the level value in the trace_ids
  structure.

  Once the logger process has sent the I_STR ioctl() call, the STREAMS log
  driver begins to send log messages matching the restrictions to the logger
  process.  The logger process obtains the log messages via the getmsg(2)
  system call.	The control part of the messages passed in this call includes
  a log_ctl structure, which indicates the mid, sid and level, time in ticks
  since the boot time that the message was submitted, the corresponding time
  in seconds since January 1, 1970, and a sequence number.  The time in
  seconds since January 1, 1970 is provided so that the date and time of the
  message can be easily computed.  The time in ticks since boot time is
  provided so that the relative timing of log messages can be determined.  In
  addition to the information contained in the log_ctl structure, there is
  also a priority indication.

  The priority indication consists of a priority code and a facility code
  (found in /sys/syslog.h). The valid values for priority codes are the
  following, based on the setting(s) in flags:

  LOG_INFO	 If SL_CONSOLE is set in flags.

  LOG_WARNING	 If SL_CONSOLE and SL_WARN are set in flags.

  LOG_CRIT	 If SL_CONSOLE and SL_FATAL are set in flags.

  LOG_ERR	 If SL_CONSOLE and SL_ERROR are set in flags.

  LOG_NOTICE	 If SL_CONSOLE and SL_NOTE are set in flags.

  LOG_DEBUG	 If SL_CONSOLE and SL_TRACE are set in flags.

  The valid values for facility codes are the following:

  LOG_KERN  If the message originates from the kernel.

  LOG_USER  If the message originates from a user process.  However, these
	    processes may sometimes set another facility code value instead.

  A user process, other than an error or trace logger, can send a log message
  to strlog().	The driver will accept only the flags and level fields of the
  log_ctl structure in the control part of the message, and a properly
  formatted data part of the message.  The data part of the message is
  properly formatted if it contains a null-terminated format string, followed
  by any arguments packed one word each after the end of the string.

  A different series of sequence numbers is provided for error and trace
  logging streams.  These sequence numbers are intended to help track the
  delivery of the messages.  A gap in a sequence of numbers indicates that
  the logger process did not successfully deliver them. This can happen if
  the logger process stops sending messages for one reason or another (see
  the strace and strerr command reference pages for more information).	The
  data part of messages contains unexpanded text of the format string (null
  terminated), followed by any arguments packed one word each after the end
  of the string.

EXAMPLES
  The following examples illustrate how to use the strlog interface for some
  basic uses.

   1.  This code example segment illustrates how a STREAMS module can
       generate a console log message:
	    strlog(TMUX,minor(mydev),0,SL_CONSOLE|SL_FATAL,
		   "TMUX driver (minor:%d) suffers resource shortage.",
		   minor(mydev));

   2.  This code example illustrates how a user process can register itself
       with the STREAMS log driver using the ioctl() command, I_ERRLOG.
	    struct strioctl iocerr:

	    iocerr.ic_cmd = I_ERRLOG;
	    iocerr.ic_timout = 0;
	    iocerr.ic_len = 0;
	    iocerr.ic_dp = NULL;
	    ioctl(logfd, I_STR, &iocerr)

NOTES
  Tru64 UNIX does not provide a console logger.	 Note, however, that other
  systems may provide console loggers.

FILES
  /dev/streams/log
	    Specifies the clone interface.

  </sys/strlog.h>
	    Specifies the header file for STREAMS logging.

  </sys/stropts.h>
	    Specifies the header file for STREAMS options and ioctl()
	    commands.


ERRORS
  If any of the following conditions occurs, strlog() driver's ioctl()
  command sets errno to the corresponding value:

  [ENXIO]   The I_TRCLOG ioctl() call did not contain any trace_ids
	    structures.

  [ENXIO]   The I_STR ioctl() call could not be recognized.

  The driver does not return any errors for incorrectly formatted messages
  that user processes send.

RELATED INFORMATION
  Commands: strace(8), strerr(8).

  Interfaces clone(7), streamio(7).

  Functions: getmsg(2), putmsg(2), write(2).

Index for Section 7

Alphabetical listing for S

Top of page