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

   1 '\" te
   2 .\" Copyright (c) 2009, 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. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
   4 .\"  See the License for the specific language governing permissions and limitations under the License. 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
   5 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH SCF_VALUE_CREATE 3SCF "May 28, 2009"
   7 .SH NAME
   8 scf_value_create, scf_value_handle, scf_value_reset, scf_value_destroy,
   9 scf_value_type, scf_value_base_type, scf_value_is_type, scf_type_base_type,
  10 scf_value_get_boolean, scf_value_get_count, scf_value_get_integer,
  11 scf_value_get_time, scf_value_get_astring, scf_value_get_ustring,
  12 scf_value_get_opaque, scf_value_get_as_string, scf_value_get_as_string_typed,
  13 scf_value_set_boolean, scf_value_set_count, scf_value_set_integer,
  14 scf_value_set_time, scf_value_set_from_string, scf_value_set_astring,
  15 scf_value_set_ustring, scf_value_set_opaque \- manipulate values in the 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_value_t *\fR\fBscf_value_create\fR(\fBscf_handle_t *\fR\fIh\fR);
  24 .fi
  25
  26 .LP
  27 .nf
  28 \fBscf_handle_t *\fR\fBscf_value_handle\fR(\fBscf_value_t *\fR\fIv\fR);
  29 .fi
  30
  31 .LP
  32 .nf
  33 \fBvoid\fR \fBscf_value_reset\fR(\fBscf_value_t *\fR\fIv\fR);
  34 .fi
  35
  36 .LP
  37 .nf
  38 \fBvoid\fR \fBscf_value_destroy\fR(\fBscf_value_t *\fR\fIv\fR);
  39 .fi
  40
  41 .LP
  42 .nf
  43 \fBint\fR \fBscf_value_type\fR(\fBscf_value_t *\fR\fIv\fR);
  44 .fi
  45
  46 .LP
  47 .nf
  48 \fBint\fR \fBscf_value_base_type\fR(\fBscf_value_t *\fR\fIv\fR);
  49 .fi
  50
  51 .LP
  52 .nf
  53 \fBint\fR \fBscf_value_is_type\fR(\fBscf_value_t *\fR\fIv\fR, \fBscf_type_t\fR \fItype\fR);
  54 .fi
  55
  56 .LP
  57 .nf
  58 \fBint\fR \fBscf_type_base_type\fR(\fBscf_type_t\fR \fItype\fR, \fBscf_type_t *\fR\fIout\fR);
  59 .fi
  60
  61 .LP
  62 .nf
  63 \fBint\fR \fBscf_value_get_boolean\fR(\fBscf_value_t *\fR\fIv\fR, \fBuint8_t *\fR\fIout\fR);
  64 .fi
  65
  66 .LP
  67 .nf
  68 \fBint\fR \fBscf_value_get_count\fR(\fBscf_value_t *\fR\fIv\fR, \fBuint64_t *\fR\fIout\fR);
  69 .fi
  70
  71 .LP
  72 .nf
  73 \fBint\fR \fBscf_value_get_integer\fR(\fBscf_value_t *\fR\fIv\fR, \fBint64_t *\fR\fIout\fR);
  74 .fi
  75
  76 .LP
  77 .nf
  78 \fBint\fR \fBscf_value_get_time\fR(\fBscf_value_t *\fR\fIv\fR, \fBint64_t *\fR\fIseconds\fR,
  79      \fBint32_t *\fR\fIns\fR);
  80 .fi
  81
  82 .LP
  83 .nf
  84 \fBssize_t\fR \fBscf_value_get_astring\fR(\fBscf_value_t *\fR\fIv\fR, \fBchar *\fR\fIbuf\fR,
  85      \fBsize_t\fR \fIsize\fR);
  86 .fi
  87
  88 .LP
  89 .nf
  90 \fBssize_t\fR \fBscf_value_get_ustring\fR(\fBscf_value_t *\fR\fIv\fR, \fBchar *\fR\fIbuf\fR,
  91      \fBsize_t\fR \fIsize\fR);
  92 .fi
  93
  94 .LP
  95 .nf
  96 \fBssize_t\fR \fBscf_value_get_opaque\fR(\fBscf_value_t *\fR\fIv\fR, \fBchar *\fR\fIout\fR,
  97      \fBsize_t\fR \fIlen\fR);
  98 .fi
  99
 100 .LP
 101 .nf
 102 \fBssize_t\fR \fBscf_value_get_as_string\fR(\fBscf_value_t *\fR\fIv\fR, \fBchar *\fR\fIbuf\fR,
 103      \fBsize_t\fR \fIsize\fR);
 104 .fi
 105
 106 .LP
 107 .nf
 108 \fBssize_t\fR \fBscf_value_get_as_string_typed\fR(\fBscf_value_t *\fR\fIv\fR,
 109      \fBscf_type_t\fR \fItype\fR, \fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIsize\fR);
 110 .fi
 111
 112 .LP
 113 .nf
 114 \fBvoid\fR \fBscf_value_set_boolean\fR(\fBscf_value_t *\fR\fIv\fR, \fBuint8_t\fR \fIin\fR);
 115 .fi
 116
 117 .LP
 118 .nf
 119 \fBvoid\fR \fBscf_value_set_count\fR(\fBscf_value_t *\fR\fIv\fR, \fBuint64_t\fR \fIin\fR);
 120 .fi
 121
 122 .LP
 123 .nf
 124 \fBvoid\fR \fBscf_value_set_integer\fR(\fBscf_value_t *\fR\fIv\fR, \fBint64_t\fR \fIin\fR);
 125 .fi
 126
 127 .LP
 128 .nf
 129 \fBint\fR \fBscf_value_set_time\fR(\fBscf_value_t *\fR\fIv\fR, \fBint64_t\fR \fIseconds\fR,
 130      \fBint32_t\fR \fIns\fR);
 131 .fi
 132
 133 .LP
 134 .nf
 135 \fBint\fR \fBscf_value_set_from_string\fR(\fBscf_value_t *\fR\fIv\fR, \fBscf_type_t\fR \fItype\fR,
 136      \fBchar *\fR\fIin\fR);
 137 .fi
 138
 139 .LP
 140 .nf
 141 \fBint\fR \fBscf_value_set_astring\fR(\fBscf_value_t *\fR\fIv\fR, \fBconst char *\fR\fIin\fR);
 142 .fi
 143
 144 .LP
 145 .nf
 146 \fBint\fR \fBscf_value_set_ustring\fR(\fBscf_value_t *\fR\fIv\fR, \fBconst char *\fR\fIin\fR);
 147 .fi
 148
 149 .LP
 150 .nf
 151 \fBint\fR \fBscf_value_set_opaque\fR(\fBscf_value_t *\fR\fIv\fR, \fBvoid *\fR\fIin\fR, \fBsize_t\fR \fIsz\fR);
 152 .fi
 153
 154 .SH DESCRIPTION
 155 .sp
 156 .LP
 157 The \fBscf_value_create()\fR function creates a new, reset \fBscf_value_t\fR
 158 that holds a single typed value. The value can be used only with the handle
 159 specified by \fIh\fR and objects associated with \fIh\fR.
 160 .sp
 161 .LP
 162 The \fBscf_value_reset()\fR function resets the value to the uninitialized
 163 state. The \fBscf_value_destroy()\fR function deallocates the object.
 164 .sp
 165 .LP
 166 The \fBscf_value_type()\fR function retrieves the type of the contents of
 167 \fIv\fR. The \fBscf_value_is_type()\fR function determines if a value is of a
 168 particular type or any of its subtypes. The \fBscf_type_base_type()\fR function
 169 returns the base type of \fItype\fR. The \fBscf_value_base_type()\fR function
 170 returns the true base type of the value (the highest type reachable from the
 171 value's type).
 172 .sp
 173
 174 .sp
 175 .TS
 176 c c c
 177 l l l .
 178 Type Identifier Base Type       Type Description
 179 _
 180 \fBSCF_TYPE_INVALID\fR          reserved invalid type
 181 \fBSCF_TYPE_BOOLEAN\fR          single bit
 182 \fBSCF_TYPE_COUNT\fR            unsigned 64-bit quantity
 183 \fBSCF_TYPE_INTEGER\fR          signed 64-bit quantity
 184 \fBSCF_TYPE_TIME\fR             T{
 185 signed 64-bit seconds, signed 32-bit nanoseconds in the range 0 <= \fIns\fR < 1,000,000,000
 186 T}
 187 \fBSCF_TYPE_ASTRING\fR          8-bit NUL-terminated string
 188 \fBSCF_TYPE_OPAQUE\fR           opaque 8-bit data
 189 \fBSCF_TYPE_USTRING\fR  \fBASTRING\fR   8-bit UTF-8 string
 190 \fBSCF_TYPE_URI\fR      \fBUSTRING\fR   a URI string
 191 \fBSCF_TYPE_FMRI\fR     \fBURI\fR       a Fault Management Resource Identifier
 192 \fBSCF_TYPE_HOST\fR     \fBUSTRING\fR   T{
 193 either a hostname, IPv4 address, or IPv6 address
 194 T}
 195 \fBSCF_TYPE_HOSTNAME\fR \fBHOST\fR      a fully-qualified domain name
 196 \fBSCF_TYPE_NET_ADDR_V4\fR      \fBHOST\fR      T{
 197 a dotted-quad IPv4 address with optional network portion
 198 T}
 199 \fBSCF_TYPE_NET_ADDR_V6\fR      \fBHOST\fR      legal IPv6 address
 200 .TE
 201
 202 .sp
 203 .LP
 204 The \fBscf_value_get_boolean()\fR, \fBscf_value_get_count()\fR,
 205 \fBscf_value_get_integer()\fR, \fBscf_value_get_time()\fR,
 206 \fBscf_value_get_astring()\fR, \fBscf_value_get_ustring()\fR, and
 207 \fBscf_value_get_opaque()\fR functions read a particular type of value from
 208 \fIv\fR.
 209 .sp
 210 .LP
 211 The \fBscf_value_get_as_string()\fR and \fBscf_value_get_as_string_typed()\fR
 212 functions convert the value to a string form. For
 213 \fBscf_value_get_as_string_typed()\fR, the value must be a reachable subtype of
 214 \fItype\fR.
 215 .sp
 216 .LP
 217 The \fBscf_value_set_boolean()\fR, \fBscf_value_set_count()\fR,
 218 \fBscf_value_set_integer()\fR, \fBscf_value_set_time()\fR,
 219 \fBscf_value_set_astring()\fR, \fBscf_value_set_ustring()\fR, and
 220 \fBscf_value_set_opaque()\fR functions set \fIv\fR to a particular value of a
 221 particular type.
 222 .sp
 223 .LP
 224 The \fBscf_value_set_from_string()\fR function is the inverse of
 225 \fBscf_value_get_as_string()\fR. It sets \fIv\fR to the value encoded in
 226 \fIbuf\fR of type \fItype\fR.
 227 .sp
 228 .LP
 229 The \fBscf_value_set_*()\fR functions will succeed on \fBscf_value_t\fR objects
 230 that have already been set.
 231 .SH RETURN VALUES
 232 .sp
 233 .LP
 234 Upon successful completion, \fBscf_value_create()\fR returns a new, reset
 235 \fBscf_value_t\fR. Otherwise, it returns \fINULL\fR.
 236 .sp
 237 .LP
 238 Upon successful completion, \fBscf_value_handle()\fR returns the handle
 239 associated with \fIv\fR. Otherwise, it returns \fINULL\fR.
 240 .sp
 241 .LP
 242 The \fBscf_value_base_type()\fR function returns the base type of the value, or
 243 \fBSCF_TYPE_INVALID\fR on failure.
 244 .sp
 245 .LP
 246 Upon successful completion, \fBscf_value_type()\fR returns the type of the
 247 value. Otherwise, it returns \fBSCF_TYPE_INVALID\fR.
 248 .sp
 249 .LP
 250 Upon successful completion, \fBscf_value_is_type()\fR,
 251 \fBscf_value_get_boolean()\fR, \fBscf_value_get_count()\fR,
 252 \fBscf_value_get_integer()\fR, \fBscf_value_get_time()\fR,
 253 \fBscf_value_set_time()\fR, \fBscf_value_set_from_string()\fR,
 254 \fBscf_value_set_astring()\fR, \fBscf_value_set_ustring()\fR, and
 255 \fBscf_value_set_opaque()\fR return 0. Otherwise, they return -1.
 256 .sp
 257 .LP
 258 Upon successful completion, \fBscf_value_get_astring()\fR,
 259 \fBscf_value_get_ustring()\fR, \fBscf_value_get_as_string()\fR, and
 260 \fBscf_value_get_as_string_typed()\fR return the length of the source string,
 261 not including the terminating null byte. Otherwise, they return -1.
 262 .sp
 263 .LP
 264 Upon successful completion, \fBscf_value_get_opaque()\fR returns the number of
 265 bytes written. Otherwise, it returns -1.
 266 .SH ERRORS
 267 .sp
 268 .LP
 269 The \fBscf_value_create()\fR function will fail if:
 270 .sp
 271 .ne 2
 272 .na
 273 \fB\fBSCF_ERROR_HANDLE_DESTROYED\fR\fR
 274 .ad
 275 .RS 30n
 276 The handle associated with \fIh\fR has been destroyed.
 277 .RE
 278
 279 .sp
 280 .ne 2
 281 .na
 282 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
 283 .ad
 284 .RS 30n
 285 The handle is \fINULL\fR.
 286 .RE
 287
 288 .sp
 289 .ne 2
 290 .na
 291 \fB\fBSCF_ERROR_NO_MEMORY\fR\fR
 292 .ad
 293 .RS 30n
 294 There is not enough memory to allocate an \fBscf_value_t\fR.
 295 .RE
 296
 297 .sp
 298 .LP
 299 The \fBscf_value_handle()\fR function will fail if:
 300 .sp
 301 .ne 2
 302 .na
 303 \fB\fBSCF_ERROR_HANDLE_DESTROYED\fR\fR
 304 .ad
 305 .RS 30n
 306 The handle associated with \fIv\fR has been destroyed.
 307 .RE
 308
 309 .sp
 310 .LP
 311 The \fBscf_value_set_time()\fR function will fail if:
 312 .sp
 313 .ne 2
 314 .na
 315 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
 316 .ad
 317 .RS 30n
 318 The nanoseconds field is not in the range 0 <= \fIns\fR < 1,000,000,000.
 319 .RE
 320
 321 .sp
 322 .LP
 323 The \fBscf_type_base_type()\fR function will fail if:
 324 .sp
 325 .ne 2
 326 .na
 327 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
 328 .ad
 329 .RS 30n
 330 The \fItype\fR argument is not a valid type.
 331 .RE
 332
 333 .sp
 334 .LP
 335 The \fBscf_value_set_astring()\fR, \fBscf_value_set_ustring()\fR,
 336 \fBscf_value_set_opaque()\fR, and \fBscf_value_set_from_string()\fR functions
 337 will fail if:
 338 .sp
 339 .ne 2
 340 .na
 341 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
 342 .ad
 343 .RS 30n
 344 The \fIin\fR argument is not a valid value for the specified type or is longer
 345 than the maximum supported value length.
 346 .RE
 347
 348 .sp
 349 .LP
 350 The \fBscf_type_base_type()\fR, \fBscf_value_is_type()\fR, and
 351 \fBscf_value_get_as_string_typed()\fR functions will fail if:
 352 .sp
 353 .ne 2
 354 .na
 355 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
 356 .ad
 357 .RS 30n
 358 The \fItype\fR argument is not a valid type.
 359 .RE
 360
 361 .sp
 362 .LP
 363 The \fBscf_value_type()\fR, \fBscf_value_base_type()\fR,
 364 \fBscf_value_get_boolean()\fR, \fBscf_value_get_count()\fR,
 365 \fBscf_value_get_integer()\fR, \fBscf_value_get_time()\fR,
 366 \fBscf_value_get_astring()\fR, \fBscf_value_get_ustring()\fR,
 367 \fBscf_value_get_as_string()\fR, and\fBscf_value_get_as_string_typed()\fR
 368 functions will fail if:
 369 .sp
 370 .ne 2
 371 .na
 372 \fB\fBSCF_ERROR_NOT_SET\fR\fR
 373 .ad
 374 .RS 21n
 375 The \fIv\fR argument has not been set to a value.
 376 .RE
 377
 378 .sp
 379 .LP
 380 The \fBscf_value_get_boolean()\fR, \fBscf_value_get_count()\fR,
 381 \fBscf_value_get_integer()\fR, \fBscf_value_get_time()\fR,
 382 \fBscf_value_get_astring()\fR, \fBscf_value_get_ustring()\fR, and
 383 \fBscf_value_get_as_string_typed()\fR functions will fail if:
 384 .sp
 385 .ne 2
 386 .na
 387 \fB\fBSCF_ERROR_TYPE_MISMATCH\fR\fR
 388 .ad
 389 .RS 27n
 390 The requested type is not the same as the value's type and is not in the
 391 base-type chain.
 392 .RE
 393
 394 .sp
 395 .LP
 396 The \fBscf_error\fR(3SCF) function can be used to retrieve the error value.
 397 .SH ATTRIBUTES
 398 .sp
 399 .LP
 400 See \fBattributes\fR(5) for descriptions of the following attributes:
 401 .sp
 402
 403 .sp
 404 .TS
 405 box;
 406 c | c
 407 l | l .
 408 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 409 _
 410 Interface Stability     Committed
 411 _
 412 MT-Level        Safe
 413 .TE
 414
 415 .SH SEE ALSO
 416 .sp
 417 .LP
 418 \fBlibscf\fR(3LIB), \fBscf_entry_add_value\fR(3SCF), \fBscf_error\fR(3SCF),
 419 \fBattributes\fR(5)