OpenSS7
SS7 for the
Common Man
© Copyright 1997-2007 OpenSS7 Corporation All Rights Reserved.
Last modified: Mon, 28 Apr 2008 12:53:43 GMT
Home TopIndex FirstPrev Next LastMore Download Info FAQ Mail  Home -> Documentation -> Man Pages -> Manual Page
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

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


STRACE

Section: The OpenSS7 Project Administration (8)
Updated: Wed, 16 Aug 2017 02:05:51 GMT
Index Return to Main Contents

NAME

strace - write STREAMS event trace messages to the standard output

SYNOPSIS

strace [options] [-nqDv] [{-d|--directory[=]}directory] [{-p|--pidfile[=]}[pidfile]] [{-l|--logdev[=]}[logdevice]] [{-D|--debug[=]}[LEVEL]] [{-v|--verbose[=]}[LEVEL]] [mid sid level] ...
strace {-h|--help}
strace {-V|--version}
strace {-C|--copying}

DESCRIPTION


The strace receives trace event messages from the STREAMS log driver (log(4)) and writes these messages to standard output. When run as a daemon, strace appends these messages to a log file. The error log files produced reside in the directory /var/adm/streams or /var/log/streams, or a user-specified directory, and are named trace.mm-dd, where mm is the month and dd is the day of the messages contained in each log file.

By default, strace without arguments writes all STREAMS trace messages from all drivers and modules. strace with command-line arguments limits the trace messages received.

Messages that appear in the trace log are intended to report debugging information that assists with troubleshooting a running STREAMS module or driver. Messages indicating the total failure of a STREAMS driver or module should have the F flag set. Those messages requiring the immediate attention of the administrator should have the N flag set, which causes the console logger to send the message to that person by way of the mail(1) command. The priority level usually has no meaning in the error log, but does have meaning if the message is sent to the trace process. Messages of lower priority levels can be filtered out.

Once initiated, the strace daemon continues to execute until terminated by the user. Usually, the strace daemon is executed asynchronously.

OPTIONS

-d, --directory directory
Specifies a directory to contain the messages. Default is to search for /var/adm/streams and then /var/log/streams .
-n, --noforeground
Daemonize, do not run in the foreground, print output to outfile and error logs to errfile. This option is most usefull for debugging strace.
-b, --basename basename
Specify the log file basename. Default is trace .
-o, --outfile outfile
Specifiy the log file output name. When run as a daemon, the default is basename . mm-dd , where mm-dd is the current month and day of month. When run in the foreground, the default is ignored and all output is to stdout. When specified, standard output is redirected to the specified file regardless of whether strace is being run in the foreground or as a daemon.
-e, --errfile errfile
Specify the error file output name. When run as a daemon, the default is /dev/null and all errors are logged to syslogd(8). When run in the foreground, the default is ignored and all errors are logged to stderr. When specified, standard error is redirected to the specified file regardless of whether strace is being run in the foreground or as a daemon.
-p, --pidfile pidfile
Specify the pid file output name. Default is /var/run/strace.pid . When run in the foreground, the default is ignored.
-l, --logdev logdevice
Specifies the log device. Default is to search /dev/streams/strlog , /dev/streams/log , /dev/strlog and /dev/log .
-q, --quiet
Suppresses normal output. This option is equivalent to --verbose=0.
-D, --debug [level]
Increase or specify the debug output level. When a debug level has been specified, strace will log to stdout, prints debug messages to stderr, and will not place itself in the background. This option may be repeated.
-v, --verbose [level]
Increase or specify the verbosity level of the output. This option may be repeated.
-h, --help
When this option is encountered, strace displays usage information on stdout and exits. No further processing of options or arguments is performed and no actions are taken.
-V, --version
When this option is encountered, strace displays version information on stdout and exits. No further processing of options or arguments is performed and no actions are taken.
-C, --copying
When this option is encountered, strace displays copying and copyright information on stdout and exits. No further processing of options or arguments is performed and no actions are taken.

ARGUMENTS

The arguments, which must be specified in groups of three, are:

mid
Specifies the STREAMS module identification number from the streamtab entry.
sid
Specifies a sub-identification number (often corresponding to a minor device).
level
Specifies a tracing priority level. strace gets messages of a level equal to or less than the value specified by level. Only positive integer values are allowed.

The value ``all'' can be used for any argument in the strace command line to indicate that there are no restrictions for that argument.

Multiple sets of the three arguments can be specified to obtain the messages from more than one driver or module. When strace is invoked, the log driver compares the sets of command line arguments with actual trace message, returning only messages that satisfy the specified criteria.

FORMAT

STREAMS trace event messages have the following format:

<seq> <time> <ticks> <level> <flags> <mid> <sid> <text>


Components are interpreted as follows:

<seq>
Trace sequence number.
<time>
Time the message was sent expressed in hh:mm:ss.
<ticks>
Time the message was sent expressed in machine ticks since last boot.
<level>
Tracing level as defined by the STREAMS driver or module that originates the messages.
<flags>
Any combination of the following three message indicators:
E
The message has also been saved in the error log.
F
The message signalled a fatal error.
N
The message has also been mailed to the system administrator.
<mid>
Module identification number of the trace message source.
<sid>
Sub-identification number of the trace message source.
<text>
Formatted text of the trace message.

DIAGNOSTICS

An exit status of zero (0) indicates that the command was successful; one (1) indicates that an error occured and a diagnostic message is printed to stderr; two (2) indicates that the option or argument syntax was in error and a diagnostic message is printed to stderr.

The --quiet option suppresses the printing of diagnostic messages to stderr.

SIGNALS

