usr/src/man/man3scf/scf_tmpl_pg_name.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_NAME 3SCF "Oct 28, 2008"
   7 .SH NAME
   8 scf_tmpl_pg_name, scf_tmpl_pg_type, scf_tmpl_pg_target, scf_tmpl_pg_required,
   9 scf_tmpl_pg_common_name, scf_tmpl_pg_description \- retrieve the metadata about
  10 a specific property group
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lscf\fR [ \fIlibrary\fR\&.\|.\|. ]
  15 #include <libscf.h>
  16
  17 \fBssize_t\fR \fBscf_tmpl_pg_name\fR(\fBconst scf_pg_tmpl_t *\fR\fIpg_tmpl\fR,
  18      \fBchar **\fR\fIout\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBssize_t\fR \fBscf_tmpl_pg_type\fR(\fBconst scf_pg_tmpl_t *\fR\fIpg_tmpl\fR,
  24      \fBchar **\fR\fIout\fR);
  25 .fi
  26
  27 .LP
  28 .nf
  29 \fBssize_t\fR \fBscf_tmpl_pg_target\fR(\fBconst scf_pg_tmpl_t *\fR\fIpg_tmpl\fR,
  30      \fBchar **\fR\fIout\fR);
  31 .fi
  32
  33 .LP
  34 .nf
  35 \fBint\fR \fBscf_tmpl_pg_required\fR(\fBconst scf_pg_tmpl_t *\fR\fIpg_tmpl\fR,
  36      \fBuint8_t *\fR\fIout\fR)
  37 .fi
  38
  39 .LP
  40 .nf
  41 \fBssize_t\fR \fBscf_tmpl_pg_common_name\fR(\fBconst scf_pg_tmpl_t *\fR\fIpg_tmpl\fR,
  42      \fBchar *\fR \fIlocale\fR, \fBchar **\fR\fIout\fR);
  43 .fi
  44
  45 .LP
  46 .nf
  47 \fBssize_t\fR \fBscf_tmpl_pg_description\fR(\fBconst scf_pg_tmpl_t *\fR\fIpg_tmpl\fR,
  48      \fBchar *\fR \fIlocale\fR, \fBchar **\fR\fIout\fR);
  49 .fi
  50
  51 .SH DESCRIPTION
  52 .sp
  53 .LP
  54 These functions retrieve the metadata about a specific property group. They
  55 require that the template for the property group has already been located by
  56 one of the \fBscf_tmpl_pg_create\fR(3SCF) suite of functions.
  57 .sp
  58 .LP
  59 The \fBscf_tmpl_pg_name()\fR function retrieves the name of the property group
  60 template and place it in *\fIout\fR. If the property group name is implicitly
  61 wildcarded (see \fBsmf_template\fR(5)) in the template, this function will
  62 return a string containing \fBSCF_TMPL_WILDCARD\fR ("*") in *\fIout\fR. The
  63 caller is responsible for freeing the *\fIout\fR buffer on success.
  64 .sp
  65 .LP
  66 The \fBscf_tmpl_pg_type()\fR function will retrieve the type of the property
  67 group template and place it in *\fIout\fR. If the property group type is
  68 implicitly wildcarded (see \fBsmf_template\fR(5)) in the template, this
  69 function will return a string containing \fBSCF_TMPL_WILDCARD\fR ("*") in
  70 *\fIout\fR. The caller is responsible for freeing the *\fIout\fR buffer on
  71 success.
  72 .sp
  73 .LP
  74 The \fBscf_tmpl_pg_target()\fR function will retrieve the target of the
  75 property group template and place it in *\fIout\fR. The caller is responsible
  76 for freeing the *\fIout\fR buffer on success.
  77 .sp
  78 .LP
  79 The \fBscf_tmpl_pg_required()\fR function will determine whether the property
  80 group is required and place the result of that check in *\fIout\fR. If required
  81 is unset, \fIout\fR will be the default value of 0. If the property is
  82 explicitly set to required, \fIout\fR will be 1.
  83 .sp
  84 .LP
  85 The \fBscf_tmpl_pg_common_name()\fR function will retrieve the property group's
  86 localized common name as currently templated and place it in *\fIout\fR. A
  87 locale (as described in \fBsetlocale\fR(3C)) may be specified, or if the
  88 supplied locale is NULL, the current locale will be used.  If a common_name in
  89 the specified locale is not found, the function will also look for a
  90 common_name in the C locale. Some templates will not specify the property group
  91 common name.  The caller is responsible for freeing the *\fIout\fR buffer on
  92 success.
  93 .sp
  94 .LP
  95 The \fBscf_tmpl_pg_description()\fR function will retrieve the property group's
  96 localized description as currently templated and place it in *\fIout\fR. A
  97 locale (as described in \fBsetlocale\fR(3C)) may be specified, or if the
  98 supplied locale is NULL, the current locale will be used. If a description in
  99 the specified locale is not found, the function will also look for a
 100 description in the C locale. Some templates will not specify the property group
 101 description.  The caller is responsible for freeing the *\fIout\fR buffer on
 102 success.
 103 .SH RETURN VALUES
 104 .sp
 105 .LP
 106 Upon successful completion, \fBscf_tmpl_pg_name()\fR,
 107 \fBscf_tmpl_pg_common_name()\fR, \fBscf_tmpl_pg_description()\fR,
 108 \fBscf_tmpl_pg_target()\fR, and \fBscf_tmpl_pg_type()\fR return the length of
 109 the string written, not including the terminating null byte. Otherwise, they
 110 return -1.
 111 .sp
 112 .LP
 113 Upon successful completion, \fBscf_tmpl_pg_required()\fR returns 0. Otherwise,
 114 it returns -1.
 115 .SH ERRORS
 116 .sp
 117 .LP
 118 The \fBscf_tmpl_pg_name()\fR, \fBscf_tmpl_pg_common_name()\fR,
 119 \fBscf_tmpl_pg_description()\fR, \fBscf_tmpl_pg_required()\fR,
 120 \fBscf_tmpl_pg_target()\fR, and \fBscf_tmpl_pg_type()\fR functions will fail
 121 if:
 122 .sp
 123 .ne 2
 124 .na
 125 \fB\fBSCF_ERROR_BACKEND_ACCESS\fR\fR
 126 .ad
 127 .sp .6
 128 .RS 4n
 129 The storage mechanism that the repository server (\fBsvc.configd\fR(1M)) chose
 130 for the operation denied access.
 131 .RE
 132
 133 .sp
 134 .ne 2
 135 .na
 136 \fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
 137 .ad
 138 .sp .6
 139 .RS 4n
 140 The connection to the repository was lost.
 141 .RE
 142
 143 .sp
 144 .ne 2
 145 .na
 146 \fB\fBSCF_ERROR_DELETED\fR\fR
 147 .ad
 148 .sp .6
 149 .RS 4n
 150 The template property group has been deleted.
 151 .RE
 152
 153 .sp
 154 .ne 2
 155 .na
 156 \fB\fBSCF_ERROR_HANDLE_DESTROYED\fR\fR
 157 .ad
 158 .sp .6
 159 .RS 4n
 160 The handle passed in has been destroyed.
 161 .RE
 162
 163 .sp
 164 .ne 2
 165 .na
 166 \fB\fBSCF_ERROR_INTERNAL\fR\fR
 167 .ad
 168 .sp .6
 169 .RS 4n
 170 An internal error occurred.
 171 .RE
 172
 173 .sp
 174 .ne 2
 175 .na
 176 \fB\fBSCF_ERROR_NO_MEMORY\fR\fR
 177 .ad
 178 .sp .6
 179 .RS 4n
 180 There is not enough memory to populate the \fBscf_pg_tmpl_t\fR.
 181 .RE
 182
 183 .sp
 184 .ne 2
 185 .na
 186 \fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
 187 .ad
 188 .sp .6
 189 .RS 4n
 190 The server does not have adequate resources to complete the request.
 191 .RE
 192
 193 .sp
 194 .ne 2
 195 .na
 196 \fB\fBSCF_ERROR_NOT_BOUND\fR\fR
 197 .ad
 198 .sp .6
 199 .RS 4n
 200 The handle is not currently bound.
 201 .RE
 202
 203 .sp
 204 .ne 2
 205 .na
 206 \fB\fBSCF_ERROR_PERMISSION_DENIED\fR\fR
 207 .ad
 208 .sp .6
 209 .RS 4n
 210 The template could not be read due to access restrictions.
 211 .RE
 212
 213 .sp
 214 .ne 2
 215 .na
 216 \fB\fBSCF_ERROR_TEMPLATE_INVALID\fR\fR
 217 .ad
 218 .sp .6
 219 .RS 4n
 220 The template data is invalid.
 221 .RE
 222
 223 .sp
 224 .LP
 225 The \fBscf_tmpl_pg_common_name()\fR and \fBscf_tmpl_pg_description()\fR
 226 functions will fail if:
 227 .sp
 228 .ne 2
 229 .na
 230 \fB\fBSCF_ERROR_NOT_FOUND\fR\fR
 231 .ad
 232 .RS 30n
 233 The property does not exist or exists and has no value.
 234 .RE
 235
 236 .sp
 237 .ne 2
 238 .na
 239 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
 240 .ad
 241 .RS 30n
 242 The locale string is too long.
 243 .RE
 244
 245 .SH ATTRIBUTES
 246 .sp
 247 .LP
 248 See \fBattributes\fR(5) for descriptions of the following attributes:
 249 .sp
 250
 251 .sp
 252 .TS
 253 box;
 254 c | c
 255 l | l .
 256 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 257 _
 258 Interface Stability     Committed
 259 _
 260 MT-Level        Safe
 261 .TE
 262
 263 .SH SEE ALSO
 264 .sp
 265 .LP
 266 \fBsvc.configd\fR(1M), \fBscf_tmpl_pg_create\fR(3SCF), \fBsetlocale\fR(3C),
 267 \fBattributes\fR(5), \fBsmf_template\fR(5)