usr/src/man/man3scf/scf_property_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_PROPERTY_CREATE 3SCF "Oct 28, 2008"
   7 .SH NAME
   8 scf_property_create, scf_property_handle, scf_property_destroy,
   9 scf_property_get_name, scf_property_type, scf_property_is_type,
  10 scf_type_to_string, scf_string_to_type, scf_property_get_value,
  11 scf_pg_get_property \- create and manipulate property handles in the Service
  12 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_property_t *\fR\fBscf_property_create\fR(\fBscf_handle_t *\fR\fIhandle\fR);
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fBscf_handle_t *\fR\fBscf_property_handle\fR(\fBscf_property_t *\fR\fIprop\fR);
  25 .fi
  26
  27 .LP
  28 .nf
  29 \fBvoid\fR \fBscf_property_destroy\fR(\fBscf_property_t *\fR\fIprop\fR);
  30 .fi
  31
  32 .LP
  33 .nf
  34 \fBssize_t\fR \fBscf_property_get_name\fR(\fBconst scf_property_t *\fR\fIprop\fR,
  35      \fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIsize\fR);
  36 .fi
  37
  38 .LP
  39 .nf
  40 \fBint\fR \fBscf_property_type\fR(\fBconst scf_property_t *\fR\fIprop\fR,
  41      \fBscf_type_t *\fR\fItype\fR);
  42 .fi
  43
  44 .LP
  45 .nf
  46 \fBint\fR \fBscf_property_is_type\fR(\fBconst scf_property_t *\fR\fIprop\fR,
  47      \fBscf_type_t\fR \fItype\fR);
  48 .fi
  49
  50 .LP
  51 .nf
  52 \fBconst char *\fR\fBscf_type_to_string\fR(\fBscf_type_t\fR \fItype\fR);
  53 .fi
  54
  55 .LP
  56 .nf
  57 \fBscf_type_t\fR \fBscf_string_to_type\fR(\fBconst char *\fR\fItype\fR);
  58 .fi
  59
  60 .LP
  61 .nf
  62 \fBint\fR \fBscf_property_get_value\fR(\fBconst scf_property_t *\fR\fIprop\fR,
  63      \fBscf_value_t *\fR\fIvalue\fR);
  64 .fi
  65
  66 .LP
  67 .nf
  68 \fBint\fR \fBscf_pg_get_property\fR(\fBconst scf_property_t *\fR\fIpg\fR,
  69      \fBconst char *\fR\fIname\fR, \fBscf_property_t *\fR\fIprop\fR);
  70 .fi
  71
  72 .SH DESCRIPTION
  73 .sp
  74 .LP
  75 Properties are named sets of values of one type. They are grouped into property
  76 groups (see \fBscf_pg_create\fR(3SCF)) that are updated atomically using
  77 transactions (see \fBscf_transaction_create\fR(3SCF)).
  78 .sp
  79 .LP
  80 An \fBscf_property_t\fR is an opaque handle that can be set to a single
  81 property at any given time. When set, it inherits the point-in-time from the
  82 source \fBscf_propertygroup_t\fR and does not change until reset.
  83 .sp
  84 .LP
  85 The \fBscf_property_create()\fR function allocates and initializes a new
  86 \fBscf_property_t\fR bound to \fIhandle\fR. The \fBscf_property_destroy()\fR
  87 function destroys and frees \fIprop\fR.
  88 .sp
  89 .LP
  90 The \fBscf_property_handle()\fR function returns the handle to which \fIprop\fR
  91 is bound.
  92 .sp
  93 .LP
  94 The \fBscf_property_type()\fR function retrieves the type of the property to
  95 which \fIprop\fR is set.
  96 .sp
  97 .LP
  98 The \fBscf_property_is_type()\fR function determines if the property is
  99 compatible with type. See \fBscf_value_create\fR(3SCF).
 100 .sp
 101 .LP
 102 The \fBscf_type_to_string()\fR function returns the string name of the type
 103 supplied. If the type is invalid or unknown, it returns "unknown".
 104 .sp
 105 .LP
 106 The \fBscf_string_to_type()\fR function returns the \fBscf_type_t\fR definition
 107 of the string supplied. If the string does not translate to an existing type,
 108 it returns \fBSCF_TYPE_INVALID\fR.
 109 .sp
 110 .LP
 111 The \fBscf_property_get_value()\fR function retrieves the single value that the
 112 property to which \fIprop\fR is set contains. If the property has more than one
 113 value, the \fIvalue\fR argument is set to one of the values. To retrieve all
 114 values associated with a property, see \fBscf_iter_property_values\fR(3SCF).
 115 .sp
 116 .LP
 117 The \fBscf_pg_get_property()\fR function sets \fIprop\fR to the property
 118 specified by \fIname\fR in the property group specified by \fIpg\fR.
 119 .SH RETURN VALUES
 120 .sp
 121 .LP
 122 Upon successful completion, \fBscf_property_create()\fR returns a new
 123 \fBscf_property_t\fR. Otherwise, it returns \fINULL\fR.
 124 .sp
 125 .LP
 126 Upon successful completion,  \fBscf_property_get_name()\fR function returns the
 127 length of the string written, not including the terminating null byte.
 128 Otherwise, it returns -1.
 129 .sp
 130 .LP
 131 Upon successful completion, \fBscf_pg_get_property()\fR,
 132 \fBscf_property_type()\fR, \fBscf_property_is_type()\fR, and
 133 \fBscf_pg_get_value()\fR functions return 0. Otherwise, they return -1.
 134 .sp
 135 .LP
 136 Upon successful completion, \fBscf_type_to_string()\fR returns a string of the
 137 type supplied.
 138 .sp
 139 .LP
 140 Upon successful completion, \fBscf_string_to_type()\fR returns the
 141 \fBscf_type_t\fR definition of the string supplied
 142 .SH ERRORS
 143 .sp
 144 .LP
 145 The \fBscf_property_create()\fR function will fail if:
 146 .sp
 147 .ne 2
 148 .na
 149 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
 150 .ad
 151 .RS 30n
 152 The value of the \fIhandle\fR argument is \fINULL\fR.
 153 .RE
 154
 155 .sp
 156 .ne 2
 157 .na
 158 \fB\fBSCF_ERROR_NO_MEMORY\fR\fR
 159 .ad
 160 .RS 30n
 161 There is not enough memory to allocate an \fBscf_property_t\fR.
 162 .RE
 163
 164 .sp
 165 .ne 2
 166 .na
 167 \fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
 168 .ad
 169 .RS 30n
 170 The server does not have adequate resources for a new property handle.
 171 .RE
 172
 173 .sp
 174 .LP
 175 The \fBscf_property_handle()\fR function will fail if:
 176 .sp
 177 .ne 2
 178 .na
 179 \fB\fBSCF_ERROR_HANDLE_DESTROYED\fR\fR
 180 .ad
 181 .RS 30n
 182 The handle associated with \fIprop\fR has been destroyed.
 183 .RE
 184
 185 .sp
 186 .LP
 187 The \fBscf_property_get_name()\fR, \fBscf_property_type()\fR,
 188 \fBscf_property_is_type()\fR, and \fBscf_property_get_value()\fR functions will
 189 fail if:
 190 .sp
 191 .ne 2
 192 .na
 193 \fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
 194 .ad
 195 .sp .6
 196 .RS 4n
 197 The connection to the repository was lost.
 198 .RE
 199
 200 .sp
 201 .ne 2
 202 .na
 203 \fB\fBSCF_ERROR_DELETED\fR\fR
 204 .ad
 205 .sp .6
 206 .RS 4n
 207 The property's parent property group or an ancestor has been deleted.
 208 .RE
 209
 210 .sp
 211 .ne 2
 212 .na
 213 \fB\fBSCF_ERROR_NOT_BOUND\fR\fR
 214 .ad
 215 .sp .6
 216 .RS 4n
 217 The handle was never bound or has been unbound.
 218 .RE
 219
 220 .sp
 221 .ne 2
 222 .na
 223 \fB\fBSCF_ERROR_NOT_SET\fR\fR
 224 .ad
 225 .sp .6
 226 .RS 4n
 227 The property is not set.
 228 .RE
 229
 230 .sp
 231 .LP
 232 The \fBscf_property_is_type()\fR function will fail if:
 233 .sp
 234 .ne 2
 235 .na
 236 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
 237 .ad
 238 .RS 30n
 239 The \fItype\fR argument is not a valid type.
 240 .RE
 241
 242 .sp
 243 .ne 2
 244 .na
 245 \fB\fBSCF_ERROR_TYPE_MISMATCH\fR\fR
 246 .ad
 247 .RS 30n
 248 The \fIprop\fR argument is not of a type compatible with \fItype\fR.
 249 .RE
 250
 251 .sp
 252 .LP
 253 The \fBscf_pg_get_property()\fR function will fail if:
 254 .sp
 255 .ne 2
 256 .na
 257 \fB\fBSCF_ERROR_BACKEND_ACCESS\fR\fR
 258 .ad
 259 .sp .6
 260 .RS 4n
 261 The  storage  mechanism  that  the   repository server (\fBsvc.configd\fR(1M))
 262 chose for the operation denied access.
 263 .RE
 264
 265 .sp
 266 .ne 2
 267 .na
 268 \fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
 269 .ad
 270 .sp .6
 271 .RS 4n
 272 The connection to the repository was lost.
 273 .RE
 274
 275 .sp
 276 .ne 2
 277 .na
 278 \fB\fBSCF_ERROR_DELETED\fR\fR
 279 .ad
 280 .sp .6
 281 .RS 4n
 282 The property group or an ancestor has been deleted.
 283 .RE
 284
 285 .sp
 286 .ne 2
 287 .na
 288 \fB\fBSCF_ERROR_HANDLE_MISMATCH\fR\fR
 289 .ad
 290 .sp .6
 291 .RS 4n
 292 The property group and property are not derived from the same handle.
 293 .RE
 294
 295 .sp
 296 .ne 2
 297 .na
 298 \fB\fBSCF_ERROR_INTERNAL\fR\fR
 299 .ad
 300 .sp .6
 301 .RS 4n
 302 An internal error occurred.
 303 .RE
 304
 305 .sp
 306 .ne 2
 307 .na
 308 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
 309 .ad
 310 .sp .6
 311 .RS 4n
 312 The value of the \fIname\fR argument is not a valid property name.
 313 .RE
 314
 315 .sp
 316 .ne 2
 317 .na
 318 \fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
 319 .ad
 320 .sp .6
 321 .RS 4n
 322 The server does not have the resources to complete the request.
 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 was never bound or has been unbound.
 333 .RE
 334
 335 .sp
 336 .ne 2
 337 .na
 338 \fB\fBSCF_ERROR_NOT_FOUND\fR\fR
 339 .ad
 340 .sp .6
 341 .RS 4n
 342 The property specified by \fIname\fR was not found.
 343 .RE
 344
 345 .sp
 346 .ne 2
 347 .na
 348 \fB\fBSCF_ERROR_NOT_SET\fR\fR
 349 .ad
 350 .sp .6
 351 .RS 4n
 352 The property group specified by \fIpg\fR is not set.
 353 .RE
 354
 355 .sp
 356 .LP
 357 The \fBscf_property_get_value()\fR function will fail if:
 358 .sp
 359 .ne 2
 360 .na
 361 \fB\fBSCF_ERROR_CONSTRAINT_VIOLATED\fR\fR
 362 .ad
 363 .sp .6
 364 .RS 4n
 365 The property has more than one value associated with it. The \fIvalue\fR
 366 argument will be set to one of the values.
 367 .RE
 368
 369 .sp
 370 .ne 2
 371 .na
 372 \fB\fBSCF_ERROR_HANDLE_MISMATCH\fR\fR
 373 .ad
 374 .sp .6
 375 .RS 4n
 376 The property and value are derived from different handles.
 377 .RE
 378
 379 .sp
 380 .ne 2
 381 .na
 382 \fB\fBSCF_ERROR_NOT_FOUND\fR\fR
 383 .ad
 384 .sp .6
 385 .RS 4n
 386 The property has no values associated with it. The \fIvalue\fR argument will be
 387 reset.
 388 .RE
 389
 390 .sp
 391 .ne 2
 392 .na
 393 \fB\fBSCF_ERROR_PERMISSION_DENIED\fR\fR
 394 .ad
 395 .sp .6
 396 .RS 4n
 397 The value could not be read due to access restrictions.
 398 .RE
 399
 400 .sp
 401 .LP
 402 The \fBscf_error\fR(3SCF) function can be used to retrieve the error value.
 403 .SH ATTRIBUTES
 404 .sp
 405 .LP
 406 See \fBattributes\fR(5) for descriptions of the following attributes:
 407 .sp
 408
 409 .sp
 410 .TS
 411 box;
 412 c | c
 413 l | l .
 414 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 415 _
 416 Interface Stability     Committed
 417 _
 418 MT-Level        Safe
 419 .TE
 420
 421 .SH SEE ALSO
 422 .sp
 423 .LP
 424 \fBlibscf\fR(3LIB), \fBscf_error\fR(3SCF), \fBscf_handle_decode_fmri\fR(3SCF),
 425 \fBscf_iter_property_values\fR(3SCF), \fBscf_pg_create\fR(3SCF),
 426 \fBscf_property_to_fmri\fR(3SCF), \fBscf_transaction_create\fR(3SCF),
 427 \fBscf_value_create\fR(3SCF), \fBattributes\fR(5)