strace catches the SIGHUP signal (see signal(7)).

SIGHUP
When the SIGHUP signal is caught, strace will close the current log file and open a new (or reopen the existing) log file. This is for use with logrotate(8).
SIGTERM
When the SIGTERM signal is caught, strace flushes and closes all of its log files and then exits.

NOTICES

strace(8) has no ressemblence to the system-call tracing utility of the same name: strace(1).

Only one strace daemon or process at a time is permitted to open the STREAMS log driver as a trace logger. If a module or driver is generating a large number of trace messages, running the trace logger causes a degradation in STREAMS performance. If a large number of messages are generated in a short time, the log driver may not be able to deliver some of the messages. This situation is indicated by gaps in the sequence numbering of the messages in the log files.

When run in the foreground, strace runs until terminated by the caller.

Running strace with several sets of arguments can impair STREAMS performance, particularly for those modules and drivers that are sending the messages. Also be aware that strace may not be able to handle a large number of messages. If drivers and modules return messages to strace too quickly, some may be lost.

Due to performance considerations, only one strace command is permitted to open the STREAMS log driver at a time. The log driver has a list of the triplets specified in the command invocation, and compares each potential trace message against this list to decide if it should be formatted and sent up to the strace process. Hence, long lists of triplets have a greater impact on overall STREAMS performance. Running the strace command has the most impact on the timing of modules and drivers generating the trace messages that are sent to the strace process. If trace messages are generated faster than the strace process can handle them, some of the messages will be lost. This last case can be determined by examining the sequence numbers on the trace messages output.

DEVICES

/dev/streams/strlog, /dev/streams/log, /dev/strlog or /dev/log
the STREAMS logging device. See strlog(4).

FILES

/usr/sbin/strace
contains the strace command.
/var/log/streams or /var/adm/streams
directory containing the error log files.
/var/log/streams/trace.pid or /var/adm/streams/trace.pid
trace log file.
/etc/init.d/strace or /etc/strace.sh
an SysV or Debian init script for starting the trace logger.

SEE ALSO

log(4), strlog(4), strlog(9), strlog(1), strerr(8), strclean(8), syslogd(8), syslog(3).

BUGS

strace has no known bugs.

COMPATIBILITY

strace is compatible with SVR 4.2[1], and systems based on SVR 4.2, such as AIX®, HP-UX®, OSF/1®, Solaris®, SUPER-UX®, UnixWare® and UXP/V®, with the following compatibility considerations:

---
Options -n, -D, -b, -o, -e, -p and -l, and all long options, are specific to this The OpenSS7 Project implementation of strace and should not be used by portable applications.
---
No other implementation documents the -q, -D, -v, -h, -V or -C options. They should not be used by portable applications.
---
Options --help and --version are provided for compatibility with GNU coding standards; --copying, OpenSS7 coding standards.
---
All other implementations document the log file directory as /var/adm/streams instead of /var/log/streams. /var/log/streams is used under Linux for compatibility with the Linux File Standard. For compatibility, strace first checks if the directory /var/adm/streams exists, and then creates /var/log/streams if necessary, unless a directory is specified with the -d option.
---
SVR 4.2 and systems based on SVR 4.2 only describe strace as operating in the foreground. The OpenSS7 Project strace permits strace to be run in the background as a daemon process. This is useful for running background, high-level traces in running systems. This is accomplished in a manner similar to strerr(8).
---
Under SVR 4.2[1] and UnixWare®[2] the STREAMS log device is called /dev/log rather than /dev/strlog. Linux already has a non-STREAMS based log mechanism (BSD-style) logging device named /dev/log.
---
Under OSF/1®[3] the STREAMS log device is called /dev/streams/log instead of /dev/strlog.
---
For compatibility with these operating environments, strace attempts to open /dev/streams/strlog, /dev/streams/log, /dev/strlog and then /dev/log if not specified with the -l option. The call to strace will fail if there is no STREAMS-based log device in this search sequence, or specified with the -l option.

CONFORMANCE

SVR 4.2[1]; AIX®, HP-UX®, OSF/1®, Solaris®, SUPER-UX®, UnixWare® and UXP/V® documentation[2..8].

HISTORY

strace first appeared in SVR 4[9].

REFERENCES

[1]
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.
[2]
UnixWare® 7.1.3, UnixWare 7.1.3 (OpenUnix 8) Documentation, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>
[3]
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/>
[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]
Solaris® 8, Solaris 8 Docmentation, 2001, (Santa Clara, California), Sun Microsystems, Inc., Sun. <http://docs.sun.com/>
[7]
SUPER-UX® Release 9.2, SUPER-UX Release 9.2 Documentation, 1999, NEC Corporation, NEC.
[8]
UXP/V® V10L10, UXP/V V10L10 Documentation, 1997, Fujitsu Limited, Fujitsu.
[9]
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 Wed, 16 Aug 2017 02:05:51 GMT.

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



Index

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
ARGUMENTS
FORMAT
DIAGNOSTICS
SIGNALS
NOTICES
DEVICES
FILES
SEE ALSO
BUGS
COMPATIBILITY
CONFORMANCE
HISTORY
REFERENCES
TRADEMARKS
IDENTIFICATION

This document was created by man2html, using the manual pages.
Time: 02:05:51 GMT, August 16, 2017
OpenSS7
SS7 for the
Common Man
Home TopIndex FirstPrev Next LastMore Download Info FAQ Mail  Home -> Documentation -> Man Pages -> Manual Page
Last modified: Mon, 28 Apr 2008 12:53:43 GMT
© Copyright 1997-2007 OpenSS7 Corporation All Rights Reserved.