OpenSS7
SS7 for the
Common Man
© Copyright 1997-2007 OpenSS7 Corporation All Rights Reserved.
Last modified: Mon, 28 Apr 2008 12:53:41 GMT
Home TopIndex FirstPrev Next LastMore Download Info FAQ Mail  Home -> Documentation -> Man Pages -> Manpage of STRLOG
Quick Links

Download

SCTP

SIGTRAN

SS7

Hardware

STREAMS

Asterisk

Related

Package

Manual

FAQ

Man Pages

Applications

SS7 Stack

ISDN Stack

SIGTRAN Stack

VoIP Stack

MG Stack

SS7/ISDN Devices

IP Transport

Embedded Systems

OS

Documentation

FAQ

SIGTRAN

Design

Conformance

Performance

References

Man Pages

Manuals

Papers

Home

Overview

Status

Documentation

Resources

About

News

Manpage of STRLOG

Description: Manual Page

Keywords: ss7 ss7/ip ss7 over ip ss7 mtp ss7 sccp ss7 tcap sigtran mtp sccp tcap openss7 acb56 linux telephony pstn linux telephony linux nebs linux compactpci


STRLOG

Section: The OpenSS7 Project Devices (4)
Updated: Thu, 14 Dec 2017 14:51:44 GMT
Index Return to Main Contents

NAME

strlog, log - STREAMS log device

SYNOPSIS

#include <unistd.h>
#include <stropts.h>
#include <strlog.h>
#include <syslog.h>

int fd = open(/dev/strlog, oflag);
int fd = open(/dev/conslog, oflag);

DESCRIPTION

fd
is a file descriptor for an strlog stream opened using the open(2s) system call on one of the following devices:

``/dev/strlog,'' ``/dev/streams/log/strlog''
This clone device is accessible to all users. This device can either be used by a console, error or trace logger, or can be used to generate log messages with putmsg(2).
``/dev/conslog,'' ``/dev/streams/log/conslog''
This non-clone device is accessble to all users. This device can be used to generate log messages to the console with putmsg(2) or write(2s).

The strlog device is characterized by the following behaviour:

The strlog driver is a STREAMS software device driver that provides an interface for the STREAMS console logging (strlogd(8)), error logging (strerr(8)) and event tracing (strace(8)) processes. The strlog driver presents two separate interfaces:

*
A function call interface in the kernel (strlog(9)) through which STREAMS driver and modules submit log messages.
*
A subset of ioctl (streamio(7)) operations and STREAMS messages for interaction with a user-level console logger (strlogd(8)), error logger (strerr(8)), trace logger (strace(8)), or processes that need to submit their own log messages (strlog(1)).

Kernel Interface

The log messages are generated within the kernel by calls to the strlog(9) utility.

User Interface

The strlog driver is opened using the clone interface, /dev/strlog, or the non-clone interface /dev/conslog.

When the specfs(5) file system is mounted on /dev/streams, the clone interface /dev/streams/clone/log, or /dev/streams/log/strlog, may also be used, or the non-cloning device /dev/streams/log/conslog.

Each open of the /dev/strlog device obtains a separate stream to strlog. To receive log messages, a process first notifies the strlog driver whether it is a console logger, an error logger or a trace logger by using the I_STR (streamio(7)) operation.

For the console logger, the I_STR operation has a ic_cmd parameter value of I_CONSLOG with no accompanying data.

For the error logger, the I_STR operation has a ic_cmd parameter value of I_ERRLOG with no accompanying data.

For the trace logger, the I_STR operation has an ic_cmd parameter value of I_TRCLOG, and must be accomplished by a data buffer containing an array of one or more trace_ids structures. Each trace_ids structure specifies a mid, sid and level field from which messages are to be accepted. The strlog(9) subroutine accepts messages whose values in the mid and sid fields 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.

Following is the format of the trace_ids structure:


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

ti_mid
specifies the STREAMS module ID number for this trace id entry. A value of minus one (-1) indicates that this trace id entry applies to any module ID.
ti_sid
specifies the sub-ID number of a minor device (unit) associated with the STREAMS module or driver specified by t_mid. A value of minus one (-1) indicates that this trace id entry applies to any sub-ID.
ti_level
specifies that maximum strlog log level that will be accepted by this trace id entry. A value of minus one (-1) indicates that this trace id entry applies to any log level.
ti_flags
this member is only present for AIX® HP-UX® and OSF/1® (Mentat) implementations and serves no purpose for the user. It is not used to filter trace messages.

