share/man/man3scf/smf_enable_instance.3scf

   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 SMF_ENABLE_INSTANCE 3SCF "Nov 5, 2007"
   7 .SH NAME
   8 smf_enable_instance, smf_disable_instance, smf_refresh_instance,
   9 smf_restart_instance, smf_maintain_instance, smf_degrade_instance,
  10 smf_restore_instance, smf_get_state \- administrative interface to the Service
  11 Configuration Facility
  12 .SH SYNOPSIS
  13 .LP
  14 .nf
  15 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lscf\fR [ \fIlibrary\fR\&.\|.\|. ]
  16 #include <libscf.h>
  17
  18 \fBint\fR \fBsmf_enable_instance\fR(\fBconst char *\fR\fIinstance\fR, \fBint\fR \fIflags\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBint\fR \fBsmf_disable_instance\fR(\fBconst char *\fR\fIinstance\fR, \fBint\fR \fIflags\fR);
  24 .fi
  25
  26 .LP
  27 .nf
  28 \fBint\fR \fBsmf_refresh_instance\fR(\fBconst char *\fR\fIinstance\fR);
  29 .fi
  30
  31 .LP
  32 .nf
  33 \fBint\fR \fBsmf_restart_instance\fR(\fBconst char *\fR\fIinstance\fR);
  34 .fi
  35
  36 .LP
  37 .nf
  38 \fBint\fR \fBsmf_maintain_instance\fR(\fBconst char *\fR\fIinstance\fR, \fBint\fR \fIflags\fR);
  39 .fi
  40
  41 .LP
  42 .nf
  43 \fBint\fR \fBsmf_degrade_instance\fR(\fBconst char *\fR\fIinstance\fR, \fBint\fR \fIflags\fR);
  44 .fi
  45
  46 .LP
  47 .nf
  48 \fBint\fR \fBsmf_restore_instance\fR(\fBconst char *\fR\fIinstance\fR);
  49 .fi
  50
  51 .LP
  52 .nf
  53 \fBchar *\fR\fBsmf_get_state\fR(\fBconst char *\fR\fIinstance\fR);
  54 .fi
  55
  56 .SH DESCRIPTION
  57 .sp
  58 .LP
  59 These functions provide administrative control over service instances. Using
  60 these functions, an administrative tool can make a request to enable, disable,
  61 refresh, or restart an instance. All calls are asynchronous. They request an
  62 action, but do not wait to see if the action succeeds or fails.
  63 .sp
  64 .LP
  65 The \fBsmf_enable_instance()\fR function enables the service instance specified
  66 by \fIinstance\fR FMRI. If \fIflags\fR is \fBSMF_TEMPORARY\fR, the enabling of
  67 the service instance is a temporary change, lasting only for the lifetime of
  68 the current system instance. The \fIflags\fR argument is set to \fB0\fR if no
  69 flags are to be use.
  70 .sp
  71 .LP
  72 The \fBsmf_disable_instance()\fR function places the service instance specified
  73 by \fIinstance\fR FMRI in the disabled state and triggers the stop method (see
  74 \fBsvc.startd\fR(8)). If \fIflags\fR is \fBSMF_TEMPORARY\fR, the disabling of
  75 the service instance is a temporary change, lasting only for the lifetime of
  76 the current system instance. The \fIflags\fR argument is set to \fB0\fR if no
  77 flags are to be use.
  78 .sp
  79 .LP
  80 The \fBsmf_refresh_instance()\fR function causes the service instance specified
  81 by \fIinstance\fR FMRI to re-read its configuration information.
  82 .sp
  83 .LP
  84 The \fBsmf_restart_instance()\fR function restarts the service instance
  85 specified by \fIinstance\fR FMRI.
  86 .sp
  87 .LP
  88 The \fBsmf_maintain_instance()\fR function moves the service instance specified
  89 by \fIinstance\fR into the maintenance state. If \fIflags\fR is
  90 \fBSMF_IMMEDIATE\fR, the instance is moved into maintenance state immediately,
  91 killing any running methods. If \fIflags\fR is \fBSMF_TEMPORARY\fR, the change
  92 to maintenance state is a temporary change, lasting only for the lifetime of
  93 the current system instance. The \fIflags\fR argument is set to \fB0\fR if no
  94 flags are to be use.
  95 .sp
  96 .LP
  97 The \fBsmf_degrade_instance()\fR function moves an online service instance into
  98 the degraded state. This function operates only on instances in the online
  99 state. The \fIflags\fR argument is set to \fB0\fR if no flags are to be use.
 100 The only available flag is \fBSMF_IMMEDIATE\fR, which causes the instance to be
 101 moved into the degraded state immediately.
 102 .sp
 103 .LP
 104 The \fBsmf_restore_instance()\fR function brings an instance currently in the
 105 maintenance to the uninitialized state, so that it can be brought back online.
 106 For a service in the degraded state, \fBsmf_restore_instance()\fR brings the
 107 specified instance back to the online state.
 108 .sp
 109 .LP
 110 The \fBsmf_get_state()\fR function returns a pointer to a string containing the
 111 name of the instance's current state. The user is responsible for freeing this
 112 string. Possible state strings are defined as the following:
 113 .sp
 114 .in +2
 115 .nf
 116 #define SCF_STATE_STRING_UNINIT         ((const char *)"uninitialized")
 117 #define SCF_STATE_STRING_MAINT          ((const char *)"maintenance")
 118 #define SCF_STATE_STRING_OFFLINE        ((const char *)"offline")
 119 #define SCF_STATE_STRING_DISABLED       ((const char *)"disabled")
 120 #define SCF_STATE_STRING_ONLINE         ((const char *)"online")
 121 #define SCF_STATE_STRING_DEGRADED       ((const char *)"degraded")
 122 .fi
 123 .in -2
 124
 125 .SH RETURN VALUES
 126 .sp
 127 .LP
 128 Upon successful completion, \fBsmf_enable_instance()\fR,
 129 \fBsmf_disable_instance()\fR, \fBsmf_refresh_instance()\fR,
 130 \fBsmf_restart_instance()\fR, \fBsmf_maintain_instance()\fR,
 131 \fBsmf_degrade_instance()\fR, and \fBsmf_restore_instance()\fR return \fB0\fR.
 132 Otherwise, they return \fB-1\fR\&.
 133 .sp
 134 .LP
 135 Upon successful completion, smf_get_state returns an allocated string.
 136 Otherwise, it returns \fINULL\fR.
 137 .SH ERRORS
 138 .sp
 139 .LP
 140 These functions will fail if:
 141 .sp
 142 .ne 2
 143 .na
 144 \fB\fBSCF_ERROR_NO_MEMORY\fR\fR
 145 .ad
 146 .sp .6
 147 .RS 4n
 148 The memory allocation failed.
 149 .RE
 150
 151 .sp
 152 .ne 2
 153 .na
 154 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
 155 .ad
 156 .sp .6
 157 .RS 4n
 158 The \fIinstance\fR FMRI or \fIflags\fR argument is invalid.
 159 .RE
 160
 161 .sp
 162 .ne 2
 163 .na
 164 \fB\fBSCF_ERROR_NOT_FOUND\fR\fR
 165 .ad
 166 .sp .6
 167 .RS 4n
 168 The FMRI is valid but there is no matching instance found.
 169 .RE
 170
 171 .sp
 172 .ne 2
 173 .na
 174 \fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
 175 .ad
 176 .sp .6
 177 .RS 4n
 178 The connection to repository was broken.
 179 .RE
 180
 181 .sp
 182 .ne 2
 183 .na
 184 \fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
 185 .ad
 186 .sp .6
 187 .RS 4n
 188 The server has insufficient resources.
 189 .RE
 190
 191 .sp
 192 .LP
 193 The \fBsmf_maintain_instance()\fR, \fBsmf_refresh_instance()\fR,
 194 \fBsmf_restart_instance()\fR, \fBsmf_degrade_instance()\fR, and
 195 \fBsmf_restore_instance()\fR functions will fail if:
 196 .sp
 197 .ne 2
 198 .na
 199 \fB\fBSCF_ERROR_PERMISSION_DENIED\fR\fR
 200 .ad
 201 .sp .6
 202 .RS 4n
 203 User does not have proper authorizations. See \fBsmf_security\fR(5).
 204 .RE
 205
 206 .sp
 207 .ne 2
 208 .na
 209 \fB\fBSCF_ERROR_BACKEND_ACCESS\fR\fR
 210 .ad
 211 .sp .6
 212 .RS 4n
 213 The repository's backend refused access.
 214 .RE
 215
 216 .sp
 217 .ne 2
 218 .na
 219 \fB\fBSCF_ERROR_BACKEND_READONLY\fR\fR
 220 .ad
 221 .sp .6
 222 .RS 4n
 223 The repository's backend is read-only.
 224 .RE
 225
 226 .sp
 227 .LP
 228 The \fBsmf_restore_instance()\fR and \fBsmf_degrade_instance()\fR functions
 229 will fail if:
 230 .sp
 231 .ne 2
 232 .na
 233 \fB\fBSCF_ERROR_CONSTRAINT_VIOLATED\fR\fR
 234 .ad
 235 .sp .6
 236 .RS 4n
 237 The function is called on an instance in an inappropriate state.
 238 .RE
 239
 240 .sp
 241 .LP
 242 The \fBscf_error\fR(3SCF) function can be used to retrieve the error value.
 243 .SH ATTRIBUTES
 244 .sp
 245 .LP
 246 See \fBattributes\fR(5) for descriptions of the following attributes:
 247 .sp
 248
 249 .sp
 250 .TS
 251 box;
 252 c | c
 253 l | l .
 254 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 255 _
 256 Interface Stability     Committed
 257 _
 258 MT-Level        Safe
 259 .TE
 260
 261 .SH SEE ALSO
 262 .sp
 263 .LP
 264 \fBsvc.startd\fR(8), \fBlibscf\fR(3LIB), \fBscf_error\fR(3SCF),
 265 \fBattributes\fR(5), \fBsmf_security\fR(5)