usr/src/man/man3scf/scf_snaplevel_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_SNAPLEVEL_CREATE 3SCF "Aug 27, 2007"
   7 .SH NAME
   8 scf_snaplevel_create, scf_snaplevel_handle, scf_snaplevel_destroy,
   9 scf_snaplevel_get_parent, scf_snaplevel_get_scope_name,
  10 scf_snaplevel_get_service_name, scf_snaplevel_get_instance_name,
  11 scf_snapshot_get_base_snaplevel, scf_snaplevel_get_next_snaplevel \- create and
  12 manipulate snaplevel handles in the Service Configuration Facility
  13 .SH SYNOPSIS
  14 .LP
  15 .nf
  16 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lscf\fR [ \fIlibrary\fR\&.\|.\|. ]
  17 #include <libscf.h>
  18
  19 \fBscf_snaplevel_t *\fR\fBscf_snaplevel_create\fR(\fBscf_handle_t *\fR\fIhandle\fR);
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fBscf_handle_t *\fR\fBscf_snaplevel_handle\fR(\fBscf_snaplevel_t *\fR\fIlevel\fR);
  25 .fi
  26
  27 .LP
  28 .nf
  29 \fBvoid\fR \fBscf_snaplevel_destroy\fR(\fBscf_snaplevel_t *\fR\fIlevel\fR);
  30 .fi
  31
  32 .LP
  33 .nf
  34 \fBint\fR \fBscf_snaplevel_get_parent\fR(\fBconst scf_snaplevel_t *\fR\fIlevel\fR,
  35      \fBconst scf_snapshot_t *\fR\fIsnap\fR);
  36 .fi
  37
  38 .LP
  39 .nf
  40 \fBssize_t\fR \fBscf_snaplevel_get_scope_name\fR(\fBconst scf_snaplevel_t *\fR\fIlevel\fR,
  41      \fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIsize\fR);
  42 .fi
  43
  44 .LP
  45 .nf
  46 \fBssize_t\fR \fBscf_snaplevel_get_service_name\fR(\fBconst scf_snaplevel_t *\fR\fIlevel\fR,
  47      \fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIsize\fR);
  48 .fi
  49
  50 .LP
  51 .nf
  52 \fBssize_t\fR \fBscf_snaplevel_get_instance_name\fR(\fBconst scf_snaplevel_t *\fR\fIlevel\fR,
  53      \fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIsize\fR);
  54 .fi
  55
  56 .LP
  57 .nf
  58 \fBint\fR \fBscf_snapshot_get_base_snaplevel\fR(\fBconst scf_snapshot_t *\fR\fIsnap\fR,
  59      \fBscf_snaplevel_t *\fR\fIlevel\fR);
  60 .fi
  61
  62 .LP
  63 .nf
  64 \fBint\fR \fBscf_snaplevel_get_next_snaplevel\fR(\fBscf_snaplevel_t *\fR\fIin\fR,
  65      \fBscf_snaplevel_t *\fR\fIout\fR);
  66 .fi
  67
  68 .SH DESCRIPTION
  69 .sp
  70 .LP
  71 A snaplevel holds all of the property groups associated with either a service
  72 or an instance. Each snapshot has an ordered list of snaplevels. Snaplevels
  73 contain the names of the instance or service from which they are derived.
  74 .sp
  75 .LP
  76 An \fBscf_snaplevel_t\fR is an opaque handle that can be set to a single
  77 snaplevel at any given time. When set, the \fBscf_snaplevel_t\fR inherits the
  78 point in time from the \fBscf_snapshot_t\fR from which it comes.
  79 .sp
  80 .LP
  81 The \fBscf_snaplevel_create()\fR function allocates and initializes a new
  82 \fBscf_snaplevel_t\fR bound to \fIhandle\fR. The \fBscf_snaplevel_destroy()\fR
  83 function destroys and frees \fIlevel\fR.
  84 .sp
  85 .LP
  86 The \fBscf_snaplevel_handle()\fR function retrieves the handle to which
  87 \fIlevel\fR is bound.
  88 .sp
  89 .LP
  90 The \fBscf_snaplevel_get_parent()\fR function sets \fIsnap\fR to the parent
  91 snapshot of the snaplevel to which \fIlevel\fR is set.  The snapshot specified
  92 by \fIsnap\fR is attached to the same point in time as level.
  93 .sp
  94 .LP
  95 The \fBscf_snaplevel_get_scope_name()\fR,
  96 \fBscf_snaplevel_get_service_name()\fR, and
  97 \fBscf_snaplevel_get_instance_name()\fR functions retrieve the name of the
  98 scope, service, and instance for the snapshot to which \fIsnap\fR is set. If
  99 the snaplevel is from an instance, all three succeed. If the snaplevel is from
 100 a service, \fBscf_snaplevel_get_instance_name()\fR fails.
 101 .sp
 102 .LP
 103 The \fBscf_snapshot_get_base_snaplevel()\fR function sets \fIlevel\fR to the
 104 first snaplevel in the snapshot to which \fIsnap\fR is set. The
 105 \fBscf_snaplevel_get_next_snaplevel()\fR function sets \fIout\fR to the next
 106 snaplevel after the snaplevel to which \fIin\fR is set. Both the \fIin\fR and
 107 \fIout\fR arguments can point to the same \fBscf_snaplevel_t\fR.
 108 .sp
 109 .LP
 110 To retrieve the property groups associated with a snaplevel, see
 111 \fBscf_iter_snaplevel_pgs\fR(3SCF), \fBscf_iter_snaplevel_pgs_typed\fR(3SCF),
 112 and \fBscf_snaplevel_get_pg\fR(3SCF).
 113 .SH RETURN VALUES
 114 .sp
 115 .LP
 116 Upon successful completion, \fBscf_snaplevel_create()\fR returns a new
 117 \fBscf_snaplevel_t\fR. Otherwise, it returns \fINULL\fR.
 118 .sp
 119 .LP
 120 Upon successful completion, \fBscf_snaplevel_get_scope_name()\fR,
 121 \fBscf_snaplevel_get_service_name()\fR, and
 122 \fBscf_snaplevel_get_instance_name()\fR return the length of the string
 123 written, not including the terminating null byte. Otherwise, they return -1.
 124 .sp
 125 .LP
 126 Upon successful completion, \fBscf_snaplevel_get_parent()\fR,
 127 \fBscf_snapshot_get_base_snaplevel()\fR, and
 128 \fBscf_snaplevel_get_next_snaplevel()\fR return. Otherwise, they return -1.
 129 .SH ERRORS
 130 .sp
 131 .LP
 132 The \fBscf_snaplevel_create()\fR function will fail if:
 133 .sp
 134 .ne 2
 135 .na
 136 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
 137 .ad
 138 .RS 30n
 139 The \fIhandle\fR argument is \fINULL\fR.
 140 .RE
 141
 142 .sp
 143 .ne 2
 144 .na
 145 \fB\fBSCF_ERROR_NO_MEMORY\fR\fR
 146 .ad
 147 .RS 30n
 148 There is not enough memory to allocate an \fBscf_snaplevel_t\fR.
 149 .RE
 150
 151 .sp
 152 .ne 2
 153 .na
 154 \fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
 155 .ad
 156 .RS 30n
 157 The server does not have adequate resources for a new snapshot handle.
 158 .RE
 159
 160 .sp
 161 .LP
 162 The \fBscf_snaplevel_get_scope_name()\fR,
 163 \fBscf_snaplevel_get_service_name()\fR,
 164 \fBscf_snaplevel_get_instance_name()\fR, and \fBscf_snaplevel_get_parent()\fR
 165 functions will fail if:
 166 .sp
 167 .ne 2
 168 .na
 169 \fB\fBSCF_ERROR_DELETED\fR\fR
 170 .ad
 171 .sp .6
 172 .RS 4n
 173 The object referred to by \fIlevel\fR has been deleted.
 174 .RE
 175
 176 .sp
 177 .ne 2
 178 .na
 179 \fB\fBSCF_ERROR_NOT_SET\fR\fR
 180 .ad
 181 .sp .6
 182 .RS 4n
 183 The snaplevel is not set.
 184 .RE
 185
 186 .sp
 187 .ne 2
 188 .na
 189 \fB\fBSCF_ERROR_NOT_BOUND\fR\fR
 190 .ad
 191 .sp .6
 192 .RS 4n
 193 The handle is not bound.
 194 .RE
 195
 196 .sp
 197 .ne 2
 198 .na
 199 \fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
 200 .ad
 201 .sp .6
 202 .RS 4n
 203 The connection to the repository was lost.
 204 .RE
 205
 206 .sp
 207 .LP
 208 The \fBscf_snaplevel_get_instance_name()\fR function will fail if:
 209 .sp
 210 .ne 2
 211 .na
 212 \fB\fBSCF_ERROR_CONSTRAINT_VIOLATED\fR\fR
 213 .ad
 214 .sp .6
 215 .RS 4n
 216 The snaplevel is derived from a service.
 217 .RE
 218
 219 .sp
 220 .LP
 221 The \fBscf_snapshot_get_base_snaplevel()\fR function will fail if:
 222 .sp
 223 .ne 2
 224 .na
 225 \fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
 226 .ad
 227 .sp .6
 228 .RS 4n
 229 The connection to the repository was lost.
 230 .RE
 231
 232 .sp
 233 .ne 2
 234 .na
 235 \fB\fBSCF_ERROR_DELETED\fR\fR
 236 .ad
 237 .sp .6
 238 .RS 4n
 239 The snapshot has been deleted.
 240 .RE
 241
 242 .sp
 243 .ne 2
 244 .na
 245 \fB\fBSCF_ERROR_HANDLE_MISMATCH\fR\fR
 246 .ad
 247 .sp .6
 248 .RS 4n
 249 The snapshot and snaplevel are not derived from the same handle.
 250 .RE
 251
 252 .sp
 253 .ne 2
 254 .na
 255 \fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
 256 .ad
 257 .sp .6
 258 .RS 4n
 259 The server does not have the resources to complete the request.
 260 .RE
 261
 262 .sp
 263 .ne 2
 264 .na
 265 \fB\fBSCF_ERROR_NOT_BOUND\fR\fR
 266 .ad
 267 .sp .6
 268 .RS 4n
 269 The handle is not bound.
 270 .RE
 271
 272 .sp
 273 .ne 2
 274 .na
 275 \fB\fBSCF_ERROR_NOT_FOUND\fR\fR
 276 .ad
 277 .sp .6
 278 .RS 4n
 279 There are no snaplevels in this snapshot.
 280 .RE
 281
 282 .sp
 283 .ne 2
 284 .na
 285 \fB\fBSCF_ERROR_NOT_SET\fR\fR
 286 .ad
 287 .sp .6
 288 .RS 4n
 289 The snapshot is not set.
 290 .RE
 291
 292 .sp
 293 .LP
 294 The \fBscf_snaplevel_get_next_snaplevel()\fR function will fail if:
 295 .sp
 296 .ne 2
 297 .na
 298 \fB\fBSCF_ERROR_DELETED\fR\fR
 299 .ad
 300 .sp .6
 301 .RS 4n
 302 The snaplevel has been deleted.
 303 .RE
 304
 305 .sp
 306 .ne 2
 307 .na
 308 \fB\fBSCF_ERROR_NOT_SET\fR\fR
 309 .ad
 310 .sp .6
 311 .RS 4n
 312 The snaplevel is not set.
 313 .RE
 314
 315 .sp
 316 .ne 2
 317 .na
 318 \fB\fBSCF_ERROR_HANDLE_MISMATCH\fR\fR
 319 .ad
 320 .sp .6
 321 .RS 4n
 322 The \fIin\fR and \fIout\fR arguments are not derived from the same handle.
 323 .RE
 324
 325 .sp
 326 .ne 2
 327 .na
 328 \fB\fBSCF_ERROR_NOT_BOUND\fR\fR
 329 .ad
 330 .sp .6
 331 .RS 4n
 332 The handle is not bound.
 333 .RE
 334
 335 .sp
 336 .ne 2
 337 .na
 338 \fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
 339 .ad
 340 .sp .6
 341 .RS 4n
 342 The connection to the repository was lost.
 343 .RE
 344
 345 .sp
 346 .ne 2
 347 .na
 348 \fB\fBSCF_ERROR_NOT_FOUND\fR\fR
 349 .ad
 350 .sp .6
 351 .RS 4n
 352 There are no more snaplevels in this snapshot.
 353 .RE
 354
 355 .sp
 356 .LP
 357 The \fBscf_error\fR(3SCF) function can be used to retrieve the error value.
 358 .SH ATTRIBUTES
 359 .sp
 360 .LP
 361 See \fBattributes\fR(5) for descriptions of the following attributes:
 362 .sp
 363
 364 .sp
 365 .TS
 366 box;
 367 c | c
 368 l | l .
 369 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 370 _
 371 Interface Stability     Committed
 372 _
 373 MT-Level        Safe
 374 .TE
 375
 376 .SH SEE ALSO
 377 .sp
 378 .LP
 379 \fBlibscf\fR(3LIB), \fBscf_error\fR(3SCF), \fBscf_iter_snaplevel_pgs\fR(3SCF),
 380 \fBscf_iter_snaplevel_pgs_typed\fR(3SCF), \fBscf_snaplevel_get_pg\fR(3SCF),
 381 \fBattributes\fR(5)