If any of the fields of the trace_ids structure contain a value of -1, strlog will accept whatever value it receives in that field. Otherwise, strlog only accepts messages 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.

At most, one console logger, one error logger and one trace logger can be active at a time. After the logger process has identified itself by using the ioctl (streamio(7)) operation, the strlog driver will begin sending messages, subject to the restrictions previously noted. These messages are obtained by using the getmsg(2) system call. The control part of the message contains a log_ctl structure, which specifies the mid, sid, level and flags fields, as well as the time in ticks since boot that the message was submitted, the corresponding time in seconds since Jan. 1, 1970, and a sequence number. The time in seconds since 1970 is provided so that the date and time of the message can be easily computed; 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;
    short   flags;
    long    ltime;
    long    ttime;
    int     seq_no;
    int     pri;
};

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 (unit) associated with the STREAMS module or driver identified by mid.
level
specifies the 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_CONSOLE
message is for the console logger.
SL_ERROR
message is for the error logger.
SL_TRACE
message is for the trace logger.
SL_FATAL
notification of a fatal error.
SL_WARN
message is a warning.
SL_NOTE
message is a note.
SL_NOTIFY
requests to mail a copy of a message to the system administrator.
ltime
time in seconds since January 1, 1970.
ttime
time in ticks since boot time.
seq_no
a sequence number for the log message.
pri
specifies the priority code and 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 LOG_ERR; SL_NOTE, the priority code is LOG_NOTICES; SL_TRACE, LOG_DEBUG; otherwise, LOG_INFO. Messages originating from the kernel have facility code set to LOG_KERN. Most message originating from user processes will have the facility code set to LOG_USER.

Different sequence number are maintained for the error logging and trace logging streams so that gaps in the sequence of messages can be determined. (During times of high message traffic, some message may not be delivered by the logger to avoid tying up system resources).

The data part of the message contains the unexpanded text of the format string (null-terminated), followed by the arguments to the format string (up to the number specified by the NLOGARGS value), aligned on the first word (int) boundary following the format string. The format string can be a maximum of LOGMSGSZ in length. Longer format messages will be truncated.

A process may also send a message of the same structure to the log driver, even if it is not a console, 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 and flags fields. All other fields are filled in by the log driver before being forwarded to the appropriate logger. The data portion must contain a null-terminated format string, of maximum length LOGMSGSZ, and any arguments (up to NLOGARGS) must be packed in an integral number of words (int) each, on the next word (int) boundary following the end of the format string.

In addition, a process may also send a message of the same structure to the console logger using the log_ctl structure and the putmsg(2) system call, or can simply write the data portion of the message using the write(2s) system call.

The strlog(1) facility is provided for issuing console, error and trace log messages from shell scripts. This is similar to the POSIX logger(1) command.

Attempting to issue an I_TRCLOG, I_ERRLOG or I_CONSLOG operation when a logging process of the given type already exists result in the [ENXIO] error being returned. Similarly, [ENXIO] is returned for I_TRCLOG operations without any trace_ids structures, or for any unrecognized I_STR operations. Incorrectly formatted log messages sent to the driver by a user process are silently ignored (no error results).

USAGE

The strlog device can be opened when no other suitable device exists and modules may be pushed on the strlog device.

IOCTLS

The strlog driver only supports streamio(7) I_STR input output controls. TRANSPARENT input output controls are not supported and will result in a return value of [ENXIO]. The strlog drivers supports the following streamio(7) I_STR input ouput controls:

I_TRCLOG

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

I_ERRLOG

Indicates an error logger. No trace_ids is required.

I_CONSLOG

Indicates a console logger. No trace_ids is required.

NOTICES

This device is provided as /dev/strlog instead of /dev/log as is the case for SVR 4.2[1] systems, because Linux already has a non-STREAMS driver called /dev/log.

EXAMPLES

1.
The following is an example of I_ERRLOG notification:

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);

2.
The following is an example of I_TRCLOG notification:

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 = sizeof(tid);
ioc.ic_dp = (char *) tid;
ioctl(log, I_STR, &ioc);

3.
The following is an example of submitting a log message (no arguments):

struct strbuf ctl, dat;
struct log_ctl lc;
char *message = "Honey, I'm 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;
putmsg(log, &ctl, &dat, 0);

DEVICES

/dev/strlog
The external file system STREAMS log device.
/dev/conslog
The external file system console log device.
/dev/streams/log/strlog, /dev/streams/clone/log, /devices/strlog
The specfs(5) shadow special filesystem STREAMS log device.
/dev/streams/log/conslog, /devices/conslog
The specfs(5) shadow special filesystem console log device.

