share/man/man8/strace.8

   1 '\" te
   2 .\"  Copyright 1989 AT&T  Copyright (c) 1997 Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH STRACE 8 "Oct 4, 1994"
   7 .SH NAME
   8 strace \- print STREAMS trace messages
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBstrace\fR [\fImid\fR \fIsid\fR \fIlevel\fR]...
  13 .fi
  14
  15 .SH DESCRIPTION
  16 .sp
  17 .LP
  18 \fBstrace\fR without arguments writes all STREAMS event trace messages from all
  19 drivers and modules to its standard output. These messages are obtained from
  20 the STREAMS log driver (see \fBlog\fR(7D)). If arguments are provided, they
  21 must be in triplets of the form \fImid, sid, level\fR, where \fImid\fR is a
  22 STREAMS module  \fBID\fR number, \fIsid\fR is a sub-ID number,  and \fIlevel\fR
  23 is a tracing priority level. Each triplet indicates that tracing messages are
  24 to be received from the given module/driver, sub-ID (usually indicating minor
  25 device), and priority level equal to, or less than the given level. The token
  26 \fBall\fR may be used for any member to indicate no restriction for that
  27 attribute.
  28 .sp
  29 .LP
  30 The format of each trace message output is:
  31 .sp
  32 .LP
  33 <\fIseq\fR> <\fBtime\fR> <\fIticks\fR> <\fIlevel\fR> <\fIflags\fR> <\fImid\fR>
  34 <\fIsid\fR> <\fItext\fR>
  35 .sp
  36 .ne 2
  37 .na
  38 \fB<\fIseq\fR>\fR
  39 .ad
  40 .RS 11n
  41 trace sequence number
  42 .RE
  43
  44 .sp
  45 .ne 2
  46 .na
  47 \fB<\fBtime\fR>\fR
  48 .ad
  49 .RS 11n
  50 time of message in \fIhh:mm:ss\fR
  51 .RE
  52
  53 .sp
  54 .ne 2
  55 .na
  56 \fB<\fIticks\fR>\fR
  57 .ad
  58 .RS 11n
  59 time of message in machine ticks since boot
  60 .RE
  61
  62 .sp
  63 .ne 2
  64 .na
  65 \fB<\fIlevel\fR>\fR
  66 .ad
  67 .RS 11n
  68 tracing priority level
  69 .RE
  70
  71 .sp
  72 .ne 2
  73 .na
  74 \fB<\fIflags\fR>\fR
  75 .ad
  76 .RS 11n
  77 E : message is also in the error log F : indicates a fatal error N : mail was
  78 sent to the system administrator (hardcoded as root)
  79 .RE
  80
  81 .sp
  82 .ne 2
  83 .na
  84 \fB<\fImid\fR>\fR
  85 .ad
  86 .RS 11n
  87 module  \fBID\fR number of source
  88 .RE
  89
  90 .sp
  91 .ne 2
  92 .na
  93 \fB<\fIsid\fR>\fR
  94 .ad
  95 .RS 11n
  96 sub-ID number of source
  97 .RE
  98
  99 .sp
 100 .ne 2
 101 .na
 102 \fB<\fItext\fR>\fR
 103 .ad
 104 .RS 11n
 105 formatted text of the trace message
 106 .RE
 107
 108 .sp
 109 .LP
 110 Once initiated, \fBstrace\fR will continue to execute until terminated by the
 111 user.
 112 .SH EXAMPLES
 113 .LP
 114 \fBExample 1 \fRA sample output of the \fBstrace\fR command:
 115 .sp
 116 .LP
 117 The following example outputs all trace messages from the module or driver
 118 whose module  \fBID\fR is  \fB41\fR:
 119
 120 .sp
 121 .in +2
 122 .nf
 123 \fBstrace  41 all all\fR
 124 .fi
 125 .in -2
 126 .sp
 127
 128 .sp
 129 .LP
 130 The following example outputs those trace messages from driver or module
 131 \fBID\fR \fB41\fR with  sub-IDs \fB0\fR, \fB1\fR, or  \fB2\fR:
 132
 133 .sp
 134 .in +2
 135 .nf
 136 \fBstrace  41 0 1  41 1 1  41 2 0\fR
 137 .fi
 138 .in -2
 139 .sp
 140
 141 .sp
 142 .LP
 143 Messages from sub-IDs  \fB0\fR and  \fB1\fR must have  a tracing level less
 144 than or equal to  \fB1\fR. Those from sub-ID  \fB2\fR must have a tracing level
 145 of  \fB0\fR.
 146
 147 .SH SEE ALSO
 148 .sp
 149 .LP
 150 \fBattributes\fR(5), \fBlog\fR(7D)
 151 .sp
 152 .LP
 153 \fI\fR
 154 .SH NOTES
 155 .RS +4
 156 .TP
 157 .ie t \(bu
 158 .el o
 159 There is no restriction to the number of \fBstrace\fR processes opening the
 160 \fBSTREAMS\fR log driver at a time.
 161 .RE
 162 .RS +4
 163 .TP
 164 .ie t \(bu
 165 .el o
 166 The log-driver records the list of the triplets specified in the command
 167 invocation, and compares each potential trace message against this list to
 168 decide if it should be formatted and sent up to the \fBstrace\fR process.
 169 Hence, long lists of triplets will have a greater impact on overall STREAMS
 170 performance. Running \fBstrace\fR will have the most impact on the timing of
 171 the modules and  drivers generating the trace messages that are sent to the
 172 \fBstrace\fR process. If trace messages are generated faster than the
 173 \fBstrace\fR process can handle them,  some of the messages will be lost. This
 174 last case can be determined by examining the sequence numbers on the trace
 175 messages output.
 176 .RE