usr/src/man/man3scf/scf_simple_prop_get.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_SIMPLE_PROP_GET 3SCF "Nov 7, 2007"
   7 .SH NAME
   8 scf_simple_prop_get, scf_simple_prop_free, scf_simple_app_props_get,
   9 scf_simple_app_props_free, scf_simple_app_props_next,
  10 scf_simple_app_props_search, scf_simple_prop_numvalues, scf_simple_prop_type,
  11 scf_simple_prop_name, scf_simple_prop_pgname, scf_simple_prop_next_boolean,
  12 scf_simple_prop_next_count, scf_simple_prop_next_integer,
  13 scf_simple_prop_next_time, scf_simple_prop_next_astring,
  14 scf_simple_prop_next_ustring, scf_simple_prop_next_opaque,
  15 scf_simple_prop_next_reset \- simplified property read interface to Service
  16 Configuration Facility
  17 .SH SYNOPSIS
  18 .LP
  19 .nf
  20 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lscf\fR [ \fIlibrary\fR\&.\|.\|. ]
  21 #include <libscf.h>
  22
  23 \fBscf_simple_prop_t *\fR\fBscf_simple_prop_get\fR(\fBscf_handle_t *\fR\fIhandle\fR,
  24      \fBconst char *\fR\fIinstance\fR, \fBconst char *\fR\fIpgname\fR, \fBconst char *\fR\fIpropname\fR);
  25 .fi
  26
  27 .LP
  28 .nf
  29 \fBvoid\fR \fBscf_simple_prop_free\fR(\fBscf_simple_prop_t *\fR\fIprop\fR);
  30 .fi
  31
  32 .LP
  33 .nf
  34 \fBscf_simple_app_props_t *\fR\fBscf_simple_app_props_get\fR(\fBscf_handle_t *\fR\fIhandle\fR,
  35      \fBconst char *\fR\fIinstance\fR);
  36 .fi
  37
  38 .LP
  39 .nf
  40 \fBvoid\fR \fBscf_simple_app_props_free\fR(\fBscf_simple_app_props_t *\fR\fIpropblock\fR);
  41 .fi
  42
  43 .LP
  44 .nf
  45 \fBconst scf_simple_prop_t *\fR\fBscf_simple_app_props_next\fR
  46      (\fBconst scf_simple_app_props_t *\fR\fIpropblock\fR,\fBscf_simple_prop_t *\fR\fIlast\fR);
  47 .fi
  48
  49 .LP
  50 .nf
  51 \fBconst scf_simple_prop_t *\fR\fBscf_simple_app_props_search\fR
  52      (\fBconst scf_simple_app_props_t *\fR\fIpropblock\fR, \fBconst char *\fR\fIpgname\fR,
  53      \fBconst char *\fR\fIpropname\fR);
  54 .fi
  55
  56 .LP
  57 .nf
  58 \fBssize_t\fR \fBscf_simple_prop_numvalues\fR(\fBconst scf_simple_prop_t *\fR\fIprop\fR);
  59 .fi
  60
  61 .LP
  62 .nf
  63 \fBscf_type_t\fR \fBscf_simple_prop_type\fR(\fBconst scf_simple_prop_t *\fR\fIprop\fR);
  64 .fi
  65
  66 .LP
  67 .nf
  68 \fBconst char *\fR\fBscf_simple_prop_name\fR(\fBconst scf_simple_prop_t *\fR\fIprop\fR);
  69 .fi
  70
  71 .LP
  72 .nf
  73 \fBconst char *\fR\fBscf_simple_prop_pgname\fR(\fBconst scf_simple_prop_t *\fR\fIprop\fR);
  74 .fi
  75
  76 .LP
  77 .nf
  78 \fBuint8_t *\fR\fBscf_simple_prop_next_boolean\fR(\fBconst scf_simple_prop_t *\fR\fIprop\fR);
  79 .fi
  80
  81 .LP
  82 .nf
  83 \fBuint64_t *\fR\fBscf_simple_prop_next_count\fR(\fBconst scf_simple_prop_t *\fR\fIprop\fR);
  84 .fi
  85
  86 .LP
  87 .nf
  88 \fBint64_t *\fR\fBscf_simple_prop_next_integer\fR(\fBconst scf_simple_prop_t *\fR\fIprop\fR);
  89 .fi
  90
  91 .LP
  92 .nf
  93 \fBint64_t *\fR\fBscf_simple_prop_next_time\fR(\fBconst scf_simple_prop_t *\fR\fIprop\fR,
  94      \fBint32_t *\fR\fInsec\fR);
  95 .fi
  96
  97 .LP
  98 .nf
  99 \fBchar *\fR\fBscf_simple_prop_next_astring\fR(\fBconst scf_simple_prop_t *\fR\fIprop\fR);
 100 .fi
 101
 102 .LP
 103 .nf
 104 \fBchar *\fR\fBscf_simple_prop_next_ustring\fR(\fBconst scf_simple_prop_t *\fR\fIprop\fR);
 105 .fi
 106
 107 .LP
 108 .nf
 109 \fBvoid *\fR\fBscf_simple_prop_next_opaque\fR(\fBconst scf_simple_prop_t *\fR\fIprop\fR,
 110      \fBsize_t *\fR\fIlength\fR);
 111 .fi
 112
 113 .LP
 114 .nf
 115 \fBvoid *\fR\fBscf_simple_prop_next_reset\fR(\fBconst scf_simple_prop_t *\fR\fIprop\fR);
 116 .fi
 117
 118 .SH DESCRIPTION
 119 .sp
 120 .LP
 121 The simplified read interface to the Service Configuration Facility deals with
 122 properties and blocks of properties.
 123 .sp
 124 .LP
 125 The \fBscf_simple_prop_get()\fR function pulls a single property. The
 126 \fBscf_simple_prop_*()\fR functions operate on the resulting
 127 \fBscf_simple_prop_t\fR.
 128 .sp
 129 .LP
 130 The application might need to get many properties or iterate through all
 131 properties. The \fBscf_simple_app_props_get()\fR function gets all properties
 132 from the service instance that are in property groups of type 'application'.
 133 Individual properties are pulled from the block using the
 134 \fBscf_simple_app_props_next()\fR function for iteration or
 135 \fBscf_simple_app_props_search()\fR to search. The pointer to the
 136 \fBscf_simple_prop_t\fR returned from iteration or searching can be acted upon
 137 using the \fBscf_simple_prop_*()\fR functions. Each \fBscf_*_get()\fR function
 138 has an accompanying \fBscf_*_free\fR function. The application does not free
 139 the pointer to the \fBscf_simple_prop_t\fR returned from the
 140 \fBscf_simple_app_props_next()\fR and \fBscf_simple_app_props_search()\fR
 141 calls. A free call is only used with a corresponding get call.
 142 .sp
 143 .LP
 144 The \fBscf_simple_prop_*()\fR functions return references to the read-only
 145 in-memory copy of the property information. Any changes to this information
 146 results in unstable behavior and inaccurate results. The simplified read
 147 interface provides read access only, with no provisions to modify data in the
 148 service configuration facility repository.
 149 .sp
 150 .LP
 151 The \fBscf_simple_prop_get()\fR function takes as arguments a bound handle, a
 152 service instance FMRI, and the property group and property name of a property.
 153 If \fIhandle\fR is \fINULL\fR, the library uses a temporary handle created for
 154 the purpose. If \fIinstance\fR is \fINULL\fR the library automatically finds
 155 the FMRI of the calling process. If \fIpgname\fR is \fINULL\fR, the library
 156 uses the default application property group. The caller is responsible for
 157 freeing the returned property with \fBscf_simple_prop_free()\fR.
 158 .sp
 159 .LP
 160 The \fBscf_simple_prop_free()\fR function frees the \fBscf_simple_prop_t\fR
 161 allocated by \fBscf_simple_prop_get()\fR.
 162 .sp
 163 .LP
 164 The \fBscf_simple_app_props_get()\fR function takes a bound handle and a
 165 service instance FMRI and pulls all the application properties into an
 166 \fBscf_simple_app_props_t\fR. If \fIhandle\fR is \fINULL\fR, the library uses a
 167 temporary handle created for the purpose. If \fIinstance\fR is \fINULL\fR, the
 168 library looks up the instance FMRI of the process calling the function. The
 169 caller is responsible for freeing the \fBscf_simple_app_props_t\fR with
 170 \fBscf_simple_app_props_free()\fR.
 171 .sp
 172 .LP
 173 The \fBscf_simple_app_props_free()\fR function frees the
 174 \fBscf_simple_app_props_t\fR allocated by \fBscf_simple_app_props_get()\fR.
 175 .sp
 176 .LP
 177 The \fBscf_simple_app_props_next()\fR function iterates over each property in
 178 an \fBscf_simple_app_props_t\fR. It takes an \fBscf_simple_app_props_t\fR
 179 pointer and the last property returned from the previous call and returns the
 180 next property in the \fBscf_simple_app_props_t\fR. Because the property is a
 181 reference into the \fBscf_simple_app_props_t\fR, its lifetime extends only
 182 until that structure is freed.
 183 .sp
 184 .LP
 185 The\fBscf_simple_app_props_search()\fR function queries for an exact match on a
 186 property in a property group. It takes an apps prop object, a property group
 187 name, and a property name, and returns a property pointer. Because the property
 188 is a reference into the \fBscf_simple_app_props_t\fR, its lifetime extends only
 189 until that structure is freed. If the property group name, \fIpgname\fR, is
 190 \fINULL\fR, "application" is used.
 191 .sp
 192 .LP
 193 The \fBscf_simple_prop_numvalues()\fR function takes a pointer to a property
 194 and returns the number of values in that property.
 195 .sp
 196 .LP
 197 The \fBscf_simple_prop_type()\fR function takes a pointer to a property and
 198 returns the type of the property in an \fBscf_type_t\fR.
 199 .sp
 200 .LP
 201 The \fBscf_simple_prop_name()\fR function takes a pointer to a property and
 202 returns a pointer to the property name string.
 203 .sp
 204 .LP
 205 The \fBscf_simple_prop_pgname()\fR function takes a pointer to a property and
 206 returns a pointer to the property group name string. The
 207 \fBscf_simple_prop_next_boolean()\fR, \fBscf_simple_prop_next_count()\fR,
 208 \fBscf_simple_prop_next_integer()\fR, \fBscf_simple_prop_next_astring()\fR, and
 209 \fBscf_simple_prop_next_ustring()\fR functions take a pointer to a property and
 210 return the first value in the property.  Subsequent calls iterate over all the
 211 values in the property. The property's internal iteration can be reset with
 212 \fBscf_simple_prop_next_reset()\fR.
 213 .sp
 214 .LP
 215 The \fBscf_simple_prop_next_time()\fR function takes a pointer to a property
 216 and the address of an allocated \fBint32_t\fR to hold the nanoseconds field,
 217 and returns the first value in the property. Subsequent calls iterate over the
 218 property values.
 219 .sp
 220 .LP
 221 The \fBscf_simple_prop_next_opaque()\fR function takes a pointer to a property
 222 and the address of an allocated integer to hold the size of the opaque buffer.
 223 It returns the first value in the property. Subsequent calls iterate over the
 224 property values, as do the \fBscf_simple_prop_next_*()\fR functions. The
 225 \fBscf_simple_prop_next_opaque()\fR function writes the size of the opaque
 226 buffer into the allocated integer.
 227 .sp
 228 .LP
 229 The \fBscf_simple_prop_next_reset()\fR function resets iteration on a property,
 230 so that a call to one of the \fBscf_simple_prop_next_*()\fR functions returns
 231 the first value in the property.
 232 .SH RETURN VALUES
 233 .sp
 234 .LP
 235 Upon successful completion, \fBscf_simple_prop_get()\fR returns a pointer to an
 236 allocated \fBscf_simple_prop_t\fR. Otherwise, it returns \fINULL\fR.
 237 .sp
 238 .LP
 239 Upon successful completion, \fBscf_simple_app_props_get()\fR returns a pointer
 240 to an allocated \fBscf_simple_app_props_t\fR. Otherwise, it returns \fINULL\fR.
 241 .sp
 242 .LP
 243 Upon successful completion, \fBscf_simple_app_props_next()\fR returns a pointer
 244 to an \fBscf_simple_prop_t\fR. Otherwise, it returns \fINULL\fR.
 245 .sp
 246 .LP
 247 Upon successful completion, \fBscf_simple_app_props_search()\fR returns a
 248 pointer to an \fBscf_simple_prop_t\fR. Otherwise, it returns \fINULL\fR.
 249 .sp
 250 .LP
 251 Upon successful completion, \fBscf_simple_prop_numvalues()\fR returns the
 252 number of values in a property. Otherwise, it returns -1.
 253 .sp
 254 .LP
 255 Upon successful completion, \fBscf_simple_prop_type()\fR returns an
 256 \fBscf_type_t\fR. Otherwise, it returns -1.
 257 .sp
 258 .LP
 259 Upon successful completion, \fBscf_simple_prop_name()\fR and
 260 \fBscf_simple_prop_pgname()\fR return character pointers. Otherwise, they
 261 return \fINULL\fR.
 262 .sp
 263 .LP
 264 Upon successful completion, \fBscf_simple_prop_next_boolean()\fR,
 265 \fBscf_simple_prop_next_count()\fR, \fBscf_simple_prop_next_integer()\fR,
 266 \fBscf_simple_prop_next_time()\fR, \fBscf_simple_prop_next_astring()\fR,
 267 \fBscf_simple_prop_next_ustring()\fR, and \fBscf_simple_prop_next_opaque()\fR
 268 return a pointer to the next value in the property. After all values have been
 269 returned, NULL is returned and \fBSCF_ERROR_NONE\fR is set. On failure,
 270 \fINULL\fR is returned and the appropriate error value is set.
 271 .SH ERRORS
 272 .sp
 273 .LP
 274 The \fBscf_simple_prop_get()\fR and \fBscf_simple_app_props_get()\fR functions
 275 will fail if:
 276 .sp
 277 .ne 2
 278 .na
 279 \fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
 280 .ad
 281 .sp .6
 282 .RS 4n
 283 The connection to the datastore is broken.
 284 .RE
 285
 286 .sp
 287 .ne 2
 288 .na
 289 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
 290 .ad
 291 .sp .6
 292 .RS 4n
 293 The instance FMRI is invalid or property name is \fINULL\fR.
 294 .RE
 295
 296 .sp
 297 .ne 2
 298 .na
 299 \fB\fBSCF_ERROR_NO_MEMORY\fR\fR
 300 .ad
 301 .sp .6
 302 .RS 4n
 303 The memory allocation failed.
 304 .RE
 305
 306 .sp
 307 .ne 2
 308 .na
 309 \fB\fBSCF_ERROR_NOT_BOUND\fR\fR
 310 .ad
 311 .sp .6
 312 .RS 4n
 313 The connection handle is not bound.
 314 .RE
 315
 316 .sp
 317 .ne 2
 318 .na
 319 \fB\fBSCF_ERROR_NOT_FOUND\fR\fR
 320 .ad
 321 .sp .6
 322 .RS 4n
 323 The specified instance or property does not exist.
 324 .RE
 325
 326 .sp
 327 .ne 2
 328 .na
 329 \fB\fBSCF_ERROR_PERMISSION_DENIED\fR\fR
 330 .ad
 331 .sp .6
 332 .RS 4n
 333 The caller is not authorized to read the property's value(s).
 334 .RE
 335
 336 .sp
 337 .LP
 338 The \fBscf_simple_app_props_next()\fR function will fail if:
 339 .sp
 340 .ne 2
 341 .na
 342 \fB\fBSCF_ERROR_NOT_SET\fR\fR
 343 .ad
 344 .RS 21n
 345 The value of the \fIpropblock\fR argument is \fINULL\fR.
 346 .RE
 347
 348 .sp
 349 .LP
 350 The \fBscf_simple_app_props_search()\fR function will fail if:
 351 .sp
 352 .ne 2
 353 .na
 354 \fB\fBSCF_ERROR_NOT_FOUND\fR\fR
 355 .ad
 356 .RS 23n
 357 The property was not found.
 358 .RE
 359
 360 .sp
 361 .ne 2
 362 .na
 363 \fB\fBSCF_ERROR_NOT_SET\fR\fR
 364 .ad
 365 .RS 23n
 366 The value of the \fIpropblock\fR or \fIpropname\fR argument is \fINULL\fR.
 367 .RE
 368
 369 .sp
 370 .LP
 371 The \fBscf_simple_prop_numvalues()\fR, \fBscf_simple_prop_type()\fR,
 372 \fBscf_simple_prop_name()\fR, and \fBscf_simple_prop_pgname()\fR functions will
 373 fail if:
 374 .sp
 375 .ne 2
 376 .na
 377 \fB\fBSCF_ERROR_NOT_SET\fR\fR
 378 .ad
 379 .RS 21n
 380 The property is \fINULL\fR.
 381 .RE
 382
 383 .sp
 384 .LP
 385 The \fBscf_simple_prop_next_boolean()\fR, \fBscf_simple_prop_next_count()\fR,
 386 \fBscf_simple_prop_next_integer()\fR, \fBscf_simple_prop_next_time()\fR,
 387 \fBscf_simple_prop_next_astring()\fR, \fBscf_simple_prop_next_ustring()\fR, and
 388 \fBscf_simple_prop_next_opaque()\fR functions will fail if:
 389 .sp
 390 .ne 2
 391 .na
 392 \fB\fBSCF_ERROR_NOT_SET\fR\fR
 393 .ad
 394 .RS 27n
 395 The property is \fINULL\fR.
 396 .RE
 397
 398 .sp
 399 .ne 2
 400 .na
 401 \fB\fBSCF_ERROR_TYPE_MISMATCH\fR\fR
 402 .ad
 403 .RS 27n
 404 The requested type does not match the property type.
 405 .RE
 406
 407 .SH EXAMPLES
 408 .LP
 409 \fBExample 1 \fRSimple Property Get
 410 .sp
 411 .in +2
 412 .nf
 413 /*
 414  * In this example, we pull the property named "size" from the
 415  * default property group.  We make sure that the property
 416  * isn't empty, and then copy it into the sizeval variable.
 417  */
 418
 419 scf_simple_prop_t       *prop;
 420 ssize_t                 numvals;
 421 int64_t                 *sizeval;
 422
 423 prop = scf_simple_prop_get(
 424         "svc://localhost/category/service/instance",
 425         NULL, "size");
 426
 427 numvals = scf_simple_prop_numvalues(prop);
 428
 429 if(numvals > 0){
 430         sizeval = scf_simple_prop_next_integer(prop);
 431 }
 432
 433 scf_simple_prop_free(prop);
 434 .fi
 435 .in -2
 436
 437 .LP
 438 \fBExample 2 \fRProperty Iteration
 439 .sp
 440 .in +2
 441 .nf
 442 scf_simple_prop_t              *prop;
 443 scf_simple_app_props_t         *appprops;
 444
 445 appprops = scf_simple_app_props_get(
 446         "svc://localhost/category/service/instance");
 447
 448 prop = scf_simple_app_props_next(appprops, NULL);
 449
 450 while(prop != NULL)
 451 {
 452         /*
 453          * This iteration will go through every property in the
 454          * instance's application block.  The user can use
 455          * the set of property functions to pull the values out
 456          * of prop, as seen in other examples.
 457          */
 458
 459         (...code acting on each property...)
 460
 461
 462 prop = scf_simple_app_props_next(appprops, prop);
 463
 464 }
 465
 466 scf_simple_app_props_free(appprops);
 467 .fi
 468 .in -2
 469
 470 .LP
 471 \fBExample 3 \fRProperty Searching
 472 .sp
 473 .in +2
 474 .nf
 475 /*
 476  * In this example, we pull the property block from the instance,
 477  * and then query it.  Generally speaking, the simple get would
 478  * be used for an example like this, but for the purposes of
 479  * illustration, the non-simple approach is used.  The property
 480  * is a list of integers that are pulled into an array.
 481  * Note how val is passed back into each call, as described above.
 482  */
 483
 484 scf_simple_app_props_t         *appprops;
 485 scf_simple_prop_t              *prop;
 486 int                     i;
 487 int64_t                 *intlist;
 488 ssize_t                 numvals;
 489
 490 appprops = scf_simple_app_props_get(
 491               "svc://localhost/category/service/instance");
 492
 493 prop = scf_simple_app_props_search(appprops, "appname", "numlist");
 494
 495 if(prop != NULL){
 496
 497         numvals = scf_simple_prop_numvalues(prop);
 498
 499         if(numvals > 0){
 500
 501         intlist = malloc(numvals * sizeof(int64_t));
 502
 503         val = scf_simple_prop_next_integer(prop);
 504
 505                 for(i=0, i < numvals, i++){
 506                         intlist[i] = *val;
 507                         val = scf_simple_prop_next_integer(prop);
 508                 }
 509         }
 510 }
 511
 512 scf_simple_app_props_free(appprops);
 513 .fi
 514 .in -2
 515
 516 .SH ATTRIBUTES
 517 .sp
 518 .LP
 519 See \fBattributes\fR(5) for descriptions of the following attributes:
 520 .sp
 521
 522 .sp
 523 .TS
 524 box;
 525 c | c
 526 l | l .
 527 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 528 _
 529 Interface Stability     Committed
 530 _
 531 MT-Level        Safe
 532 .TE
 533
 534 .SH SEE ALSO
 535 .sp
 536 .LP
 537 \fBlibscf\fR(3LIB), \fBscf_error\fR(3SCF), \fBattributes\fR(5)