SEE ALSO

open(2s), strerr(8), strace(8), strlogd(8), strlog(9), streamio(7), strlog(1), getmsg(2), putmsg(2), write(2s).

BUGS

strlog has no known bugs.

COMPATIBILITY

The operation of the STREAMS error logger and trace logger are described in the SVR 4.2 SPG[2]. strlog is compatible with systems based on SVR 4.2[1], including AIX®, HP-UX®, OSF/1®, Solaris®, SUPER-UX® and UnixWare®, with the following portability considerations:

---
AIX® does not document the trace_ids and log_ctl structures.
---
HP-UX® does not have a pri field in the log_ctl structure.
---
HP-UX® does not support priority or facility codes.
---
HP-UX® does not suppor the I_CONSLOG input output control.
---
OSF/1® calls this device /dev/streams/log.
---
Solaris®, SUPER-UX® and UnixWare® do not provide the ti_flags field of the trace_ids structure; AIX®, HP-UX® and OSF/1® do.
---
Solaris® declares ltime to be clock32_t or clock_t, and ttime to be time32_t or time_t, depending on a 64 or 32-bit architecture.
---
On most systems, the STREAMS log device is called /dev/log; however, Linux has a BSD-based log device by that name, so the device /dev/strlog is used instead.

CONFORMANCE

SVR 4.2[3], AIX®, HP-UX®, OSF/1®, Solaris®, SUPER-UX® and UnixWare® documentation[4..9].

HISTORY

strlog first appeared in SVR 4[10].

REFERENCES

[1]
SVR 4.2, UNIX® System V Release 4.2 Programmer's Manual, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[2]
SVR 4.2, STREAMS Programmer's Guide, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[3]
SVR 4.2 CR, UNIX® System V Release 4.2 Command Reference Manual, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[4]
AIX® 5L Version 5.1, AIX 5L Version 5.1 Documentation, 2001, (Boulder, Colorado), Internatonal Business Machines Corp., IBM. <http://publibn.boulder.ibm.com/>
[5]
HP-UX® 11i v2, HP-UX 11i v2 Documentation, 2001, (Palo Alto, California), Hewlett-Packard Company, HP. <http://docs.hp.com/>
[6]
Digital® UNIX (OSF/1.2), Digital UNIX Documentation Library, 2003, (Palo Alto, California), Digital Equipment Corporation, Hewlett-Packard Company. <http://www.true64unix.compaq.com/docs/>
[7]
Solaris® 8, Solaris 8 Docmentation, 2001, (Santa Clara, California), Sun Microsystems, Inc., Sun. <http://docs.sun.com/>
[8]
SUPER-UX® Release 9.2, SUPER-UX Release 9.2 Documentation, 1999, NEC Corporation, NEC.
[9]
UnixWare® 7.1.3, UnixWare 7.1.3 (OpenUnix 8) Documentation, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>
[10]
SVR 4, UNIX® System V Release 4 Programmer's Manual, 1990, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.

TRADEMARKS

OpenSS7tm
is a trademark of OpenSS7 Corporation.
Linux®
is a registered trademark of Linus Torvalds.
UNIX®
is a registered trademark of The Open Group.
Solaris®
is a registered trademark of Sun Microsystems.

Other trademarks are the property of their respective owners.

IDENTIFICATION

The OpenSS7 Project: Package OpenSS7 version 0.9.2 released Thu, 14 Dec 2017 14:51:44 GMT.

Copyright©1997-2008OpenSS7 Corp.
All Rights Reserved.
(See roff source for permission notice.)



Index

NAME
SYNOPSIS
DESCRIPTION
Kernel Interface
User Interface
USAGE
IOCTLS
I_TRCLOG
I_ERRLOG
I_CONSLOG
NOTICES
EXAMPLES
DEVICES
SEE ALSO
BUGS
COMPATIBILITY
CONFORMANCE
HISTORY
REFERENCES
TRADEMARKS
IDENTIFICATION

This document was created by man2html, using the manual pages.
Time: 14:51:44 GMT, December 14, 2017
OpenSS7
SS7 for the
Common Man
Home TopIndex FirstPrev Next LastMore Download Info FAQ Mail  Home -> Documentation -> Man Pages -> Manpage of STRLOG
Last modified: Mon, 28 Apr 2008 12:53:41 GMT
© Copyright 1997-2007 OpenSS7 Corporation All Rights Reserved.