share/man/man3nvpair/nvlist_add_boolean.3nvpair

   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 .\" Copyright (c) 2016 Delphix. All Rights Reserved.
   7 .TH NVLIST_ADD_BOOLEAN 3NVPAIR "Sep 15, 2009"
   8 .SH NAME
   9 nvlist_add_boolean, nvlist_add_boolean_value, nvlist_add_byte, nvlist_add_int8,
  10 nvlist_add_uint8, nvlist_add_int16, nvlist_add_uint16, nvlist_add_int32,
  11 nvlist_add_uint32, nvlist_add_int64, nvlist_add_uint64, nvlist_add_double,
  12 nvlist_add_string, nvlist_add_nvlist, nvlist_add_nvpair,
  13 nvlist_add_boolean_array, nvlist_add_byte_array, nvlist_add_int8_array,
  14 nvlist_add_uint8_array, nvlist_add_int16_array, nvlist_add_uint16_array,
  15 nvlist_add_int32_array, nvlist_add_uint32_array, nvlist_add_int64_array,
  16 nvlist_add_uint64_array, nvlist_add_string_array, nvlist_add_nvlist_array \-
  17 add new name-value pair to nvlist_t
  18 .SH SYNOPSIS
  19 .LP
  20 .nf
  21 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lnvpair\fR [ \fIlibrary\fR... ]
  22 #include <libnvpair.h>
  23
  24 \fBint\fR \fBnvlist_add_boolean\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR);
  25 .fi
  26
  27 .LP
  28 .nf
  29 \fBint\fR \fBnvlist_add_boolean_value\fR(\fBnvlist_t *\fR\fInvl\fR,
  30      \fBconst char *\fR\fIname\fR, \fBboolean_t\fR \fIval\fR);
  31 .fi
  32
  33 .LP
  34 .nf
  35 \fBint\fR \fBnvlist_add_byte\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
  36      \fBuchar_t\fR \fIval\fR);
  37 .fi
  38
  39 .LP
  40 .nf
  41 \fBint\fR \fBnvlist_add_int8\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
  42      \fBint8_t\fR \fIval\fR);
  43 .fi
  44
  45 .LP
  46 .nf
  47 \fBint\fR \fBnvlist_add_uint8\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
  48      \fBuint8_t\fR \fIval\fR);
  49 .fi
  50
  51 .LP
  52 .nf
  53 \fBint\fR \fBnvlist_add_int16\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
  54      \fBint16_t\fR \fIval\fR);
  55 .fi
  56
  57 .LP
  58 .nf
  59 \fBint\fR \fBnvlist_add_uint16\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
  60      \fBuint16_t\fR \fIval\fR);
  61 .fi
  62
  63 .LP
  64 .nf
  65 \fBint\fR \fBnvlist_add_int32\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
  66      \fBint32_t\fR \fIval\fR);
  67 .fi
  68
  69 .LP
  70 .nf
  71 \fBint\fR \fBnvlist_add_uint32\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
  72      \fBuint32_t\fR \fIval\fR);
  73 .fi
  74
  75 .LP
  76 .nf
  77 \fBint\fR \fBnvlist_add_int64\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
  78      \fBint64_t\fR \fIval\fR);
  79 .fi
  80
  81 .LP
  82 .nf
  83 \fBint\fR \fBnvlist_add_uint64\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
  84      \fBuint64_t\fR \fIval\fR);
  85 .fi
  86
  87 .LP
  88 .nf
  89 \fBint\fR \fBnvlist_add_double\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
  90      \fBdouble\fR \fIval\fR);
  91 .fi
  92
  93 .LP
  94 .nf
  95 \fBint\fR \fBnvlist_add_string\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
  96      \fBconst char *\fR\fIval\fR);
  97 .fi
  98
  99 .LP
 100 .nf
 101 \fBint\fR \fBnvlist_add_nvlist\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
 102      \fBnvlist_t *\fR\fIval\fR);
 103 .fi
 104
 105 .LP
 106 .nf
 107 \fBint\fR \fBnvlist_add_nvpair\fR(\fBnvlist_t *\fR\fInvl\fR, \fBnvpair_t *\fR\fInvp\fR);
 108 .fi
 109
 110 .LP
 111 .nf
 112 \fBint\fR \fBnvlist_add_boolean_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
 113      \fBboolean_t *\fR\fIval\fR, \fBuint_t\fR \fInelem\fR);
 114 .fi
 115
 116 .LP
 117 .nf
 118 \fBint\fR \fBnvlist_add_byte_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
 119      \fBuchar_t *\fR\fIval\fR, \fBuint_t\fR \fInelem\fR);
 120 .fi
 121
 122 .LP
 123 .nf
 124 \fBint\fR \fBnvlist_add_int8_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
 125      \fBint8_t *\fR\fIval\fR, \fBuint_t\fR \fInelem\fR);
 126 .fi
 127
 128 .LP
 129 .nf
 130 \fBint\fR \fBnvlist_add_uint8_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
 131      \fBuint8_t *\fR\fIval\fR, \fBuint_t\fR \fInelem\fR);
 132 .fi
 133
 134 .LP
 135 .nf
 136 \fBint\fR \fBnvlist_add_int16_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
 137      \fBint16_t *\fR\fIval\fR, \fBuint_t\fR \fInelem\fR);
 138 .fi
 139
 140 .LP
 141 .nf
 142 \fBint\fR \fBnvlist_add_uint16_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
 143      \fBuint16_t *\fR\fIval\fR, \fBuint_t\fR \fInelem\fR);
 144 .fi
 145
 146 .LP
 147 .nf
 148 \fBint\fR \fBnvlist_add_int32_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
 149      \fBint32_t *\fR\fIval\fR, \fBuint_t\fR \fInelem\fR);
 150 .fi
 151
 152 .LP
 153 .nf
 154 \fBint\fR \fBnvlist_add_uint32_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
 155      \fBuint32_t *\fR\fIval\fR, \fBuint_t\fR \fInelem\fR);
 156 .fi
 157
 158 .LP
 159 .nf
 160 \fBint\fR \fBnvlist_add_int64_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
 161      \fBint64_t *\fR\fIval\fR, \fBuint_t\fR \fInelem\fR);
 162 .fi
 163
 164 .LP
 165 .nf
 166 \fBint\fR \fBnvlist_add_uint64_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
 167      \fBuint64_t *\fR\fIval\fR, \fBuint_t\fR \fInelem\fR);
 168 .fi
 169
 170 .LP
 171 .nf
 172 \fBint\fR \fBnvlist_add_string_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
 173      \fBchar *const *\fR\fIval\fR, \fBuint_t\fR \fInelem\fR);
 174 .fi
 175
 176 .LP
 177 .nf
 178 \fBint\fR \fBnvlist_add_nvlist_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
 179      \fBnvlist_t **\fR\fIval\fR, \fBuint_t\fR \fInelem\fR);
 180 .fi
 181
 182 .SH PARAMETERS
 183 .ne 2
 184 .na
 185 \fB\fInvl\fR\fR
 186 .ad
 187 .RS 9n
 188 The \fBnvlist_t\fR (name-value pair list) to be processed.
 189 .RE
 190
 191 .sp
 192 .ne 2
 193 .na
 194 \fB\fInvp\fR\fR
 195 .ad
 196 .RS 9n
 197 The \fBnvpair_t\fR (name-value pair) to be processed.
 198 .RE
 199
 200 .sp
 201 .ne 2
 202 .na
 203 \fB\fIname\fR\fR
 204 .ad
 205 .RS 9n
 206 Name of the \fBnvpair\fR (name-value pair).
 207 .RE
 208
 209 .sp
 210 .ne 2
 211 .na
 212 \fB\fInelem\fR\fR
 213 .ad
 214 .RS 9n
 215 Number of elements in value (that is, array size).
 216 .RE
 217
 218 .sp
 219 .ne 2
 220 .na
 221 \fB\fIval\fR\fR
 222 .ad
 223 .RS 9n
 224 Value or starting address of the array value.
 225 .RE
 226
 227 .SH DESCRIPTION
 228 .LP
 229 These functions add a new name-value pair to an \fBnvlist_t\fR. The uniqueness
 230 of \fBnvpair\fR name and data types follows the \fInvflag\fR argument specified
 231 for \fBnvlist_alloc()\fR. See \fBnvlist_alloc\fR(3NVPAIR).
 232 .sp
 233 .LP
 234 If \fBNV_UNIQUE_NAME\fR was specified for \fInvflag\fR, existing \fBnvpair\fRs
 235 with matching names are removed before the new \fBnvpair\fR is added.
 236 .sp
 237 .LP
 238 If \fBNV_UNIQUE_NAME_TYPE\fR was specified for \fInvflag\fR, existing
 239 \fBnvpair\fRs with matching names and data types are removed before the new
 240 \fBnvpair\fR is added.
 241 .sp
 242 .LP
 243 If neither was specified for \fInvflag\fR, the new \fBnvpair\fR is
 244 unconditionally added at the end of the list. The library preserves the order
 245 of the name-value pairs across packing, unpacking, and duplication.
 246 .sp
 247 .LP
 248 Multiple threads can simultaneously read the same \fBnvlist_t\fR, but only one
 249 thread can actively change a given \fBnvlist_t\fR at a time. The caller is
 250 responsible for the synchronization.
 251 .sp
 252 .LP
 253 The name used for any name-value pair, including the terminating null
 254 byte, can be no more than
 255 .B INT16_MAX
 256 (2^15 - 1) bytes in
 257 length, otherwise
 258 .B EINVAL
 259 will be returned.
 260 .sp
 261 .LP
 262 The list that is added to the parent \fBnvlist_t\fR by calling
 263 \fBnvlist_add_nvlist()\fR is copied and thus is not freed when
 264 \fBnvlist_free()\fR is called on the parent list. To prevent memory leaks, your
 265 code needs to look like the following (error handling elided for clarity):
 266 .sp
 267 .in +2
 268 .nf
 269 nvlist_t *parent_nvl;
 270 nvlist_t *child_nvl;
 271
 272 /* create parent list, add an entry */
 273 (void) nvlist_alloc(&parent_nvl, NV_UNIQUE_NAME, KM_SLEEP);
 274 (void) nvlist_add_boolean(parent_nvl, "parent_bool", 0);
 275
 276 /* create child list, add an entry */
 277 (void) nvlist_alloc(&child_nvl, NV_UNIQUE_NAME, KM_SLEEP);
 278 (void) nvlist_add_boolean(child_nvl, "child_bool", 0);
 279
 280 /* add the child to the parent */
 281 (void) nvlist_add_nvlist(parent_nvl, "child_nvlist", child_nvl);
 282
 283 /* do stuff .. */
 284
 285 /* free nvlist(s) */
 286 (void) nvlist_free(child_nvl); /* required, but not obvious */
 287 (void) nvlist_free(parent_nvl);
 288 .fi
 289 .in -2
 290
 291 .sp
 292 .LP
 293 The \fBnvlist_add_boolean()\fR function is deprecated. The
 294 \fBnvlist_add_boolean_value()\fR function should be used instead.
 295 .SH RETURN VALUES
 296 .LP
 297 These functions return 0 on success and an error value on failure.
 298 .SH ERRORS
 299 .LP
 300 These functions will fail if:
 301 .sp
 302 .ne 2
 303 .na
 304 \fB\fBEINVAL\fR\fR
 305 .ad
 306 .RS 10n
 307 There is an invalid argument.
 308 .RE
 309
 310 .sp
 311 .ne 2
 312 .na
 313 \fB\fBENOMEM\fR\fR
 314 .ad
 315 .RS 10n
 316 There is insufficient memory.
 317 .RE
 318
 319 .SH ATTRIBUTES
 320 .LP
 321 See \fBattributes\fR(5) for descriptions of the following attributes:
 322 .sp
 323
 324 .sp
 325 .TS
 326 box;
 327 c | c
 328 l | l .
 329 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 330 _
 331 Interface Stability     Committed
 332 _
 333 MT-Level        MT-Safe
 334 .TE
 335
 336 .SH SEE ALSO
 337 .LP
 338 \fBlibnvpair\fR(3LIB), \fBnvlist_alloc\fR(3NVPAIR), \fBattributes\fR(5)