share/man/man1/ctwatch.1

   1 '\" te
   2 .\" Copyright (c) 2004, 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 CTWATCH 1 "Jul 14, 2004"
   7 .SH NAME
   8 ctwatch \- watch events in a contract or group of contracts
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fB/usr/bin/ctwatch\fR [\fB-f\fR] [\fB-r\fR] [\fB-v\fR] \fIcontract-type\fR... | \fIcontract-id\fR...
  13 .fi
  14
  15 .SH DESCRIPTION
  16 .sp
  17 .LP
  18 The \fBctwatch\fR utility allows a user to observe the events occurring within
  19 a set of contracts or contract types. By default, \fBctwatch\fR watches all
  20 contracts.
  21 .SH OPTIONS
  22 .sp
  23 .LP
  24 The following options are supported:
  25 .sp
  26 .ne 2
  27 .na
  28 \fB\fB-f\fR\fR
  29 .ad
  30 .RS 6n
  31 Report events starting at the front of the event queue. Normally, \fBctwatch\fR
  32 reports only events which occur after it has been invoked. With the \fB-f\fR
  33 option, any events that still exist in the contracts' event queues when
  34 \fBctwatch\fR is invoked (for example, unacknowledged critical events) are also
  35 reported.
  36 .RE
  37
  38 .sp
  39 .ne 2
  40 .na
  41 \fB\fB-r\fR\fR
  42 .ad
  43 .RS 6n
  44 Reliably watches all messages. Normally, the system may drop informative events
  45 and acknowledged critical events at any time, so \fBctwatch\fR isn't guaranteed
  46 to see them all. This option may only be used if the \fBctwatch\fR is invoked
  47 with the \fB{PRIV_CONTRACT_EVENT}\fR privilege asserted in its effective set.
  48 .RE
  49
  50 .sp
  51 .ne 2
  52 .na
  53 \fB\fB-v\fR\fR
  54 .ad
  55 .RS 6n
  56 Request verbose event descriptions.
  57 .RE
  58
  59 .SH OPERANDS
  60 .sp
  61 .LP
  62 The following operands are supported:
  63 .sp
  64 .ne 2
  65 .na
  66 \fB\fIcontract-type\fR\fR
  67 .ad
  68 .RS 17n
  69 Valid contract types are:
  70 .sp
  71 .ne 2
  72 .na
  73 \fBprocess\fR
  74 .ad
  75 .RS 11n
  76 Process contracts.
  77 .RE
  78
  79 .RE
  80
  81 .sp
  82 .ne 2
  83 .na
  84 \fB\fIcontract-id\fR\fR
  85 .ad
  86 .RS 17n
  87 A valid contract id.
  88 .RE
  89
  90 .SH OUTPUT
  91 .sp
  92 .LP
  93 The following list defines the column headings and the meanings of a
  94 \fBctwatch\fR report:
  95 .sp
  96 .ne 2
  97 .na
  98 \fBCTID\fR
  99 .ad
 100 .RS 11n
 101 The contract \fBID\fR generating the event.
 102 .RE
 103
 104 .sp
 105 .ne 2
 106 .na
 107 \fBEVID\fR
 108 .ad
 109 .RS 11n
 110 The event \fBID\fR.
 111 .RE
 112
 113 .sp
 114 .ne 2
 115 .na
 116 \fBCRIT\fR
 117 .ad
 118 .RS 11n
 119 Whether the event is informative, critical, or initiates an exit negotiation.
 120 Values are \fBinfo\fR, \fBcrit\fR, or \fBneg\fR, respectively.
 121 .RE
 122
 123 .sp
 124 .ne 2
 125 .na
 126 \fBACK\fR
 127 .ad
 128 .RS 11n
 129 The event has been acknowledged. Values are \fByes\fR or "\fBno\fR".
 130 .RE
 131
 132 .sp
 133 .ne 2
 134 .na
 135 \fBCTTYPE\fR
 136 .ad
 137 .RS 11n
 138 The contract type.
 139 .RE
 140
 141 .sp
 142 .ne 2
 143 .na
 144 \fBSUMMARY\fR
 145 .ad
 146 .RS 11n
 147 A type-specific summary of the event.
 148 .RE
 149
 150 .SH EXAMPLES
 151 .LP
 152 \fBExample 1 \fRWatching a process contract
 153 .sp
 154 .in +2
 155 .nf
 156 example% \fBctwatch -r 1\fR
 157
 158 CTID    EVID    CRIT ACK CTTYPE  SUMMARY
 159 1       2       crit no  process pid 100569 was created
 160 1       3       info no  process pid 100569 encountered hardware error
 161 1       4       info no  process pid 100568 exited
 162 1       5       info no  process pid 100569 exited
 163 1       6       crit no  process contract empty
 164 .fi
 165 .in -2
 166 .sp
 167
 168 .SH EXIT STATUS
 169 .sp
 170 .LP
 171 The following exit values are returned:
 172 .sp
 173 .ne 2
 174 .na
 175 \fB\fB0\fR\fR
 176 .ad
 177 .RS 5n
 178 Successful completion.
 179 .RE
 180
 181 .sp
 182 .ne 2
 183 .na
 184 \fB\fB1\fR\fR
 185 .ad
 186 .RS 5n
 187 An error occurred.
 188 .RE
 189
 190 .sp
 191 .ne 2
 192 .na
 193 \fB\fB2\fR\fR
 194 .ad
 195 .RS 5n
 196 Invalid arguments.
 197 .RE
 198
 199 .SH FILES
 200 .sp
 201 .LP
 202 \fB/system/contract/*\fR
 203 .SH ATTRIBUTES
 204 .sp
 205 .LP
 206 See \fBattributes\fR(5) for descriptions of the following attributes:
 207 .sp
 208
 209 .sp
 210 .TS
 211 box;
 212 c | c
 213 l | l .
 214 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 215 _
 216 Interface Stability     See below.
 217 .TE
 218
 219 .sp
 220 .LP
 221 Human Readable Output is Unstable. Invocation is Evolving.
 222 .SH SEE ALSO
 223 .sp
 224 .LP
 225 \fBctrun\fR(1), \fBctstat\fR(1), \fBcontract\fR(4), \fBprocess\fR(4),
 226 \fBattributes\fR(5), \fBprivileges\fR(5)
 227 .SH NOTES
 228 .sp
 229 .LP
 230 Ordering of events is only guaranteed within a single contract, or within a
 231 single type when a type is specified.
 232 .sp
 233 .LP
 234 \fBctwatch\fR can only observe those events which are generated by contracts
 235 owned or authored by processes with the same effective user ID as
 236 \fBctwatch\fR, unless the \fB{PRIV_CONTRACT_OBSERVER}\fR privilege is asserted
 237 in its effective set.