usr/src/man/man1m/plockstat.1m

   1 '\" te
   2 .\" Copyright (c) 2009, 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 PLOCKSTAT 1M "Jan 26, 2009"
   7 .SH NAME
   8 plockstat \- report user-level lock statistics
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBplockstat\fR [\fB-vACHV\fR] [\fB-n\fR \fIcount\fR] [\fB-s\fR \fIdepth\fR] [\fB-e\fR \fIsecs\fR]
  13      [\fB-x\fR \fIarg\fR [=val]] \fIcommand\fR [\fIarg\fR]...
  14 .fi
  15
  16 .LP
  17 .nf
  18 \fBplockstat\fR [\fB-vACHV\fR] [\fB-n\fR \fIcount\fR] [\fB-s\fR \fIdepth\fR] [\fB-e\fR \fIsecs\fR]
  19      [\fB-x\fR \fIarg\fR [=val]] \fB-p\fR \fIpid\fR
  20 .fi
  21
  22 .SH DESCRIPTION
  23 .sp
  24 .LP
  25 The \fBplockstat\fR utility gathers and displays user-level locking statistics.
  26 By default, \fBplockstat\fR monitors all lock contention events, gathers
  27 frequency and timing data about those events, and displays the data in
  28 decreasing frequency order, so that the most common events appear first.
  29 .sp
  30 .LP
  31 \fBplockstat\fR gathers data until the specified command completes or the
  32 process specified with the \fB-p\fR option completes.
  33 .sp
  34 .LP
  35 \fBplockstat\fR relies on DTrace to instrument a running process or a command
  36 it invokes to trace events of interest. This imposes a small but measurable
  37 performance overhead on the processes being observed. Users must have the
  38 \fBdtrace_proc\fR privilege and have permission to observe a particular process
  39 with \fBplockstat\fR. Refer to the \fI\fR for more information about DTrace
  40 security features.
  41 .SH OPTIONS
  42 .sp
  43 .LP
  44 The following options are supported:
  45 .sp
  46 .ne 2
  47 .na
  48 \fB\fB-A\fR\fR
  49 .ad
  50 .RS 16n
  51 Watch all lock events. This option is equivalent to \fB-CH\fR.
  52 .RE
  53
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fB-C\fR\fR
  58 .ad
  59 .RS 16n
  60 Watch contention events.
  61 .RE
  62
  63 .sp
  64 .ne 2
  65 .na
  66 \fB\fB-H\fR\fR
  67 .ad
  68 .RS 16n
  69 Watch hold events.
  70 .RE
  71
  72 .sp
  73 .ne 2
  74 .na
  75 \fB\fB-e\fR \fIsecs\fR\fR
  76 .ad
  77 .RS 16n
  78 Exit after the number of seconds specified have elapsed.
  79 .RE
  80
  81 .sp
  82 .ne 2
  83 .na
  84 \fB\fB-n\fR \fIcount\fR\fR
  85 .ad
  86 .RS 16n
  87 Display only the specified number of entries for each output category.
  88 .RE
  89
  90 .sp
  91 .ne 2
  92 .na
  93 \fB\fB-s\fR \fIdepth\fR\fR
  94 .ad
  95 .RS 16n
  96 Record a stack trace rather than just the calling function.
  97 .RE
  98
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fB-p\fR \fIpid\fR\fR
 103 .ad
 104 .RS 16n
 105 Specify a process ID from which \fBplockstat\fR is to gather data.
 106 .RE
 107
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fB-v\fR\fR
 112 .ad
 113 .RS 16n
 114 Print out a message to indicate that tracing has started.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fB-x\fR \fIarg\fR[=\fIval\fR]\fR
 121 .ad
 122 .RS 16n
 123 Enable or modify a DTrace runtime option or D compiler option. The list of
 124 options is found in the \fISolaris Dynamic Tracing Guide\fR. Boolean options
 125 are enabled by specifying their name. Options with values are set by separating
 126 the option name and value with an equals sign (\fB=\fR).
 127 .RE
 128
 129 .sp
 130 .ne 2
 131 .na
 132 \fB\fB-V\fR\fR
 133 .ad
 134 .RS 16n
 135 Print the Dtrace commands used to gather the data. The output can then be used
 136 directly with the \fBdtrace\fR(1M) command.
 137 .RE
 138
 139 .SH OPERANDS
 140 .sp
 141 .LP
 142 The following operands are supported:
 143 .sp
 144 .ne 2
 145 .na
 146 \fB\fIarg\fR\fR
 147 .ad
 148 .RS 11n
 149 A string to be passed as an argument to \fIcommand\fR.
 150 .RE
 151
 152 .sp
 153 .ne 2
 154 .na
 155 \fB\fIcommand\fR\fR
 156 .ad
 157 .RS 11n
 158 The name of a utility to be invoked.
 159 .RE
 160
 161 .sp
 162 .ne 2
 163 .na
 164 \fB\fIcount\fR\fR
 165 .ad
 166 .RS 11n
 167 A positive integer value.
 168 .RE
 169
 170 .sp
 171 .ne 2
 172 .na
 173 \fB\fIpid\fR\fR
 174 .ad
 175 .RS 11n
 176 A process identifier for a process to be monitored.
 177 .RE
 178
 179 .sp
 180 .ne 2
 181 .na
 182 \fB\fIsecs\fR\fR
 183 .ad
 184 .RS 11n
 185 Duration specified as a positive integer number of seconds.
 186 .RE
 187
 188 .SH EXIT STATUS
 189 .sp
 190 .LP
 191 The following exit values are returned:
 192 .sp
 193 .ne 2
 194 .na
 195 \fB\fB0\fR\fR
 196 .ad
 197 .RS 6n
 198 Successful completion.
 199 .RE
 200
 201 .sp
 202 .ne 2
 203 .na
 204 \fB>\fB0\fR\fR
 205 .ad
 206 .RS 6n
 207 An error occurred.
 208 .RE
 209
 210 .SH ATTRIBUTES
 211 .sp
 212 .LP
 213 See \fBattributes\fR(5) for descriptions of the following attributes:
 214 .sp
 215
 216 .sp
 217 .TS
 218 box;
 219 c | c
 220 l | l .
 221 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 222 _
 223 Interface Stability     See below.
 224 .TE
 225
 226 .sp
 227 .LP
 228 The command-line syntax is Evolving. The human-readable output is Unstable.
 229 .SH SEE ALSO
 230 .sp
 231 .LP
 232 \fBdtrace\fR(1M), \fBlockstat\fR(1M), \fBmutex_init\fR(3C),
 233 \fBpthread_mutex_lock\fR(3C), \fBpthread_rwlock_rdlock\fR(3C),
 234 \fBpthread_rwlock_wrlock\fR(3C), \fBpthread_rwlock_unlock\fR(3C),
 235 \fBrwlock\fR(3C), \fBattributes\fR(5), \fBfasttrap\fR(7D)
 236 .sp
 237 .LP
 238 \fI\fR