usr/src/man/man3scf/scf_tmpl_pg_create.3scf

   1 '\" te
   2 .\" Copyright (c) 2008, 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_TMPL_PG_CREATE 3SCF "Oct 28, 2008"
   7 .SH NAME
   8 scf_tmpl_pg_create, scf_tmpl_pg_reset, scf_tmpl_pg_destroy,
   9 scf_tmpl_get_by_pg_name, scf_tmpl_get_by_pg, scf_tmpl_iter_pgs \- template
  10 property group 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_pg_tmpl_t *\fR\fBscf_tmpl_pg_create\fR(\fBscf_handle_t *\fR\fIhandle\fR);
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBvoid\fR \fBscf_tmpl_pg_reset\fR(\fBscf_pg_tmpl_t *\fR\fIpg_tmpl\fR);
  23 .fi
  24
  25 .LP
  26 .nf
  27 \fBvoid\fR \fBscf_tmpl_pg_destroy\fR(\fBscf_pg_tmpl_t *\fR\fIpg_tmpl\fR);
  28 .fi
  29
  30 .LP
  31 .nf
  32 \fBint\fR \fBscf_tmpl_get_by_pg_name\fR(\fBconst char *\fR\fIinstance_fmri\fR,
  33      \fBconst char *\fR\fIsnapshot\fR, \fBconst char *\fR\fIpg_name\fR,
  34      \fBconst char *\fR\fIpg_type\fR, \fBscf_pg_tmpl_t *\fR\fIpg_tmpl\fR, \fBint\fR \fIflags\fR);
  35 .fi
  36
  37 .LP
  38 .nf
  39 \fBint\fR \fBscf_tmpl_get_by_pg\fR(\fBscf_propertygroup_t *\fR\fIpg\fR,
  40      \fBscf_pg_tmpl_t *\fR\fIpg_tmpl\fR, \fBint\fR \fIflags\fR)
  41 .fi
  42
  43 .LP
  44 .nf
  45 \fBint\fR \fBscf_tmpl_iter_pgs\fR(\fBscf_pg_tmpl_t *\fR\fIpg_tmpl\fR, \fBconst char *\fR\fIfmri\fR,
  46      \fBconst char *\fR\fIsnapshot\fR, \fBconst char *\fR\fIpg_type\fR, \fBint\fR \fIflags\fR);
  47 .fi
  48
  49 .SH DESCRIPTION
  50 .sp
  51 .LP
  52 The template property group functions locate and give access to metadata about
  53 SMF configuration for service instances. They are used to directly access
  54 property group metadata and explore metadata for properties contained in those
  55 property groups.
  56 .sp
  57 .LP
  58 A property group does not need to be currently defined in order to explore
  59 metadata about it, as long as the metadata is defined.  Thus, the property
  60 group template functions operate on strings rather than
  61 \fBscf_propertygroup_t\fR entities.
  62 .sp
  63 .LP
  64 By default, when an instance FMRI is specified, \fBscf_tmpl_get_by_pg_name()\fR
  65 and \fBscf_tmpl_iter_pgs()\fR lookup composed data from the running snapshot of
  66 the instance. A different snapshot may be explicitly selected by specifying a
  67 valid snapshot name rather than  NULL for the snapshot argument. If a service
  68 FMRI is specified, the current properties are used.
  69 .sp
  70 .LP
  71 By default, these functions also explore template data defined by the service
  72 or instance itself, the service's restarter, and global template data. See
  73 \fBsmf_template\fR(5) for more information about this composition.
  74 .sp
  75 .LP
  76 Once retrieved, the \fBscf_pg_tmpl_t\fR can be explored using the
  77 \fBscf_tmpl_pg_name\fR(3SCF) and \fBscf_tmpl_prop_create\fR(3SCF) suite of
  78 functions.
  79 .sp
  80 .LP
  81 Before calling \fBscf_tmpl_get_by_pg()\fR, \fBscf_tmpl_get_by_pg_name()\fR, or
  82 \fBscf_tmpl_iter_pgs()\fR, the \fBscf_pg_tmpl_t\fR must be allocated by
  83 \fBscf_tmpl_pg_create()\fR. The \fBscf_pg_tmpl_t\fR can be reset to contain no
  84 template information with \fBscf_tmpl_pg_reset()\fR, so that it can be used to
  85 start an iteration from scratch. All associated memory can be freed with
  86 \fBscf_tmpl_pg_destroy()\fR.
  87 .sp
  88 .LP
  89 The \fBscf_tmpl_get_by_pg()\fR function locates the most specific matching
  90 template for the property group supplied. The parent of that property group can
  91 be either a service or an instance.
  92 .sp
  93 .LP
  94 The \fBscf_tmpl_get_by_pg_name()\fR function locates the most specific matching
  95 template for the property group as specified. As described above, when  the
  96 snapshot argument is \fINULL\fR the default running snapshot is used. If flags
  97 includes \fBSCF_PG_TMPL_FLAG_CURRENT\fR, the snapshot argument is ignored and
  98 the current configuration is used. If flags includes
  99 \fBSCF_PG_TMPL_FLAG_EXACT\fR, only the exact FMRI is looked up. Either or both
 100 of the \fIpg_name\fR and \fIpg_type\fR arguments may be specified as
 101 \fINULL\fR. In this case, \fIpg_name\fR and/or \fIpg_type\fR is wildcarded and
 102 matches any value. The most specific snapshot matching those arguments is
 103 returned.
 104 .sp
 105 .LP
 106 The \fBscf_tmpl_iter_pgs()\fR function iterates across all templates defined
 107 for the specified FMRI, snapshot, and optional property group type. It also
 108 takes an optional flags argument. If flags includes
 109 \fBSCF_PG_TMPL_FLAG_CURRENT\fR, the snapshot argument is ignored and the
 110 "running" snapshot is used. \fBSCF_PG_TMPL_FLAG_REQUIRED\fR searches only for
 111 required property groups. \fBSCF_PG_TMPL_FLAG_EXACT\fR looks only at the exact
 112 FMRI provided for templates, and not for templates defined on its restarter or
 113 globally.
 114 .sp
 115 .LP
 116 The iterator state for \fBscf_tmpl_iter_pgs()\fR is stored on the template data
 117 structure. The data structure should be allocated with
 118 \fBscf_tmpl_pg_create()\fR and to continue the iteration the previously
 119 returned structure should be passed in as an argument.
 120 .SH RETURN VALUES
 121 .sp
 122 .LP
 123 The \fBscf_tmpl_pg_create()\fR function returns \fINULL\fR on failure and a
 124 pointer to an allocated and populated \fBscf_pg_tmpl_t\fR on success. The
 125 caller is responsible for freeing the memory with \fBscf_tmpl_pg_destroy()\fR.
 126 .sp
 127 .LP
 128 The \fBscf_tmpl_get_by_pg()\fR and \fBscf_tmpl_get_by_pg_name()\fR functions
 129 return 0 on success and -1 on failure.
 130 .sp
 131 .LP
 132 The \fBscf_tmpl_iter_pgs()\fR function returns 1 on successful completion. If
 133 the iteration is complete, it returns 0. It returns -1 on error.
 134 .SH ERRORS
 135 .sp
 136 .LP
 137 The \fBscf_tmpl_get_by_pg()\fR, \fBscf_tmpl_get_by_pg_name()\fR, and
 138 \fBscf_tmpl_iter_pgs()\fR functions will fail if:
 139 .sp
 140 .ne 2
 141 .na
 142 \fB\fBSCF_ERROR_BACKEND_ACCESS\fR\fR
 143 .ad
 144 .sp .6
 145 .RS 4n
 146 The storage mechanism that the repository server (\fBsvc.configd\fR(1M)) chose
 147 for the operation denied access.
 148 .RE
 149
 150 .sp
 151 .ne 2
 152 .na
 153 \fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
 154 .ad
 155 .sp .6
 156 .RS 4n
 157 The connection to the repository was lost.
 158 .RE
 159
 160 .sp
 161 .ne 2
 162 .na
 163 \fB\fBSCF_ERROR_DELETED\fR\fR
 164 .ad
 165 .sp .6
 166 .RS 4n
 167 The instance or its template property group has been deleted.
 168 .RE
 169
 170 .sp
 171 .ne 2
 172 .na
 173 \fB\fBSCF_ERROR_HANDLE_DESTROYED\fR\fR
 174 .ad
 175 .sp .6
 176 .RS 4n
 177 The handle passed in has been destroyed.
 178 .RE
 179
 180 .sp
 181 .ne 2
 182 .na
 183 \fB\fBSCF_ERROR_INTERNAL\fR\fR
 184 .ad
 185 .sp .6
 186 .RS 4n
 187 An internal error occurred.
 188 .RE
 189
 190 .sp
 191 .ne 2
 192 .na
 193 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
 194 .ad
 195 .sp .6
 196 .RS 4n
 197 The \fIhandle\fR argument, \fIfmri\fR argument, snapshot name, \fIpg_name\fR,
 198 or \fIpg\fR is invalid.
 199 .RE
 200
 201 .sp
 202 .ne 2
 203 .na
 204 \fB\fBSCF_ERROR_NO_MEMORY\fR\fR
 205 .ad
 206 .sp .6
 207 .RS 4n
 208 There is not enough memory to populate the \fBscf_pg_tmpl_t\fR.
 209 .RE
 210
 211 .sp
 212 .ne 2
 213 .na
 214 \fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
 215 .ad
 216 .sp .6
 217 .RS 4n
 218 The server does not have adequate resources to complete the request.
 219 .RE
 220
 221 .sp
 222 .ne 2
 223 .na
 224 \fB\fBSCF_ERROR_NOT_BOUND\fR\fR
 225 .ad
 226 .sp .6
 227 .RS 4n
 228 The handle is not currently bound.
 229 .RE
 230
 231 .sp
 232 .ne 2
 233 .na
 234 \fB\fBSCF_ERROR_NOT_FOUND\fR\fR
 235 .ad
 236 .sp .6
 237 .RS 4n
 238 The object matching FMRI does not exist in the repository, or the snapshot does
 239 not exist.
 240 .RE
 241
 242 .sp
 243 .ne 2
 244 .na
 245 \fB\fBSCF_ERROR_PERMISSION_DENIED\fR\fR
 246 .ad
 247 .sp .6
 248 .RS 4n
 249 The template could not be read due to access restrictions.
 250 .RE
 251
 252 .sp
 253 .LP
 254 The \fBscf_tmpl_get_by_pg()\fR function will fail if:
 255 .sp
 256 .ne 2
 257 .na
 258 \fB\fBSCF_ERROR_NOT_SET\fR\fR
 259 .ad
 260 .RS 21n
 261 The property group specified by \fIpg\fR is not set.
 262 .RE
 263
 264 .sp
 265 .LP
 266 The \fBscf_tmpl_pg_create()\fR function will fail if:
 267 .sp
 268 .ne 2
 269 .na
 270 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
 271 .ad
 272 .RS 30n
 273 The handle argument is \fINULL\fR.
 274 .RE
 275
 276 .sp
 277 .ne 2
 278 .na
 279 \fB\fBSCF_ERROR_NO_MEMORY\fR\fR
 280 .ad
 281 .RS 30n
 282 There is no memory available.
 283 .RE
 284
 285 .SH ATTRIBUTES
 286 .sp
 287 .LP
 288 See \fBattributes\fR(5) for descriptions of the following attributes:
 289 .sp
 290
 291 .sp
 292 .TS
 293 box;
 294 c | c
 295 l | l .
 296 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 297 _
 298 Interface Stability     Committed
 299 _
 300 MT-Level        Safe
 301 .TE
 302
 303 .SH SEE ALSO
 304 .sp
 305 .LP
 306 \fBsvc.configd\fR(1M), \fBscf_tmpl_pg_name\fR(3SCF),
 307 \fBscf_tmpl_prop_create\fR(3SCF), \fBattributes\fR(5), \fBsmf_template\fR(5)