*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->HP-UX 11i man pages -> strlog (7)              


 strlog(7)                                                         strlog(7)

 NAME    [Toc]    [Back]
      strlog - STREAMS log driver

 DESCRIPTION    [Toc]    [Back]
      The STREAMS log driver allows user-level processes and STREAMS drivers
      and modules to perform error logging and event tracing. These tasks
      are done via a user interface and a kernel interface.  Further, the
      STREAMS log driver delivers error logging and event tracing messages
      to the Network Tracing and Logging Facility (NetTL) (see nettl(1M),
      netfmt(1M), and nettlconf(1M)).

      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

      The log messages accepted by the log driver are also delivered to
      NetTL.  NetTL can be used to control which types of messages to log,
      and to format and filter the logged messages.

    Kernel Interface    [Toc]    [Back]
      STREAMS drivers and modules generate log messages by calls to the
      strlog function.

           #include <sys/strlog.h>

           int strlog (mid, sid, level, flags, fmt [, value ]...);
           short mid;
           short sid;
           char level;
           ushort flags;
           char *fmt;
           int value;

      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.

 Hewlett-Packard Company            - 1 -   HP-UX 11i Version 2: August 2003

 strlog(7)                                                         strlog(7)

      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 will be printed to the

                     SL_FATAL       Provides a notification of a fatal

                     SL_NOTIFY      Makes a request to mail a copy of a
                                    message to the system administrator.

                     The following are additional flags.  These flags are
                     not used by strerr or strace.  However, they are used
                     to map STREAMS messages to NetTL messages as described
                     below in "STREAMS-NetTL Link" section.

                     SL_WARN        The message is a warning.

                     SL_NOTE        The message is a note.

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

      values    are numeric or character arguments for the format string.
                There is no maximum number of arguments that can be

    User Interface    [Toc]    [Back]
      User processes access the log driver with an open() call to
      /dev/strlog.  Each open to the device will obtain a separate stream.
      After a process opens /dev/strlog, it indicates whether it is an error
      logger or trace logger.  It does this by issuing an I_STR ioctl()
      system call with the appropriate value in the ic_cmd field of the
      strioctl structure, and the appropriate data and control information
      in a trace_ids structure:

           struct trace_ids {
               short   ti_mid;
               short   ti_sid;
               char    ti_level;
               short   ti_flags;

 Hewlett-Packard Company            - 2 -   HP-UX 11i Version 2: August 2003

 strlog(7)                                                         strlog(7)

      The values for ic_cmd are:

      I_ERRLOG       Indicates an error logger.  No trace_ids data is

      I_TRCLOG       Indicates a trace logger.  A data buffer consisting of
                     an array of one or more trace_ids structures must be

      If any of the fields of the trace_ids structure contain a value of -1,
      /dev/strlog 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() system call.  The control part of the messages passed in
      this call includes a log_ctl structure:

           struct log_ctl {
               short   mid;
               short   sid;
               char    level;
               short   flags;
               long    ltime;
               long    ttime;
               int     seq_no;

      The log_ctl structure 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.

      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 up to three 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

 Hewlett-Packard Company            - 3 -   HP-UX 11i Version 2: August 2003

 strlog(7)                                                         strlog(7)

      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 strace(1M) and strerr(1M) command reference
      pages for more information).  The data part of messages contains text
      of the format string (null terminated), followed by up to three

    STREAMS-NetTL Link    [Toc]    [Back]
      Both STREAMS error logging and event tracing messages are mapped to
      NetTL logging messages, and are delivered to NetTL.  NetTL classifies
      messages into four log classes: DISASTER, ERROR, WARNING, and
      INFORMATIVE.  The NetTL log class is determined by the flags according
      to the following rule:

           If (flags & SL_ERROR)           NetTL log class
               if (flags & SL_FATAL) ====>  DISASTER
               if (flags & SL_WARN)  ====>  WARNING
               if (flags & SL_NOTE)  ====>  INFORMATIVE
               otherwise             ====>  ERROR
               all messages          ====>  INFORMATIVE

      As a default, only DISASTER and ERROR messages are logged.  This
      setting can be altered by the nettl command or the nettlconf command
      (see nettl(1M) and nettlconf(1M)).

      The STREAMS subsystem ID used by NetTL is STREAMS.

      The messages logged by NetTL facility can be formatted to a readable
      form by the netfmt command (see netfmt(1M)).  The netfmt accepts a
      filter configuration file, which can be used to filter on STREAMS
      module ID and sub-ID.  The filter configuration file syntax for
      STREAMS is the following:

           STREAMS module_id sub_id

      module_id and sub_id can be a decimal number or ``*'' as a wild card.

 RETURN VALUE    [Toc]    [Back]
      Unless specified otherwise, upon successful completion, the strlog
      ioctl() commands return a value of 0 (zero).  Otherwise, a value of -1
      is returned.

 ERRORS    [Toc]    [Back]
      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

 Hewlett-Packard Company            - 4 -   HP-UX 11i Version 2: August 2003

 strlog(7)                                                         strlog(7)

      [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.

 EXAMPLES    [Toc]    [Back]
      The following examples illustrate some basic uses for the strlog

      This code example segment shows how a STREAMS module causes a message
      to be printed to the console:

                  "TMUX driver (minor:%d) suffers resource shortage.",

      This code example shows how a user process registers itself with the
      STREAMS log driver using the ioctl() command, I_ERRLOG.

           struct strioctl iocerr:
           int logfd;

           if ((logfd = open("/dev/strlog", O_RDWR)) == -1) {
                printf("Cannot open /dev/strlog\n");

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

      This code example shows a user-level process sending a message to the
      strlog driver.

           struct strbuf control, data;
           struct log_ctl log;
           char *warning = "Fatal error for user level process";
           int logfd;

           if ((logfd = open("/dev/strlog", O_RDWR)) == -1) {
                printf("Cannot open /dev/strlog\n");

           control.len = control.maxlen = sizeof(log);
           control.buf = (char *)&lc;

           data.len = data.maxlen = strlen(warning);
           data.buf = warning;

 Hewlett-Packard Company            - 5 -   HP-UX 11i Version 2: August 2003

 strlog(7)                                                         strlog(7)

           lc.level = 2;
           lc.flags = SL_FATAL|SL_CONSOLE;

           putmsg(logfd, &control, &data, 0);

      The following examples illustrate how to use the NetTL facility for
      the STREAMS.  See nettl(1M), netfmt(1M), nettlconf(1M) for the general
      NetTL usage.  The STREAMS subsystem ID used by NetTL is STREAMS.

      The netfmt accepts a filter configuration file as a command argument.
      The following filter configuration file example is used to format the
      messages whose module ID is 1 and sub-ID is 100:

           STREAMS    1    100

      This filter configuration file example can be used to display all the
      messages whose module ID is 2 and all the messages whose sub-ID is

           STREAMS    2    *
           STREAMS    *    101

 FILES    [Toc]    [Back]
      /dev/strlog              specifies the clone interface.

      <sys/strlog.h>           specifies the header file for streams

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

 SEE ALSO    [Toc]    [Back]
      strace(1M), strerr(1M), clone(7), streamio(7), getmsg(2), putmsg(2),
      write(2), open(2), ioctl(2), nettl(1M), netfmt(1M), nettlconf(1M).

 Hewlett-Packard Company            - 6 -   HP-UX 11i Version 2: August 2003
[ Back ]
 Similar pages
Name OS Title
telm HP-UX STREAMS Telnet slave (pseudo-terminal) driver, STREAMS Telnet master driver (used by telnetd only), respective
tels HP-UX STREAMS Telnet slave (pseudo-terminal) driver, STREAMS Telnet master driver (used by telnetd only), respective
dlpi Tru64 STREAMS pseudodevice driver for bridging BSD Drivers to STREAMS
dlb Tru64 STREAMS pseudodevice driver for bridging BSD Drivers to STREAMS
sad IRIX STREAMS Administrative Driver
sad HP-UX STREAMS Administrative Driver
sad Tru64 STREAMS Administrative Driver
ipx IRIX IPX Streams Multiplexor Driver
ptm HP-UX STREAMS master pty (pseudo-terminal) driver
clone IRIX open any minor device on a STREAMS driver
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service