share/man/man3sip/sip_enable_counters.3sip

   1 '\" te
   2 .\" Copyright (c) 2008, 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 SIP_ENABLE_COUNTERS 3SIP "Jan 11, 2008"
   7 .SH NAME
   8 sip_enable_counters, sip_disable_counters, sip_get_counter_value \- counter
   9 operations
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... -\fBlsip\fR [ \fIlibrary\fR... ]
  14 #include <sip.h>
  15
  16 \fBint\fR \fBsip_enable_counters\fR(\fBint\fR \fIcounter_group\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBint\fR \fBsip_disable_counters\fR(\fBint\fR \fIcounter_group\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBint\fR \fBsip_get_counter_value\fR(\fBint\fR \fIgroup\fR, \fBint\fR \fIcounter\fR, \fBvoid *\fR\fIcounterval\fR,
  27      \fBsize_t\fR \fIcounterlen\fR);
  28 .fi
  29
  30 .SH DESCRIPTION
  31 .sp
  32 .LP
  33 The \fBsip_enable_counters()\fR function enables the measurement and counting
  34 of the selected counter group. The only allowed value for the
  35 \fIcounter_group\fR is \fBSIP_TRAFFIC_COUNTERS\fR, which is defined in
  36 \fB<sip.h>\fR. Once enabled, the SIP stack starts measuring end-to-end SIP
  37 traffic. The SIP stack keeps track of:
  38 .RS +4
  39 .TP
  40 .ie t \(bu
  41 .el o
  42 the number of SIP requests sent and received (broken down by methods),
  43 .RE
  44 .RS +4
  45 .TP
  46 .ie t \(bu
  47 .el o
  48 the number of SIP responses sent and received (broken down by response codes),
  49 and
  50 .RE
  51 .RS +4
  52 .TP
  53 .ie t \(bu
  54 .el o
  55 the number of bytes sent and received.
  56 .RE
  57 .sp
  58 .LP
  59 The following counters are defined in \fB<sip.h>\fR for the
  60 \fBSIP_TRAFFIC_COUNTERS\fR group. These counter values are retrieved using the
  61 \fBsip_get_counter_value()\fR function.
  62 .sp
  63 .in +2
  64 .nf
  65 SIP_TOTAL_BYTES_RCVD
  66 SIP_TOTAL_BYTES_SENT
  67 SIP_TOTAL_REQ_RCVD
  68 SIP_TOTAL_REQ_SENT
  69 SIP_TOTAL_RESP_RCVD
  70 SIP_TOTAL_RESP_SENT
  71 SIP_ACK_REQ_RCVD
  72 SIP_ACK_REQ_SENT
  73 SIP_BYE_REQ_RCVD
  74 SIP_BYE_REQ_SENT
  75 SIP_CANCEL_REQ_RCVD
  76 SIP_CANCEL_REQ_SENT
  77 SIP_INFO_REQ_RCVD
  78 SIP_INFO_REQ_SENT
  79 SIP_INVITE_REQ_RCVD
  80 SIP_INVITE_REQ_SENT
  81 SIP_NOTIFY_REQ_RCVD
  82 SIP_NOTIFY_REQ_SENT
  83 SIP_OPTIONS_REQ_RCVD
  84 SIP_OPTIONS_REQ_SENT
  85 SIP_PRACK_REQ_RCVD
  86 SIP_PRACK_REQ_SENT
  87 SIP_REFER_REQ_RCVD
  88 SIP_REFER_REQ_SENT
  89 SIP_REGISTER_REQ_RCVD
  90 SIP_REGISTER_REQ_SENT
  91 SIP_SUBSCRIBE_REQ_RCVD
  92 SIP_SUBSCRIBE_REQ_SENT
  93 SIP_UPDATE_REQ_RCVD
  94 SIP_UPDATE_REQ_SENT
  95 SIP_1XX_RESP_RCVD
  96 SIP_1XX_RESP_SENT
  97 SIP_2XX_RESP_RCVD
  98 SIP_2XX_RESP_SENT
  99 SIP_3XX_RESP_RCVD
 100 SIP_3XX_RESP_SENT
 101 SIP_4XX_RESP_RCVD
 102 SIP_4XX_RESP_SENT
 103 SIP_5XX_RESP_RCVD
 104 SIP_5XX_RESP_SENT
 105 SIP_6XX_RESP_RCVD
 106 SIP_6xx_RESP_SENT
 107 SIP_COUNTER_START_TIME  /* records time when counting was enabled */
 108 SIP_COUNTER_STOP_TIME   /* records time when counting was disabled */
 109 .fi
 110 .in -2
 111
 112 .sp
 113 .LP
 114 All of the above counters are defined to be \fBuint64_t\fR, except for
 115 \fBSIP_COUNTER_START_TIME\fR and \fBSIP_COUNTER_STOP_TIME\fR, which are defined
 116 to be \fBtime_t\fR.
 117 .sp
 118 .LP
 119 The \fBsip_disable_counters()\fR function disables measurement and counting for
 120 the specified \fIcounter_group\fR. When disabled, the counter values are not
 121 reset and are retained until the measurement is enabled again. Calling
 122 \fBsip_enable_counters()\fR again would reset all counter values to zero and
 123 counting would start afresh.
 124 .sp
 125 .LP
 126 The \fBsip_get_counter_value()\fR function retrieves the value of the specified
 127 counter within the specified counter group. The value is copied to the user
 128 provided buffer, \fIcounterval\fR, of length \fIcounterlen\fR. For example,
 129 after the following call, \fIinvite_rcvd\fR would have the correct value.
 130 .sp
 131 .in +2
 132 .nf
 133 uint64_t invite_rcvd;
 134
 135 sip_get_counter_value(SIP_TRAFFIC_COUNTERS, SIP_INVITE_REQ_RCVD,
 136         &invite_rcvd, sizeof (uint64_t));
 137 .fi
 138 .in -2
 139
 140 .SH RETURN VALUES
 141 .sp
 142 .LP
 143 Upon successful completion, \fBsip_enable_counters()\fR and
 144 \fBsip_disable_counters()\fR return 0. They will return \fBEINVAL\fR if an
 145 incorrect group is specified.
 146 .sp
 147 .LP
 148 Upon successful completion, \fBsip_get_counter_value()\fR returns 0. It
 149 returns \fBEINVAL\fR if an incorrect counter name or counter size is specified,
 150 or if \fIcounterval\fR is \fINULL\fR.
 151 .SH ATTRIBUTES
 152 .sp
 153 .LP
 154 See \fBattributes\fR(5) for descriptions of the following attributes:
 155 .sp
 156
 157 .sp
 158 .TS
 159 box;
 160 c | c
 161 l | l .
 162 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 163 _
 164 Interface Stability     Committed
 165 _
 166 MT-Level        MT-Safe
 167 .TE
 168
 169 .SH SEE ALSO
 170 .sp
 171 .LP
 172 \fBattributes\fR(5)