WindNet STREAMS provides two utilities, strace and strerr, as well as the strlog( )routine for debugging and administering STREAMS modules and drivers. Any module or driver in any stream can call the STREAMS logging function, strlog( ), which sends formatted text to the error logger, strerr, or the trace logger, strace, or both.

The WindNet STREAMS strace utility can be called with or without arguments. When it is called without any arguments, it prints all event trace messages from all drivers and modules in the system to a file, streams.log, in the directory specified by the configuration constant STREAMS_STRACE_OUTPUT_DIR in configAll.h. The strace utility obtains these messages from the STREAMS log driver. (For more information about configuring this utility into VxWorks, see §6.1 Configuring VxWorks for WindNet STREAMS.)

If you call strace with arguments, you must use a set of triplets--mid, sid and level, in that order--as shown in the following command:

-> sp strace "<mid> <sid> <level>"

Each triplet indicates that tracing messages are to be received from the module specified by mid (module ID), by sid (sub-ID, usually indicating a minor device number), and by level (a tracing priority level equal to or less than the specified value). The token all is substituted for mid, sid, and level when you want to remove restrictions for that attribute.

If the module ID is provided to strace, then strace output is sent to the file module-id.log in STREAMS_STRACE_OUTPUT_DIR. The module ID is a unique identification number that identifies the STREAMS driver or module in the STREAMS subsystem. It is obtained from the module-id field in the module_info structure. Every STREAMS driver or module has a module_info structure.

The following command traces all the trace messages from the STREAMS driver or module which has its module ID as mid, for all sub-IDs, and all trace levels:

-> sp strace "<mid> all all"

The following command traces the trace messages from the STREAMS driver or module that has a module ID of 5232, a sub ID of 0, and a tracing level of 1:

-> sp strace "5232 0 1"

Sample output from this strace call:

1 12:00:00 1 ... 5232 0 loop: This is a sample strlog output
2 12:00:01 1 ... 5232 0 loop: From VxWorks STREAMS

The fields in strace output, as shown above, are the message sequence number, timestamp, tracing level, module ID, sub-ID, module name, and the actual message.

The strerr utility prints error messages from all the STREAMS drivers and modules in a system. The resulting error.log file resides in the directory specified by the configuration constant STREAMS_STRERR_OUTPUT_DIR in configAll.h. (For information about configuring this utility into VxWorks, see §6.1 Configuring VxWorks for WindNet STREAMS.) The strerr utility pursues only comprehensive traces of all error messages in a system; it cannot be used for traces from a single STREAMS driver or module.

The format of an error message provided by strerr is as follows:

<seq> <time> <ticks> <flags> <mid> <sid> <text>
<seq> error sequence number
<time> time of message
<ticks> time of message in machine ticks since boot
<flags> 
T: the message was also sent to a tracing tasks
F: Indicates a fatal error
<mid> Module-Id number of source
<sid> Sub-Id number of source
<text> formatted text of the error message 

The following command traces all the error messages from all STREAMS drivers and modules in the system and appends them to the log file error.log:

-> sp strerr  

Sample output from strerr:

1 00:00:43 3736781 TF 5232 0 loop:  "This sample message has the FATAL bit set" 

The fields in strerr output, as shown above, are the message sequence number (1), timestamp (00:00:43), time of message in machine ticks (3736781) , flags (TF), module ID (5232), sub-ID (0), and text.

The strlog( )routine enables STREAMS drivers and modules to submit messages to the log device from within the STREAMS subsystem. The format of the call is:

strlog ( short mid, short sid, char level, unsigned short flags, char *fmt, ...)

The arguments to strlog( ) are as follows:

Identification number of the module or driver submitting the message. The number is the mi_idnum value from the module_info structure.

Sub-ID number such as the minor number of a device.

Tracing level for selective screening of low priority messages. Larger values imply less important messages.

Valid flags are:

SL_ERROR

Message is for error logger. The strerr utility would receive this message.

SL_TRACE

Message is for trace logger. The strace utility would receive this message.

SL_CONSOLE

Log message to console.

SL_FATAL

Error is fatal.

SL_WARN

Error is a warning

SL_NOTE

Error is a notice.

The strlog( ) routine submits formatted messages to the log driver. The flags argument specifies the type of the message and where it is to be sent. The strace application receives messages with the SL_TRACE flag set from the log driver and sends them to the log file. The strerr application receives error messages from the log driver and appends them to the error log file.

This routine writes the string to the log driver. An strace application tracing for this moduleID of mid and sub-ID of 0 receives the string "This is a strace test".

strlog (mid, 0, 1, SL_TRACE,"This is a strace test\n");

This routine writes the string to the log driver. An strerr application receives the string "This is a strerr test".

strlog (mid, 0, 1, SL_ERROR,"This is a strerr test\n");

This statement writes the string to both the strace and strerr applications.

strlog (mid,0,1,SL_TRACE|SL_ERROR,"This is a test\n");