usr/src/man/man3scf/scf_tmpl_prop_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_PROP_CREATE 3SCF "Oct 28, 2008"
   7 .SH NAME
   8 scf_tmpl_prop_create, scf_tmpl_prop_reset, scf_tmpl_prop_destroy,
   9 scf_tmpl_get_by_prop, scf_tmpl_iter_props \- template property functions
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lscf\fR [ \fIlibrary\fR\&.\|.\|. ]
  14 #include <libscf.h>
  15
  16 \fBscf_prop_tmpl_t *\fR\fBscf_tmpl_prop_create\fR(\fBscf_handle_t *\fR\fIhandle\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBvoid\fR \fBscf_tmpl_prop_reset\fR(\fBscf_prop_tmpl_t *\fR\fIprop_tmpl\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBvoid\fR \fBscf_tmpl_prop_destroy\fR(\fBscf_prop_tmpl_t *\fR\fIprop_tmpl\fR);
  27 .fi
  28
  29 .LP
  30 .nf
  31 \fBint\fR \fBscf_tmpl_get_by_prop\fR(\fBscf_pg_tmpl_t *\fR\fIpg_tmpl\fR,
  32      \fBconst char *\fR\fIprop\fR, \fBscf_prop_tmpl_t *\fR\fIprop_tmpl\fR, \fBint\fR \fIflags\fR)
  33 .fi
  34
  35 .LP
  36 .nf
  37 \fBint\fR \fBscf_tmpl_iter_props\fR(\fBscf_pg_tmpl_t *\fR\fIpg_tmpl\fR, \fBconst char *\fR\fIfmri\fR,
  38      \fBscf_prop_tmpl_t *\fR\fIprop_tmpl\fR, \fBint\fR \fIflags\fR);
  39 .fi
  40
  41 .SH DESCRIPTION
  42 .sp
  43 .LP
  44 The template property functions locate and give access to metadata about
  45 properties.  They require that the template for the property group containing
  46 the property has already been located by one of the
  47 \fBscf_tmpl_pg_create\fR(3SCF) suite of functions.
  48 .sp
  49 .LP
  50 Once retrieved, the \fBscf_prop_tmpl_t\fR can be explored using the
  51 \fBscf_tmpl_prop_name\fR(3SCF) suite of functions.
  52 .sp
  53 .LP
  54 Before calling \fBscf_tmpl_get_by_prop()\fR or \fBscf_tmpl_iter_props()\fR, the
  55 \fBscf_prop_tmpl_t\fR must be allocated by \fBscf_tmpl_prop_create\fR. The
  56 \fBscf_prop_tmpl_t\fR can be reset to contain no template information with
  57 \fBscf_tmpl_prop_reset()\fR, so that it can be used to start an iteration from
  58 scratch. All associated memory can be freed with \fBscf_tmpl_prop_destroy()\fR.
  59 .sp
  60 .LP
  61 The \fBscf_tmpl_get_by_prop()\fR function locates template data about the
  62 property name specified.
  63 .sp
  64 .LP
  65 The \fBscf_tmpl_iter_props()\fR function iterates across all property templates
  66 defined in the specified property group template.
  67 .sp
  68 .LP
  69 The iterator state for \fBscf_tmpl_iter_props()\fR is stored on the property
  70 template data structure. The data structure should be allocated with
  71 \fBscf_tmpl_prop_create()\fR, and to continue the iteration the previously
  72 returned structure should be passed in as an argument.
  73 .SH RETURN VALUES
  74 .sp
  75 .LP
  76 The \fBscf_tmpl_get_by_prop()\fR function returns -1 on failure and 0 on
  77 success.
  78 .sp
  79 .LP
  80 The \fBscf_tmpl_iter_props()\fR function returns 1 on successful completion. If
  81 the iteration is complete, it returns 0. It returns -1 on error.
  82 .SH ERRORS
  83 .sp
  84 .LP
  85 The \fBscf_tmpl_get_by_prop()\fR and \fBscf_tmpl_iter_props()\fR functions will
  86 fail if:
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fBSCF_ERROR_BACKEND_ACCESS\fR\fR
  91 .ad
  92 .sp .6
  93 .RS 4n
  94 The storage mechanism that the repository server (\fBsvc.configd\fR(1M)) chose
  95 for the operation denied access.
  96 .RE
  97
  98 .sp
  99 .ne 2
 100 .na
 101 \fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
 102 .ad
 103 .sp .6
 104 .RS 4n
 105 The connection to the repository was lost.
 106 .RE
 107
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fBSCF_ERROR_DELETED\fR\fR
 112 .ad
 113 .sp .6
 114 .RS 4n
 115 The instance or its template property group has been deleted.
 116 .RE
 117
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fBSCF_ERROR_HANDLE_DESTROYED\fR\fR
 122 .ad
 123 .sp .6
 124 .RS 4n
 125 The handle passed in has been destroyed.
 126 .RE
 127
 128 .sp
 129 .ne 2
 130 .na
 131 \fB\fBSCF_ERROR_INTERNAL\fR\fR
 132 .ad
 133 .sp .6
 134 .RS 4n
 135 An internal error occurred.
 136 .RE
 137
 138 .sp
 139 .ne 2
 140 .na
 141 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
 142 .ad
 143 .sp .6
 144 .RS 4n
 145 One of the arguments is invalid.
 146 .RE
 147
 148 .sp
 149 .ne 2
 150 .na
 151 \fB\fBSCF_ERROR_NO_MEMORY\fR\fR
 152 .ad
 153 .sp .6
 154 .RS 4n
 155 There is not enough memory to populate the \fBscf_prop_tmpl_t\fR.
 156 .RE
 157
 158 .sp
 159 .ne 2
 160 .na
 161 \fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
 162 .ad
 163 .sp .6
 164 .RS 4n
 165 The server does not have adequate resources to complete the request.
 166 .RE
 167
 168 .sp
 169 .ne 2
 170 .na
 171 \fB\fBSCF_ERROR_NOT_BOUND\fR\fR
 172 .ad
 173 .sp .6
 174 .RS 4n
 175 The handle is not currently bound.
 176 .RE
 177
 178 .sp
 179 .LP
 180 The \fBscf_tmpl_get_by_prop()\fR function will fail if:
 181 .sp
 182 .ne 2
 183 .na
 184 \fB\fBSCF_ERROR_NOT_FOUND\fR\fR
 185 .ad
 186 .sp .6
 187 .RS 4n
 188 Template object matching property doesn't exist in the repository.
 189 .RE
 190
 191 .sp
 192 .ne 2
 193 .na
 194 \fB\fBSCF_ERROR_TYPE_MISMATCH\fR\fR
 195 .ad
 196 .sp .6
 197 .RS 4n
 198 Matching template object is the wrong type in the repository.
 199 .RE
 200
 201 .sp
 202 .ne 2
 203 .na
 204 \fB\fBSCF_ERROR_PERMISSION_DENIED\fR\fR
 205 .ad
 206 .sp .6
 207 .RS 4n
 208 The template could not be read due to access restrictions.
 209 .RE
 210
 211 .sp
 212 .ne 2
 213 .na
 214 \fB\fBSCF_ERROR_TEMPLATE_INVALID\fR\fR
 215 .ad
 216 .sp .6
 217 .RS 4n
 218 The template data is invalid.
 219 .RE
 220
 221 .sp
 222 .LP
 223 The \fBscf_tmpl_prop_create()\fR function will fail if:
 224 .sp
 225 .ne 2
 226 .na
 227 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
 228 .ad
 229 .RS 30n
 230 The \fIhandle\fR argument is \fINULL\fR.
 231 .RE
 232
 233 .sp
 234 .ne 2
 235 .na
 236 \fB\fBSCF_ERROR_NO_MEMORY\fR\fR
 237 .ad
 238 .RS 30n
 239 There is no memory available.
 240 .RE
 241
 242 .SH ATTRIBUTES
 243 .sp
 244 .LP
 245 See \fBattributes\fR(5) for descriptions of the following attributes:
 246 .sp
 247
 248 .sp
 249 .TS
 250 box;
 251 c | c
 252 l | l .
 253 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 254 _
 255 Interface Stability     Committed
 256 _
 257 MT-Level        Safe
 258 .TE
 259
 260 .SH SEE ALSO
 261 .sp
 262 .LP
 263 \fBsvc.configd\fR(1M), \fBscf_tmpl_pg_create\fR(3SCF),
 264 \fBscf_tmpl_prop_name\fR(3SCF), \fBattributes\fR(5), \fBsmf_template\fR(5)