usr/src/man/man3scf/scf_snapshot_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_SNAPSHOT_CREATE 3SCF "Aug 27, 2007"
   7 .SH NAME
   8 scf_snapshot_create, scf_snapshot_handle, scf_snapshot_destroy,
   9 scf_snapshot_get_parent, scf_snapshot_get_name, scf_snapshot_update,
  10 scf_instance_get_snapshot \- create and manipulate snapshot handles and
  11 snapshots in the Service 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 \fBscf_snapshot_t *\fR\fBscf_snapshot_create\fR(\fBscf_handle_t *\fR\fIhandle\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBscf_handle_t *\fR\fBscf_snapshot_handle\fR(\fBscf_snapshot_t *\fR\fIsnap\fR);
  24 .fi
  25
  26 .LP
  27 .nf
  28 \fBvoid\fR \fBscf_snapshot_destroy\fR(\fBscf_snapshot_t *\fR\fIsnap\fR);
  29 .fi
  30
  31 .LP
  32 .nf
  33 \fBint\fR \fBscf_snapshot_get_parent\fR(\fBconst scf_snapshot_t *\fR\fIsnap\fR,
  34      \fBscf_instance_t *\fR\fIinst\fR);
  35 .fi
  36
  37 .LP
  38 .nf
  39 \fBssize_t\fR \fBscf_snapshot_get_name\fR(\fBconst scf_snapshot_t *\fR\fIsnap\fR,
  40      \fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIsize\fR);
  41 .fi
  42
  43 .LP
  44 .nf
  45 \fBint\fR \fBscf_snapshot_update\fR(\fBscf_snapshot_t *\fR\fIsnap\fR);
  46 .fi
  47
  48 .LP
  49 .nf
  50 \fBint\fR \fBscf_instance_get_snapshot\fR(\fBconst scf_instance_t *\fR\fIinst\fR,
  51      \fBconst char *\fR\fIname\fR, \fBscf_snapshot_t *\fR\fIsnap\fR);
  52 .fi
  53
  54 .SH DESCRIPTION
  55 .sp
  56 .LP
  57 A snapshot is an unchanging picture of the full set of property groups
  58 associated with an instance. Snapshots are automatically created and managed by
  59 the Solaris Management Facility. See \fBsmf\fR(5).
  60 .sp
  61 .LP
  62 A snapshot consists of a set of snaplevels, each of which holds copies of the
  63 property groups associated with an instance or service in the resolution path
  64 of the base instance. Typically, there is one snaplevel for the instance and
  65 one for the instance's parent service.
  66 .sp
  67 .LP
  68 The \fBscf_snapshot_create()\fR function allocates and initializes a new
  69 \fBscf_snapshot_t\fR bound to \fIhandle\fR. The \fBscf_snapshot_destroy()\fR
  70 function destroys and frees \fIsnap\fR.
  71 .sp
  72 .LP
  73 The \fBscf_snapshot_handle()\fR function retrieves the handle to which
  74 \fIsnap\fR is bound.
  75 .sp
  76 .LP
  77 The \fBscf_snapshot_get_parent()\fR function sets \fIinst\fR to the parent of
  78 the snapshot to which \fIsnap\fR is set.
  79 .sp
  80 .LP
  81 The \fBscf_snapshot_get_name()\fR function retrieves the name of the snapshot
  82 to which \fIsnap\fR is set.
  83 .sp
  84 .LP
  85 The \fBscf_snapshot_update()\fR function reattaches \fIsnap\fR to the latest
  86 version of the snapshot to which \fIsnap\fR is set.
  87 .sp
  88 .LP
  89 The \fBscf_instance_get_snapshot()\fR function sets \fIsnap\fR to the snapshot
  90 specified by \fIname\fR in the instance specified by \fIinst\fR. To walk all of
  91 the snapshots, see \fBscf_iter_instance_snapshots\fR(3SCF).
  92 .sp
  93 .LP
  94 To access the snaplevels of a snapshot, see
  95 \fBscf_snapshot_get_base_snaplevel\fR(3SCF).
  96 .SH RETURN VALUES
  97 .sp
  98 .LP
  99 Upon successful completion, \fBscf_snapshot_create()\fR returns a new
 100 \fBscf_snapshot_t\fR. Otherwise, it returns \fINULL\fR.
 101 .sp
 102 .LP
 103 Upon successful completion, \fBscf_snapshot_handle()\fR returns the handle to
 104 which \fIsnap\fR is bound. Otherwise, it returns \fINULL\fR.
 105 .sp
 106 .LP
 107 Upon successful completion, \fBscf_snapshot_get_name()\fR returns the length of
 108 the string written, not including the terminating null byte. Otherwise, it
 109 returns \fINULL\fR.
 110 .sp
 111 .LP
 112 The \fBscf_snapshot_update()\fR function returns 1 if the snapshot was updated,
 113 0 if the snapshot had not been updated, and -1 on failure.
 114 .sp
 115 .LP
 116 Upon successful completion, \fBscf_snapshot_get_parent()\fR and
 117 \fBscf_instance_get_snapshot()\fR return 0. Otherwise, they return -1.
 118 .SH ERRORS
 119 .sp
 120 .LP
 121 The \fBscf_snapshot_create()\fR function will fail if:
 122 .sp
 123 .ne 2
 124 .na
 125 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
 126 .ad
 127 .sp .6
 128 .RS 4n
 129 The \fIhandle\fR argument is \fINULL\fR.
 130 .RE
 131
 132 .sp
 133 .ne 2
 134 .na
 135 \fB\fBSCF_ERROR_NO_MEMORY\fR\fR
 136 .ad
 137 .sp .6
 138 .RS 4n
 139 There is not enough memory to allocate an \fBscf_snapshot_t\fR.
 140 .RE
 141
 142 .sp
 143 .ne 2
 144 .na
 145 \fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
 146 .ad
 147 .sp .6
 148 .RS 4n
 149 The server does not have adequate resources for a new instance handle.
 150 .RE
 151
 152 .sp
 153 .LP
 154 The \fBscf_snapshot_handle()\fR function will fail if:
 155 .sp
 156 .ne 2
 157 .na
 158 \fB\fBSCF_ERROR_HANDLE_DESTROYED\fR\fR
 159 .ad
 160 .sp .6
 161 .RS 4n
 162 The handle associated with \fIsnap\fR has been destroyed.
 163 .RE
 164
 165 .sp
 166 .LP
 167 The \fBscf_snapshot_get_name()\fR and \fBscf_snapshot_get_parent()\fR functions
 168 will fail if:
 169 .sp
 170 .ne 2
 171 .na
 172 \fB\fBSCF_ERROR_DELETED\fR\fR
 173 .ad
 174 .sp .6
 175 .RS 4n
 176 The snapshot has been deleted.
 177 .RE
 178
 179 .sp
 180 .ne 2
 181 .na
 182 \fB\fBSCF_ERROR_NOT_SET\fR\fR
 183 .ad
 184 .sp .6
 185 .RS 4n
 186 The snapshot is not set.
 187 .RE
 188
 189 .sp
 190 .ne 2
 191 .na
 192 \fB\fBSCF_ERROR_NOT_BOUND\fR\fR
 193 .ad
 194 .sp .6
 195 .RS 4n
 196 The handle is not bound.
 197 .RE
 198
 199 .sp
 200 .ne 2
 201 .na
 202 \fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
 203 .ad
 204 .sp .6
 205 .RS 4n
 206 The connection to the repository was lost.
 207 .RE
 208
 209 .sp
 210 .LP
 211 The \fBscf_snapshot_update()\fR function will fail if:
 212 .sp
 213 .ne 2
 214 .na
 215 \fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
 216 .ad
 217 .sp .6
 218 .RS 4n
 219 The connection to the repository was lost.
 220 .RE
 221
 222 .sp
 223 .ne 2
 224 .na
 225 \fB\fBSCF_ERROR_DELETED\fR\fR
 226 .ad
 227 .sp .6
 228 .RS 4n
 229 An ancestor of the snapshot specified by \fIsnap\fR has been deleted.
 230 .RE
 231
 232 .sp
 233 .ne 2
 234 .na
 235 \fB\fBSCF_ERROR_INTERNAL\fR\fR
 236 .ad
 237 .sp .6
 238 .RS 4n
 239 An internal error occurred. This can happen if \fIsnap\fR has been corrupted.
 240 .RE
 241
 242 .sp
 243 .ne 2
 244 .na
 245 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
 246 .ad
 247 .sp .6
 248 .RS 4n
 249 The \fIsnap\fR argument refers to an invalid \fBscf_snapshot_t\fR.
 250 .RE
 251
 252 .sp
 253 .ne 2
 254 .na
 255 \fB\fBSCF_ERROR_NOT_BOUND\fR\fR
 256 .ad
 257 .sp .6
 258 .RS 4n
 259 The handle is not bound.
 260 .RE
 261
 262 .sp
 263 .ne 2
 264 .na
 265 \fB\fBSCF_ERROR_NOT_SET\fR\fR
 266 .ad
 267 .sp .6
 268 .RS 4n
 269 The snapshot specified by \fIsnap\fR is not set.
 270 .RE
 271
 272 .sp
 273 .LP
 274 The \fBscf_instance_get_snapshot()\fR function will fail if:
 275 .sp
 276 .ne 2
 277 .na
 278 \fB\fBSCF_ERROR_BACKEND_ACCESS\fR\fR
 279 .ad
 280 .sp .6
 281 .RS 4n
 282 The  storage  mechanism  that  the   repository server (\fBsvc.configd\fR(1M))
 283 chose for the operation denied access.
 284 .RE
 285
 286 .sp
 287 .ne 2
 288 .na
 289 \fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
 290 .ad
 291 .sp .6
 292 .RS 4n
 293 The connection to the repository was lost.
 294 .RE
 295
 296 .sp
 297 .ne 2
 298 .na
 299 \fB\fBSCF_ERROR_DELETED\fR\fR
 300 .ad
 301 .sp .6
 302 .RS 4n
 303 The instance has been deleted.
 304 .RE
 305
 306 .sp
 307 .ne 2
 308 .na
 309 \fB\fBSCF_ERROR_HANDLE_MISMATCH\fR\fR
 310 .ad
 311 .sp .6
 312 .RS 4n
 313 The instance and snapshot are not derived from the same handle.
 314 .RE
 315
 316 .sp
 317 .ne 2
 318 .na
 319 \fB\fBSCF_ERROR_INTERNAL\fR\fR
 320 .ad
 321 .sp .6
 322 .RS 4n
 323 An internal error occurred.
 324 .RE
 325
 326 .sp
 327 .ne 2
 328 .na
 329 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
 330 .ad
 331 .sp .6
 332 .RS 4n
 333 The value of the \fIname\fR argument is not a valid snapshot name.
 334 .RE
 335
 336 .sp
 337 .ne 2
 338 .na
 339 \fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
 340 .ad
 341 .sp .6
 342 .RS 4n
 343 The server does not have the resources to complete the request.
 344 .RE
 345
 346 .sp
 347 .ne 2
 348 .na
 349 \fB\fBSCF_ERROR_NOT_BOUND\fR\fR
 350 .ad
 351 .sp .6
 352 .RS 4n
 353 The handle is not bound.
 354 .RE
 355
 356 .sp
 357 .ne 2
 358 .na
 359 \fB\fBSCF_ERROR_NOT_FOUND\fR\fR
 360 .ad
 361 .sp .6
 362 .RS 4n
 363 The snapshot specified by \fIname\fR was not found.
 364 .RE
 365
 366 .sp
 367 .ne 2
 368 .na
 369 \fB\fBSCF_ERROR_NOT_SET\fR\fR
 370 .ad
 371 .sp .6
 372 .RS 4n
 373 The instance is not set.
 374 .RE
 375
 376 .sp
 377 .LP
 378 The \fBscf_error\fR(3SCF) function can be used to retrieve the error value.
 379 .SH ATTRIBUTES
 380 .sp
 381 .LP
 382 See \fBattributes\fR(5) for descriptions of the following attributes:
 383 .sp
 384
 385 .sp
 386 .TS
 387 box;
 388 c | c
 389 l | l .
 390 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 391 _
 392 Interface Stability     Committed
 393 _
 394 MT-Level        Safe
 395 .TE
 396
 397 .SH SEE ALSO
 398 .sp
 399 .LP
 400 \fBlibscf\fR(3LIB), \fBscf_error\fR(3SCF),
 401 \fBscf_iter_instance_snapshots\fR(3SCF),
 402 \fBscf_snapshot_get_base_snaplevel\fR(3SCF), \fBattributes\fR(5), \fBsmf\fR(5)