usr/src/man/man3pool/pool_value_alloc.3pool

   1 '\" te
   2 .\" Copyright (c) 2003, 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 POOL_VALUE_ALLOC 3POOL "Sep 23, 2003"
   7 .SH NAME
   8 pool_value_alloc, pool_value_free, pool_value_get_bool, pool_value_get_double,
   9 pool_value_get_int64, pool_value_get_name, pool_value_get_string,
  10 pool_value_get_type, pool_value_get_uint64, pool_value_set_bool,
  11 pool_value_set_double, pool_value_set_int64, pool_value_set_name,
  12 pool_value_set_string, pool_value_set_uint64 \- resource pool property value
  13 manipulation functions
  14 .SH SYNOPSIS
  15 .LP
  16 .nf
  17 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpool\fR [ \fIlibrary\fR\&.\|.\|. ]
  18 #include <pool.h>
  19
  20 \fBpool_value_t *\fR\fBpool_value_alloc\fR(\fBvoid\fR);
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fBvoid\fR \fBpool_value_free\fR(\fBpool_value_t *\fR\fIvalue\fR);
  26 .fi
  27
  28 .LP
  29 .nf
  30 \fBpool_value_class_t\fR \fBpool_value_get_type\fR(
  31      \fBconst pool_value_t *\fR\fIvalue\fR);
  32 .fi
  33
  34 .LP
  35 .nf
  36 \fBint\fR \fBpool_value_get_bool\fR(\fBconst pool_value_t *\fR\fIvalue\fR,
  37      \fBuchar_t *\fR\fIbool\fR);
  38 .fi
  39
  40 .LP
  41 .nf
  42 \fBint\fR \fBpool_value_get_double\fR(\fBconst pool_value_t *\fR\fIvalue\fR,
  43      \fBdouble *\fR\fId\fR);
  44 .fi
  45
  46 .LP
  47 .nf
  48 \fBint\fR \fBpool_value_get_int64\fR(\fBconst pool_value_t *\fR\fIvalue\fR,
  49      \fBint64_t *\fR\fIi64\fR);
  50 .fi
  51
  52 .LP
  53 .nf
  54 \fBint\fR \fBpool_value_get_string\fR(\fBconst pool_value_t *\fR\fIvalue\fR,
  55      \fBconst char **\fR\fIstrp\fR);
  56 .fi
  57
  58 .LP
  59 .nf
  60 \fBint\fR \fBpool_value_get_uint64\fR(\fBconst pool_value_t *\fR\fIvalue\fR,
  61      \fBuint64_t *\fR\fIui64\fR);
  62 .fi
  63
  64 .LP
  65 .nf
  66 \fBvoid\fR \fBpool_value_set_bool\fR(\fBconst pool_value_t *\fR\fIvalue\fR,
  67      \fBuchar_t\fR \fIbool\fR);
  68 .fi
  69
  70 .LP
  71 .nf
  72 \fBvoid\fR \fBpool_value_set_double\fR(\fBconst pool_value_t *\fR\fIvalue\fR,
  73      \fBdouble\fR \fId\fR);
  74 .fi
  75
  76 .LP
  77 .nf
  78 \fBvoid\fR \fBpool_value_set_int64\fR(\fBconst pool_value_t *\fR\fIvalue\fR,
  79      \fBint64_t\fR \fIi64\fR);
  80 .fi
  81
  82 .LP
  83 .nf
  84 \fBint\fR \fBpool_value_set_string\fR(\fBconst pool_value_t *\fR\fIvalue\fR,
  85      \fBconst char *\fR\fIstrp\fR);
  86 .fi
  87
  88 .LP
  89 .nf
  90 \fBvoid\fR \fBpool_value_set_uint64\fR(\fBconst pool_value_t *\fR\fIvalue\fR,
  91      \fBuint64_t\fR \fIui64\fR);
  92 .fi
  93
  94 .LP
  95 .nf
  96 \fBconst char *\fR\fBpool_value_get_name\fR(\fBconst pool_value_t *\fR\fIvalue\fR);
  97 .fi
  98
  99 .LP
 100 .nf
 101 \fBint\fR \fBpool_value_set_name\fR(\fBconst pool_value_t *\fR\fIvalue\fR,
 102      \fBconst char *\fR\fIname\fR);
 103 .fi
 104
 105 .SH DESCRIPTION
 106 .sp
 107 .LP
 108 A \fBpool_value_t\fR is an opaque type representing the typed value portion of
 109 a pool property. For a list of the types supported by a \fBpool_value_t\fR, see
 110 \fBpool_get_property\fR(3POOL).
 111 .sp
 112 .LP
 113 The \fBpool_value_alloc()\fR function allocates and returns an opaque container
 114 for a pool property value. The \fBpool_value_free()\fR function must be called
 115 explicitly for allocated property values.
 116 .sp
 117 .LP
 118 The \fBpool_value_get_bool()\fR, \fBpool_value_get_double()\fR,
 119 \fBpool_value_get_int64()\fR, \fBpool_value_get_string()\fR, and
 120 \fBpool_value_get_uint64()\fR functions retrieve the value contained in the
 121 \fBpool_value_t\fR pointed to by \fIvalue\fR to the location pointed to by the
 122 second argument. If the type of the value does not match that expected by the
 123 function, an error value is returned.  The string retrieved by
 124 \fBpool_value_get_string()\fR is freed by the library when the value is
 125 overwritten or \fBpool_value_free()\fR is called on the pool property value.
 126 .sp
 127 .LP
 128 The \fBpool_value_get_type()\fR function returns the type of the data contained
 129 by a \fBpool_value_t\fR. If the value is unused then a type of \fBPOC_INVAL\fR
 130 is returned.
 131 .sp
 132 .LP
 133 The \fBpool_value_set_bool()\fR, \fBpool_value_set_double()\fR,
 134 \fBpool_value_set_int64()\fR, \fBpool_value_set_string()\fR, and
 135 \fBpool_value_set_uint64()\fR functions set the value and type of the property
 136 value to the provided values. The \fBpool_value_set_string()\fR function copies
 137 the string passed in and returns -1 if the memory allocation fails.
 138 .sp
 139 .LP
 140 Property values can optionally have names. These names are used to describe
 141 properties as name=value pairs in the various query functions (see
 142 \fBpool_query_resources\fR(3POOL)).  A copy of the string passed to
 143 \fBpool_value_set_name()\fR is made by the library, and the value returned by
 144 \fBpool_value_get_name()\fR is freed when the \fBpool_value_t\fR is deallocated
 145 or overwritten.
 146 .SH RETURN VALUES
 147 .sp
 148 .LP
 149 Upon successful completion, \fBpool_value_alloc()\fR returns a pool property
 150 value with type initialized to \fBPVC_INVAL\fR. Otherwise, \fINULL\fR is
 151 returned and \fBpool_error()\fR returns the pool-specific error value.
 152 .sp
 153 .LP
 154 Upon successful completion, \fBpool_value_get_type()\fR returns the type
 155 contained in the property value passed in as an argument. Otherwise,
 156 \fBPOC_INVAL\fR is returned and \fBpool_error()\fR returns the pool-specific
 157 error value.
 158 .sp
 159 .LP
 160 Upon successful completion, \fBpool_value_get_bool()\fR,
 161 \fBpool_value_get_double()\fR, \fBpool_value_get_int64()\fR,
 162 \fBpool_value_get_string()\fR, and \fBpool_value_get_uint64()\fR return 0.
 163 Otherwise -1 is returned and \fBpool_error\fR(3POOL) returns the pool-specific
 164 error value.
 165 .sp
 166 .LP
 167 Upon successful completion, \fBpool_value_set_string()\fR and
 168 \fBpool_value_set_name()\fR return 0. If the memory allocation failed, -1 is
 169 returned and \fBpool_error()\fR returns the pool-specific error value.
 170 .SH ERRORS
 171 .sp
 172 .LP
 173 The \fBpool_value_alloc()\fR function will fail if:
 174 .sp
 175 .ne 2
 176 .na
 177 \fB\fBPOE_SYSTEM\fR\fR
 178 .ad
 179 .RS 14n
 180 A system error has occurred. Check the system error code for more details.
 181 .RE
 182
 183 .sp
 184 .LP
 185 The \fBpool_value_get_bool()\fR, \fBpool_value_get_double()\fR,
 186 \fBpool_value_get_int64()\fR, \fBpool_value_get_string()\fR, and
 187 \fBpool_value_get_uint64()\fR functions will fail if:
 188 .sp
 189 .ne 2
 190 .na
 191 \fB\fBPOE_BADPARAM\fR\fR
 192 .ad
 193 .RS 16n
 194 The supplied \fIvalue\fR does not match the type of the requested operation.
 195 .RE
 196
 197 .sp
 198 .LP
 199 The \fBpool_value_set_string()\fR function will fail if:
 200 .sp
 201 .ne 2
 202 .na
 203 \fB\fBPOE_SYSTEM\fR\fR
 204 .ad
 205 .RS 14n
 206 A system error has occurred. Check the system error code for more details.
 207 .RE
 208
 209 .sp
 210 .LP
 211 The \fBpool_value_set_name()\fR function will fail if:
 212 .sp
 213 .ne 2
 214 .na
 215 \fB\fBPOE_SYSTEM\fR\fR
 216 .ad
 217 .RS 14n
 218 A system error has occurred. Check the system error code for more details.
 219 .RE
 220
 221 .SH ATTRIBUTES
 222 .sp
 223 .LP
 224 See \fBattributes\fR(5) for descriptions of the following attributes:
 225 .sp
 226
 227 .sp
 228 .TS
 229 box;
 230 c | c
 231 l | l .
 232 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 233 _
 234 CSI     Enabled
 235 _
 236 Interface Stability     Unstable
 237 _
 238 MT-Level        Safe
 239 .TE
 240
 241 .SH SEE ALSO
 242 .sp
 243 .LP
 244 \fBlibpool\fR(3LIB), \fBpool_error\fR(3POOL), \fBattributes\fR(5)