usr/src/man/man3ext/tsalarm_get.3ext

   1 '\" te
   2 .\" Copyright (c) 2007, 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 TSALARM_GET 3EXT "Sep 4, 2007"
   7 .SH NAME
   8 tsalarm_get, tsalarm_set \- get or set alarm relays
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 cc [ \fIflag\fR... ] \fIfile\fR... \fB-ltsalarm\fR [ \fIlibrary\fR... ]
  13 #include <tsalarm.h>
  14
  15 \fBint\fR \fBtsalarm_get\fR(\fBuint32_t\fR \fIalarm_type\fR, \fBuint32_t *\fR\fIalarm_state\fR);
  16 .fi
  17
  18 .LP
  19 .nf
  20 \fBint\fR \fBtsalarm_set\fR(\fBuint32_t\fR \fIalarm_type\fR, \fBuint32_t\fR \fIalarm_state\fR);
  21 .fi
  22
  23 .SH PARAMETERS
  24 .sp
  25 .ne 2
  26 .na
  27 \fB\fIalarm_type\fR\fR
  28 .ad
  29 .sp .6
  30 .RS 4n
  31 The alarm type whose state is retrieved or set. Valid settings are:
  32 .sp
  33 .ne 2
  34 .na
  35 \fB\fBTSALARM_CRITICAL\fR\fR
  36 .ad
  37 .RS 20n
  38 critical
  39 .RE
  40
  41 .sp
  42 .ne 2
  43 .na
  44 \fB\fBTSALARM_MAJOR\fR\fR
  45 .ad
  46 .RS 20n
  47 major
  48 .RE
  49
  50 .sp
  51 .ne 2
  52 .na
  53 \fB\fBTSALARM_MINOR\fR\fR
  54 .ad
  55 .RS 20n
  56 minor
  57 .RE
  58
  59 .sp
  60 .ne 2
  61 .na
  62 \fB\fBTSALARM_USER\fR\fR
  63 .ad
  64 .RS 20n
  65 user
  66 .RE
  67
  68 .RE
  69
  70 .sp
  71 .ne 2
  72 .na
  73 \fB\fIalarm_state\fR\fR
  74 .ad
  75 .sp .6
  76 .RS 4n
  77 The state of the alarm. Valid settings are:
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fBTSALARM_STATE_ON\fR\fR
  82 .ad
  83 .RS 25n
  84 The alarm state needs to be changed to "on", or is returned as "on".
  85 .RE
  86
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fBTSALARM_STATE_OFF\fR\fR
  91 .ad
  92 .RS 25n
  93 The alarm state needs to be changed to "off", or is returned as "off".
  94 .RE
  95
  96 .sp
  97 .ne 2
  98 .na
  99 \fB\fBTSALARM_STATE_UNKNOWN\fR\fR
 100 .ad
 101 .RS 25n
 102 The alarm state is returned as unknown.
 103 .RE
 104
 105 .RE
 106
 107 .SH DESCRIPTION
 108 .sp
 109 .LP
 110 The TSALARM interface provides functions through which alarm relays can be
 111 controlled. The set of functions and data structures of this interface are
 112 defined in the \fB<tsalarm.h>\fR header.
 113 .sp
 114 .LP
 115 There are four alarm relays that are controlled by ILOM. Each alarm can be set
 116 to "on" or "off" by using \fBtsalarm\fR interfaces provided from the host. The
 117 four alarms are labeled as \fBcritical\fR, \fBmajor\fR, \fBminor\fR, and
 118 \fBuser\fR. The user alarm is set by a user application depending on system
 119 condition. LEDs in front of the box provide a visual indication of the four
 120 alarms. The number of alarms and their meanings and labels can vary across
 121 platforms.
 122 .sp
 123 .LP
 124 The \fBtsalarm_get()\fR function gets the state of \fIalarm_type\fR and
 125 returnsit in \fIalarm_state\fR. If successful, the function returns 0.
 126 .sp
 127 .LP
 128 The \fBtsalarm_set()\fR function sets the state of \fIalarm_type\fR to the
 129 value in \fIalarm_state\fR. If successful, the function returns 0.
 130 .sp
 131 .LP
 132 The following structures are defined in \fB<tsalarm.h>\fR:
 133 .sp
 134 .in +2
 135 .nf
 136 typedef struct tsalarm_req {
 137      uint32_t     alarm_id;
 138      uint32_t     alarm_action;
 139 } tsalarm_req_t;
 140 .fi
 141 .in -2
 142
 143 .sp
 144 .in +2
 145 .nf
 146 typedef struct tsalarm_resp {
 147      uint32_t     status;
 148      uint32_t     alarm_id;
 149      uint32_t     alarm_state;
 150 } tsalarm_resp_t;
 151 .fi
 152 .in -2
 153
 154 .SH RETURN VALUES
 155 .sp
 156 .LP
 157 The \fBtsalarm_get()\fR and \fBtsalarm_set()\fR functions return the following
 158 values:
 159 .sp
 160 .ne 2
 161 .na
 162 \fB\fBTSALARM_CHANNEL_INIT_FAILURE\fR\fR
 163 .ad
 164 .sp .6
 165 .RS 4n
 166 Channel initialization failed.
 167 .RE
 168
 169 .sp
 170 .ne 2
 171 .na
 172 \fB\fBTSALARM_COMM_FAILURE\fR\fR
 173 .ad
 174 .sp .6
 175 .RS 4n
 176 Channel communication failed.
 177 .RE
 178
 179 .sp
 180 .ne 2
 181 .na
 182 \fB\fBTSALARM_NULL_REQ_DATA\fR\fR
 183 .ad
 184 .sp .6
 185 .RS 4n
 186 Allocating memory for request data failed.
 187 .RE
 188
 189 .sp
 190 .ne 2
 191 .na
 192 \fB\fBTSALARM_SUCCESS\fR\fR
 193 .ad
 194 .sp .6
 195 .RS 4n
 196 Successful completion.
 197 .RE
 198
 199 .sp
 200 .ne 2
 201 .na
 202 \fB\fBTSALARM_UNBOUND_PACKET_RECVD\fR\fR
 203 .ad
 204 .sp .6
 205 .RS 4n
 206 An incorrect packet was received.
 207 .RE
 208
 209 .sp
 210 .LP
 211 The \fBtsalarm_get()\fR function returns the following value:
 212 .sp
 213 .ne 2
 214 .na
 215 \fB\fBTSALARM_GET_ERROR\fR\fR
 216 .ad
 217 .RS 21n
 218 An error occurred  while getting the alarm state.
 219 .RE
 220
 221 .sp
 222 .LP
 223 The \fBtsalarm_set()\fR function returns the following value:
 224 .sp
 225 .ne 2
 226 .na
 227 \fB\fBTSALARM_SET_ERROR\fR\fR
 228 .ad
 229 .RS 21n
 230 An error occurred  while setting the alarm state.
 231 .RE
 232
 233 .SH EXAMPLES
 234 .LP
 235 \fBExample 1 \fRGet and set an alarm state.
 236 .sp
 237 .LP
 238 The following example demonstrates how to get and set an alarm state.
 239
 240 .sp
 241 .in +2
 242 .nf
 243 #include <stdio.h>
 244 #include <stdlib.h>
 245 #include <string.h>
 246 #include <sys/types.h>
 247 #include <tsalarm.h>
 248
 249 void help(char *name) {
 250    printf("Syntax:  %s [get <type> | set <type> <state>]\en\en", name);
 251    printf("         type  = { critical, major, minor, user }\en");
 252    printf("         state = { on, off }\en\en");
 253
 254    exit(0);
 255 }
 256
 257 int main(int argc, char **argv) {
 258
 259    uint32_t alarm_type, alarm_state;
 260
 261    if (argc < 3)
 262       help(argv[0]);
 263
 264    if (strncmp(argv[2], "critical", 1) == 0)
 265       alarm_type = TSALARM_CRITICAL;
 266    else if (strncmp(argv[2], "major", 2) == 0)
 267       alarm_type = TSALARM_MAJOR;
 268    else if (strncmp(argv[2], "minor", 2) == 0)
 269       alarm_type = TSALARM_MINOR;
 270    else if (strncmp(argv[2], "user", 1) == 0)
 271       alarm_type = TSALARM_USER;
 272    else
 273       help(argv[0]);
 274
 275    if (strncmp(argv[1], "get", 1) == 0) {
 276       tsalarm_get(alarm_type, &alarm_state);
 277       printf("alarm = %d\etstate = %d\en", alarm_type, alarm_state);
 278    }
 279    else if (strncmp(argv[1], "set", 1) == 0) {
 280       if (strncmp(argv[3], "on", 2) == 0)
 281          alarm_state = TSALARM_STATE_ON;
 282       else if (strncmp(argv[3], "off", 2) == 0)
 283          alarm_state = TSALARM_STATE_OFF;
 284       else
 285          help(argv[0]);
 286
 287       tsalarm_set(alarm_type, alarm_state);
 288    }
 289    else {
 290       help(argv[0]);
 291    }
 292
 293    return 0;
 294 }
 295 .fi
 296 .in -2
 297
 298 .SH ATTRIBUTES
 299 .sp
 300 .LP
 301 See \fBattributes\fR(5) for descriptions of the following attributes:
 302 .sp
 303
 304 .sp
 305 .TS
 306 box;
 307 c | c
 308 l | l .
 309 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 310 _
 311 Interface Stability     Uncommitted
 312 _
 313 MT-Level        Safe
 314 .TE
 315
 316 .SH SEE ALSO
 317 .sp
 318 .LP
 319 \fBlibtsalarm\fR(3LIB), \fBattributes\fR(5)