usr/src/man/man3scf/scf_handle_create.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 SCF_HANDLE_CREATE 3SCF "Aug 17, 2007"
   7 .SH NAME
   8 scf_handle_create, scf_handle_destroy, scf_handle_decorate, scf_handle_bind,
   9 scf_handle_unbind, scf_myname \- Service Configuration Facility handle
  10 functions
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lscf\fR [ \fIlibrary\fR\&.\|.\|. ]
  15 #include <libscf.h>
  16
  17 \fBscf_handle_t *\fR\fBscf_handle_create\fR(\fBscf_version_t\fR \fIversion\fR);
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBvoid\fR \fBscf_handle_destroy\fR(\fBscf_handle_t *\fR\fIhandle\fR);
  23 .fi
  24
  25 .LP
  26 .nf
  27 \fBint\fR \fBscf_handle_decorate\fR(\fBscf_handle_t *\fR\fIhandle\fR, \fBconst char *\fR\fIparam\fR,
  28      \fBscf_value_t *\fR\fIvalue\fR);
  29 .fi
  30
  31 .LP
  32 .nf
  33 \fBint\fR \fBscf_handle_bind\fR(\fBscf_handle_t *\fR\fIhandle\fR);
  34 .fi
  35
  36 .LP
  37 .nf
  38 \fBint\fR \fBscf_handle_unbind\fR(\fBscf_handle_t *\fR\fIhandle\fR);
  39 .fi
  40
  41 .LP
  42 .nf
  43 \fBssize_t\fR \fBscf_myname\fR(\fBscf_handle_t *\fR\fIhandle\fR, \fBchar *\fR\fIout\fR, \fBsize_t\fR \fIsz\fR);
  44 .fi
  45
  46 .SH DESCRIPTION
  47 .sp
  48 .LP
  49 The \fBscf_handle_create()\fR function creates a new Service Configuration
  50 Facility handle that is used as the base for all communication with the
  51 configuration repository. The version argument must be \fBSCF_VERSION\fR.
  52 .sp
  53 .LP
  54 The \fBscf_handle_decorate()\fR function sets a single connection-level
  55 parameter, \fIparam\fR, to the supplied value. If \fIvalue\fR is
  56 \fBSCF_DECORATE_CLEAR\fR, \fIparam\fR is reset to its default state. Values
  57 passed to \fBscf_handle_decorate()\fR can be reset, reused, or destroyed. The
  58 values set do not take effect until \fBscf_handle_bind()\fR is called. Any
  59 invalid values will not cause errors prior to the call to
  60 \fBscf_handle_bind()\fR. The only available decorations is:
  61 .sp
  62 .ne 2
  63 .na
  64 \fBdebug\fR
  65 .ad
  66 .RS 9n
  67 (count) Set the debugging flags.
  68 .RE
  69
  70 .sp
  71 .LP
  72 The \fBscf_handle_bind()\fR function binds the handle to a running
  73 \fBsvc.configd\fR(1M) daemon, using the current decorations to modify the
  74 connection. All states derived from the handle are reset immediately after a
  75 successful binding.
  76 .sp
  77 .LP
  78 The \fBscf_handle_unbind()\fR function severs an existing repository connection
  79 or clears the in-client state for a broken connection.
  80 .sp
  81 .LP
  82 The \fBscf_handle_destroy()\fR function destroys and frees an SCF handle. It is
  83 illegal to use the handle after calling \fBscf_handle_destroy()\fR. Actions on
  84 subordinate objects act as if the handle is unbound.
  85 .sp
  86 .LP
  87 The \fBscf_myname()\fR function retrieves the FMRI for the service of which the
  88 connecting process is a part. If the full FMRI does not fit in the provided
  89 buffer, it is truncated and, if \fIsz\fR > 0, zero-terminated.
  90 .SH RETURN VALUES
  91 .sp
  92 .LP
  93 Upon successful completion, \fBscf_handle_create()\fR returns the new handle.
  94 Otherwise, it returns \fINULL\fR.
  95 .sp
  96 .LP
  97 Upon successful completion, \fBscf_handle_decorate()\fR,
  98 \fBscf_handle_bind()\fR, and \fBscf_handle_unbind()\fR return 0. Otherwise,
  99 they return -1.
 100 .sp
 101 .LP
 102 The \fBscf_myname()\fR function returns the length of the full FMRI. Otherwise,
 103 it returns -1.
 104 .SH ERRORS
 105 .sp
 106 .LP
 107 The \fBscf_handle_create()\fR function will fail if:
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fBSCF_ERROR_NO_MEMORY\fR\fR
 112 .ad
 113 .RS 30n
 114 There is no memory available.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fBSCF_ERROR_VERSION_MISMATCH\fR\fR
 121 .ad
 122 .RS 30n
 123 The version is invalid, or the application was compiled against a version of
 124 the library that is more recent than the one on the system.
 125 .RE
 126
 127 .sp
 128 .LP
 129 The \fBscf_handle_decorate()\fR function will fail if:
 130 .sp
 131 .ne 2
 132 .na
 133 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
 134 .ad
 135 .RS 30n
 136 The \fIparam\fR argument is not a recognized parameter.
 137 .RE
 138
 139 .sp
 140 .ne 2
 141 .na
 142 \fB\fBSCF_ERROR_TYPE_MISMATCH\fR\fR
 143 .ad
 144 .RS 30n
 145 The \fIvalue\fR argument does not match the expected type for param.
 146 .RE
 147
 148 .sp
 149 .ne 2
 150 .na
 151 \fB\fBSCF_ERROR_NOT_SET\fR\fR
 152 .ad
 153 .RS 30n
 154 The \fIvalue\fR argument is not set.
 155 .RE
 156
 157 .sp
 158 .ne 2
 159 .na
 160 \fB\fBSCF_ERROR_IN_USE\fR\fR
 161 .ad
 162 .RS 30n
 163 The handle is currently bound.
 164 .RE
 165
 166 .sp
 167 .ne 2
 168 .na
 169 \fB\fBSCF_ERROR_HANDLE_MISMATCH\fR\fR
 170 .ad
 171 .RS 30n
 172 The \fIvalue\fR argument is not derived from \fIhandle\fR.
 173 .RE
 174
 175 .sp
 176 .LP
 177 The \fBscf_handle_bind()\fR function will fail if:
 178 .sp
 179 .ne 2
 180 .na
 181 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
 182 .ad
 183 .RS 30n
 184 One of the decorations was invalid.
 185 .RE
 186
 187 .sp
 188 .ne 2
 189 .na
 190 \fB\fBSCF_ERROR_NO_SERVER\fR\fR
 191 .ad
 192 .RS 30n
 193 The repository server is not running.
 194 .RE
 195
 196 .sp
 197 .ne 2
 198 .na
 199 \fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
 200 .ad
 201 .RS 30n
 202 The server does not have adequate resources for a new connection.
 203 .RE
 204
 205 .sp
 206 .ne 2
 207 .na
 208 \fB\fBSCF_ERROR_IN_USE\fR\fR
 209 .ad
 210 .RS 30n
 211 The handle is already bound.
 212 .RE
 213
 214 .sp
 215 .LP
 216 The \fBscf_handle_unbind()\fR function will fail if:
 217 .sp
 218 .ne 2
 219 .na
 220 \fB\fBSCF_ERROR_NOT_BOUND\fR\fR
 221 .ad
 222 .RS 23n
 223 The handle is not bound.
 224 .RE
 225
 226 .sp
 227 .LP
 228 The \fBscf_handle_myname()\fR function will fail if:
 229 .sp
 230 .ne 2
 231 .na
 232 \fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
 233 .ad
 234 .sp .6
 235 .RS 4n
 236 The connection to the repository was lost.
 237 .RE
 238
 239 .sp
 240 .ne 2
 241 .na
 242 \fB\fBSCF_ERROR_NOT_BOUND\fR\fR
 243 .ad
 244 .sp .6
 245 .RS 4n
 246 The handle is not bound.
 247 .RE
 248
 249 .sp
 250 .ne 2
 251 .na
 252 \fB\fBSCF_ERROR_NOT_SET\fR\fR
 253 .ad
 254 .sp .6
 255 .RS 4n
 256 This process is not marked as a SMF service.
 257 .RE
 258
 259 .sp
 260 .LP
 261 The \fBscf_error\fR(3SCF) function can be used to retrieve the error value.
 262 .SH ATTRIBUTES
 263 .sp
 264 .LP
 265 See \fBattributes\fR(5) for descriptions of the following attributes:
 266 .sp
 267
 268 .sp
 269 .TS
 270 box;
 271 c | c
 272 l | l .
 273 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 274 _
 275 Interface Stability     Committed
 276 _
 277 MT-Level        See below.
 278 .TE
 279
 280 .sp
 281 .LP
 282 Operations on a single handle (and the objects associated with it) are Safe.
 283 Operations on different handles are MT-Safe. Objects associated with different
 284 handles cannot be mixed, as this will lead to an
 285 \fBSCF_ERROR_HANDLE_MISMATCH\fR error.
 286 .SH SEE ALSO
 287 .sp
 288 .LP
 289 \fBlibscf\fR(3LIB), \fBscf_error\fR(3SCF), \fBattributes\fR(5)