usr/src/man/man9f/nvlist_alloc.9f

   1 '\" te
   2 .\" Copyright (c) 2006, 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 NVLIST_ALLOC 9F "Feb 15, 2016"
   7 .SH NAME
   8 nvlist_alloc, nvlist_free, nvlist_size, nvlist_pack, nvlist_unpack, nvlist_dup,
   9 nv_alloc_init, nv_alloc_fini, nvlist_xalloc, nvlist_xpack, nvlist_xunpack,
  10 nvlist_xdup, nvlist_merge \- Manage a name-value pair list
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 #include <sys/nvpair.h>
  15
  16 List Manipulation:
  17
  18 \fBint\fR \fBnvlist_alloc\fR(\fBnvlist_t **\fR\fInvlp\fR, \fBuint_t\fR \fInvflag\fR,
  19      \fBint\fR \fIkmflag\fR);
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fBint\fR \fBnvlist_xalloc\fR(\fBnvlist_t **\fR\fInvlp\fR, \fBuint_t\fR \fInvflag\fR, \fBnv_alloc_t *\fR\fInva\fR);
  25 .fi
  26
  27 .LP
  28 .nf
  29 \fBvoid\fR \fBnvlist_free\fR(\fBnvlist_t *\fR\fInvl\fR);
  30 .fi
  31
  32 .LP
  33 .nf
  34 \fBint\fR \fBnvlist_size\fR(\fBnvlist_t *\fR\fInvl\fR, \fBsize_t *\fR\fIsize\fR, \fBint\fR \fIencoding\fR);
  35 .fi
  36
  37 .LP
  38 .nf
  39 \fBint\fR \fBnvlist_pack\fR(\fBnvlist_t *\fR\fInvl\fR, \fBchar **\fR\fIbufp\fR, \fBsize_t *\fR\fIbuflen\fR, \fBint\fR \fIencoding\fR,
  40      \fBint\fR \fIflag\fR);
  41 .fi
  42
  43 .LP
  44 .nf
  45 \fBint\fR \fBnvlist_xpack\fR(\fBnvlist_t *\fR\fInvl\fR, \fBchar **\fR\fIbufp\fR, \fBsize_t *\fR\fIbuflen\fR, \fBint\fR \fIencoding\fR,
  46      \fBnv_alloc_t *\fR\fInva\fR);
  47 .fi
  48
  49 .LP
  50 .nf
  51 \fBint\fR \fBnvlist_unpack\fR(\fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIbuflen\fR, \fBnvlist_t **\fR\fInvlp\fR, \fBint\fR \fIflag\fR);
  52 .fi
  53
  54 .LP
  55 .nf
  56 \fBint\fR \fBnvlist_xunpack\fR(\fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIbuflen\fR, \fBnvlist_t **\fR\fInvlp\fR,
  57      \fBnv_alloc_t *\fR\fInva\fR);
  58 .fi
  59
  60 .LP
  61 .nf
  62 \fBint\fR \fBnvlist_dup\fR(\fBnvlist_t *\fR\fInvl\fR, \fBnvlist_t **\fR\fInvlp\fR, \fBint\fR \fIflag\fR);
  63 .fi
  64
  65 .LP
  66 .nf
  67 \fBint\fR \fBnvlist_xdup\fR(\fBnvlist_t *\fR\fInvl\fR, \fBnvlist_t **\fR\fInvlp\fR, \fBnv_alloc_t *\fR\fInva\fR);
  68 .fi
  69
  70 .LP
  71 .nf
  72 \fBint\fR \fBnvlist_merge\fR(\fBnvlist_t *\fR\fIdst\fR, \fBnvlist_t *\fR\fInvl\fR, \fBint\fR \fIflag\fR);
  73 .fi
  74
  75 .LP
  76 .nf
  77 Pluggable Allocator Configuration:
  78
  79 \fBnv_alloc_t *\fR\fBnvlist_lookup_nv_alloc\fR(\fBnvlist_t *);\fR
  80 .fi
  81
  82 .LP
  83 .nf
  84 \fBint\fR \fBnv_alloc_init\fR(\fBnv_alloc_t *\fR\fInva\fR,
  85      \fBconst nv_alloc_ops_t *\fR \fInvo,\fR/* args */ ...);
  86 .fi
  87
  88 .LP
  89 .nf
  90 \fBvoid\fR  \fBnv_alloc_reset\fR(\fBnv_alloc_t  *\fR\fInva\fR);
  91 .fi
  92
  93 .LP
  94 .nf
  95 \fBvoid\fR  \fBnv_alloc_fini\fR(\fBnv_alloc_t *\fR\fInva\fR);
  96 .fi
  97
  98 .LP
  99 .nf
 100 Pluggable Allocation Initialization with Fixed Allocator:
 101
 102 \fBint\fR \fBnv_alloc_init\fR(\fBnv_alloc_t *\fR\fInva\fR,
 103      \fBnv_fixed_ops\fR, \fBvoid *\fR \fIbufptr\fR,  \fBsize_t\fR sz);
 104 .fi
 105
 106 .SH INTERFACE LEVEL
 107 .LP
 108 Solaris DDI specific (Solaris DDI)
 109 .SH PARAMETERS
 110 .ne 2
 111 .na
 112 \fB\fInvlp\fR\fR
 113 .ad
 114 .RS 12n
 115 Address of a pointer to list of name-value pairs (\fBnvlist_t\fR).
 116 .RE
 117
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fInvflag\fR\fR
 122 .ad
 123 .RS 12n
 124 Specify bit fields defining \fBnvlist_t\fR properties:
 125 .sp
 126 .ne 2
 127 .na
 128 \fB\fBNV_UNIQUE_NAME\fR\fR
 129 .ad
 130 .RS 23n
 131 \fBnvpair\fR names are unique.
 132 .RE
 133
 134 .sp
 135 .ne 2
 136 .na
 137 \fB\fBNV_UNIQUE_NAME_TYPE\fR\fR
 138 .ad
 139 .RS 23n
 140 Name-data type combination is unique
 141 .RE
 142
 143 .RE
 144
 145 .sp
 146 .ne 2
 147 .na
 148 \fB\fIkmflag\fR\fR
 149 .ad
 150 .RS 12n
 151 Kernel memory allocation policy, either \fBKM_SLEEP\fR or \fBKM_NOSLEEP\fR.
 152 .RE
 153
 154 .sp
 155 .ne 2
 156 .na
 157 \fB\fInvl\fR\fR
 158 .ad
 159 .RS 12n
 160 \fBnvlist_t\fR to be processed.
 161 .RE
 162
 163 .sp
 164 .ne 2
 165 .na
 166 \fB\fIdst\fR\fR
 167 .ad
 168 .RS 12n
 169 Destination \fBnvlist_t\fR.
 170 .RE
 171
 172 .sp
 173 .ne 2
 174 .na
 175 \fB\fIsize\fR\fR
 176 .ad
 177 .RS 12n
 178 Pointer to buffer to contain the encoded size.
 179 .RE
 180
 181 .sp
 182 .ne 2
 183 .na
 184 \fB\fIbufp\fR\fR
 185 .ad
 186 .RS 12n
 187 Address of buffer to pack \fBnvlist\fR into. Must be 8-byte aligned. If NULL,
 188 library will allocate memory.
 189 .RE
 190
 191 .sp
 192 .ne 2
 193 .na
 194 \fB\fIbuf\fR\fR
 195 .ad
 196 .RS 12n
 197 Buffer containing packed \fBnvlist_t\fR.
 198 .RE
 199
 200 .sp
 201 .ne 2
 202 .na
 203 \fB\fIbuflen\fR\fR
 204 .ad
 205 .RS 12n
 206 Size of buffer \fIbufp\fR or \fIbuf\fR points to.
 207 .RE
 208
 209 .sp
 210 .ne 2
 211 .na
 212 \fB\fIencoding\fR\fR
 213 .ad
 214 .RS 12n
 215 Encoding method for packing.
 216 .RE
 217
 218 .sp
 219 .ne 2
 220 .na
 221 \fB\fInvo\fR\fR
 222 .ad
 223 .RS 12n
 224 Pluggable allocator operations pointer (nv_alloc_ops_t).
 225 .RE
 226
 227 .sp
 228 .ne 2
 229 .na
 230 \fB\fInva\fR\fR
 231 .ad
 232 .RS 12n
 233 Points to a nv_alloc_t structure to be used for the specified \fBnvlist_t\fR.
 234 .RE
 235
 236 .SH DESCRIPTION
 237 .LP
 238 List Manipulation:
 239 .sp
 240 .LP
 241 The \fBnvlist_alloc()\fR function allocates a new name-value pair list and
 242 updates \fInvlp\fR to point to the handle. The argument \fInvflag\fR specifies
 243 \fBnvlist_t\fR properties to remain persistent across packing, unpacking, and
 244 duplication.
 245 .sp
 246 .LP
 247 If \fBNV_UNIQUE_NAME\fR is specified for nvflag, existing nvpairs with matching
 248 names are removed before the new nvpair is added. If \fBNV_UNIQUE_NAME_TYPE\fR
 249 is specified for nvflag, existing nvpairs with matching names and data types
 250 are removed before the new nvpair is added. See \fBnvlist_add_byte\fR(9F) for
 251 more details.
 252 .sp
 253 .LP
 254 The \fBnvlist_xalloc()\fR function differs from \fBnvlist_alloc()\fR in that
 255 \fBnvlist_xalloc()\fR can use a different allocator, as described in the
 256 Pluggable Allocators section.
 257 .sp
 258 .LP
 259 The \fBnvlist_free()\fR function frees a name-value pair list. If \fInvl\fR
 260 is a null pointer, no action occurs.
 261 .sp
 262 .LP
 263 The \fBnvlist_size()\fR function returns the minimum size of a contiguous
 264 buffer large enough to pack \fInvl\fR. The \fIencoding\fR parameter specifies
 265 the method of encoding when packing \fInvl\fR. Supported encoding methods are:
 266 .sp
 267 .ne 2
 268 .na
 269 \fB\fBNV_ENCODE_NATIVE\fR\fR
 270 .ad
 271 .RS 20n
 272 Straight \fBbcopy()\fR as described in \fBbcopy\fR(9F).
 273 .RE
 274
 275 .sp
 276 .ne 2
 277 .na
 278 \fB\fBNV_ENCODE_XDR\fR\fR
 279 .ad
 280 .RS 20n
 281 Use XDR encoding, suitable for sending to another host.
 282 .RE
 283
 284 .sp
 285 .LP
 286 The \fBnvlist_pack()\fR function packs \fInvl\fR into contiguous memory
 287 starting at *\fIbufp\fR. The \fIencoding\fR parameter specifies the method of
 288 encoding (see above).
 289 .RS +4
 290 .TP
 291 .ie t \(bu
 292 .el o
 293 If *\fIbufp\fR is not NULL, *\fIbufp\fR is expected to be a caller-allocated
 294 buffer of size *\fIbuflen\fR. The \fIkmflag\fR argument is ignored.
 295 .RE
 296 .RS +4
 297 .TP
 298 .ie t \(bu
 299 .el o
 300 If *\fIbufp\fR is NULL, the library allocates memory and updates *\fIbufp\fR to
 301 point to the memory and updates *\fIbuflen\fR to contain the size of the
 302 allocated memory. The value of \fIkmflag\fR indicates the memory allocation
 303 policy
 304 .RE
 305 .sp
 306 .LP
 307 The \fBnvlist_xpack()\fR function differs from \fBnvlist_pack()\fR in that
 308 \fBnvlist_xpack()\fR can use a different allocator.
 309 .sp
 310 .LP
 311 The \fBnvlist_unpack()\fR function takes a buffer with a packed \fBnvlist_t\fR
 312 and unpacks it into a searchable \fBnvlist_t\fR. The library allocates memory
 313 for \fBnvlist_t\fR. The caller is responsible for freeing the memory by calling
 314 \fBnvlist_free()\fR.
 315 .sp
 316 .LP
 317 The \fBnvlist_xunpack()\fR function differs from \fBnvlist_unpack()\fR in that
 318 \fBnvlist_xunpack()\fR can use a different allocator.
 319 .sp
 320 .LP
 321 The \fBnvlist_dup()\fR function makes a copy of \fInvl\fR and updates
 322 \fInvlp\fR to point to the copy.
 323 .sp
 324 .LP
 325 The \fBnvlist_xdup()\fR function differs from \fBnvlist_dup()\fR in that
 326 \fBnvlist_xdup()\fR can use a different allocator.
 327 .sp
 328 .LP
 329 The \fBnvlist_merge()\fR function adds copies of all name-value pairs from
 330 \fBnvlist_t\fR \fInvl\fR to \fBnvlist_t dst\fR. Name-value pairs in dst are
 331 replaced with name-value pairs from \fBnvl\fR which have identical names (if
 332 dst has the type \fBNV_UNIQUE_NAME\fR), or identical names and types (if dst
 333 has the type \fBNV_UNIQUE_NAME_TYPE\fR).
 334 .sp
 335 .LP
 336 The \fBnvlist_lookup_nv_alloc()\fR function retrieves the pointer to the
 337 allocator used when manipulating a name-value pair list.
 338 .SS "PLUGGABLE ALLOCATORS"
 339 .LP
 340 Using Pluggable Allocators:
 341 .sp
 342 .LP
 343 The \fBnv_alloc_init()\fR, \fBnv_alloc_reset()\fR and \fBnv_alloc_fini()\fR
 344 functions provide an interface that specifies the allocator to be used when
 345 manipulating a name-value pair list.
 346 .sp
 347 .LP
 348 The \fBnv_alloc_init()\fR determines allocator properties and puts them into
 349 the \fInva\fR argument. You need to specify the \fInv_arg\fR argument, the
 350 \fInvo\fR argument and an optional variable argument list.  The optional
 351 arguments are passed to the (*\fBnv_ao_init()\fR) function.
 352 .sp
 353 .LP
 354 The \fInva\fR argument must be passed to \fBnvlist_xalloc()\fR,
 355 \fBnvlist_xpack()\fR, \fBnvlist_xunpack()\fR and \fBnvlist_xdup()\fR.
 356 .sp
 357 .LP
 358 The \fBnv_alloc_reset()\fR function resets the allocator properties to the data
 359 specified by \fBnv_alloc_init()\fR. When no (*\fBnv_ao_reset()\fR) function is
 360 specified, \fBnv_alloc_reset()\fR is without effect.
 361 .sp
 362 .LP
 363 The \fBnv_alloc_fini()\fR destroys the allocator properties determined by
 364 \fBnv_alloc_init()\fR. When a (*\fBnv_ao_fini()\fR) routine is specified, it is
 365 called from \fBnv_alloc_fini()\fR.
 366 .sp
 367 .LP
 368 The disposition of the allocated objects and the memory used to store them is
 369 left to the allocator implementation.
 370 .sp
 371 .LP
 372 The `nv_alloc_sleep' and `nv_alloc_nosleep' nv_alloc_t pointers may be used
 373 with nvlist_xalloc to mimic the behavior of nvlist_alloc with KM_SLEEP and
 374 KM_NOSLEEP, respectively.
 375 .sp
 376 .in +2
 377 .nf
 378 o  nv_alloc_nosleep
 379 o  nv_alloc_sleep
 380 .fi
 381 .in -2
 382
 383 .sp
 384 .LP
 385 The nvpair framework provides a fixed-buffer allocator, accessible via
 386 nv_fixed_ops.
 387 .sp
 388 .in +2
 389 .nf
 390 o  nv_fixed_ops
 391 .fi
 392 .in -2
 393
 394 .sp
 395 .LP
 396 Given a buffer size and address, the fixed-buffer allocator allows for the
 397 creation of nvlists in contexts where malloc or kmem_alloc services may not be
 398 available. The fixed-buffer allocator is designed primarily to support the
 399 creation of nvlists.
 400 .sp
 401 .LP
 402 Memory freed using \fBnvlist_free()\fR, pair-removal, or similar routines is
 403 not reclaimed.
 404 .sp
 405 .LP
 406 When used to initialize the fixed-buffer allocator, nv_alloc_init should be
 407 called as follows:
 408 .sp
 409 .in +2
 410 .nf
 411 int nv_alloc_init(nv_alloc_t *nva, const nv_alloc_ops_t *nvo,
 412     void *bufptr, size_t sz);
 413 .fi
 414 .in -2
 415
 416 .sp
 417 .LP
 418 When invoked on a fixed-buffer, the \fBnv_alloc_reset()\fR function resets the
 419 fixed buffer and prepares it for re-use. The framework consumer is responsible
 420 for freeing the buffer passed to \fBnv_alloc_init()\fR.
 421 .SS "CREATING PLUGGABLE ALLOCATORS"
 422 .LP
 423 Any producer of name-value pairs may possibily specify his own allocator
 424 routines. You must provide the following pluggable allocator operations in the
 425 allocator implementation.
 426 .sp
 427 .in +2
 428 .nf
 429 int (*nv_ao_init)(nv_alloc_t *nva, va_list nv_valist);
 430 void (*nv_ao_fini)(nv_alloc_t *nva);
 431 void *(*nv_ao_alloc)(nv_alloc_t *nva, size_t sz);
 432 void (*nv_ao_reset)(nv_alloc_t *nva);
 433 void (*nv_ao_free)(nv_alloc_t *nva, void *buf, size_t sz);
 434 .fi
 435 .in -2
 436
 437 .sp
 438 .LP
 439 The \fInva\fR argument of the allocator implementation is always the first
 440 argument.
 441 .sp
 442 .LP
 443 The optional (*\fBnv_ao_init()\fR ) function is responsible for filling the
 444 data specified by \fBnv_alloc_init()\fR into the \fBnva_arg()\fR argument.  The
 445 (*\fBnv_ao_init()\fR) function is called only when \fBnv_alloc_init()\fR is
 446 executed.
 447 .sp
 448 .LP
 449 The optional (*\fBnv_ao_fini()\fR) function is responsible for the cleanup of
 450 the allocator implementation. It is called by \fBnv_alloc_fini()\fR.
 451 .sp
 452 .LP
 453 The required (*\fBnv_ao_alloc()\fR) function is used in the nvpair allocation
 454 framework for memory allocation. The sz argument specifies the size of the
 455 requested buffer.
 456 .sp
 457 .LP
 458 The optional (*\fBnv_ao_reset()\fR) function is responsible for resetting the
 459 nva_arg argument to the data specified by \fBnv_alloc_init()\fR.
 460 .sp
 461 .LP
 462 The required (*\fBnv_ao_free()\fR) function is used in the nvpair allocator
 463 framework for memory de-allocation. The argument buf is a pointer to a block
 464 previously allocated by (*\fBnv_ao_alloc()\fR) function. The size argument sz
 465 must exactly match the original allocation.
 466 .sp
 467 .LP
 468 The disposition of the allocated objects and the memory used to store them is
 469 left to the allocator implementation.
 470 .SH RETURN VALUES
 471 .LP
 472 For \fBnvlist_alloc()\fR, \fBnvlist_dup()\fR, \fBnvlist_xalloc()\fR, and
 473 \fBnvlist_xdup()\fR:
 474 .sp
 475 .ne 2
 476 .na
 477 \fB\fB0\fR\fR
 478 .ad
 479 .RS 10n
 480 success
 481 .RE
 482
 483 .sp
 484 .ne 2
 485 .na
 486 \fB\fBEINVAL\fR\fR
 487 .ad
 488 .RS 10n
 489 invalid argument
 490 .RE
 491
 492 .sp
 493 .ne 2
 494 .na
 495 \fB\fBENOMEM\fR\fR
 496 .ad
 497 .RS 10n
 498 insufficient memory
 499 .RE
 500
 501 .sp
 502 .LP
 503 For \fBnvlist_pack()\fR, \fBnvlist_unpack()\fR, \fBnvlist_xpack()\fR, and
 504 \fBnvlist_xunpack()\fR:
 505 .sp
 506 .ne 2
 507 .na
 508 \fB\fB0\fR\fR
 509 .ad
 510 .RS 11n
 511 success
 512 .RE
 513
 514 .sp
 515 .ne 2
 516 .na
 517 \fB\fBEINVAL\fR\fR
 518 .ad
 519 .RS 11n
 520 invalid argument
 521 .RE
 522
 523 .sp
 524 .ne 2
 525 .na
 526 \fB\fBENOMEM\fR\fR
 527 .ad
 528 .RS 11n
 529 insufficient memory
 530 .RE
 531
 532 .sp
 533 .ne 2
 534 .na
 535 \fB\fBEFAULT\fR\fR
 536 .ad
 537 .RS 11n
 538 encode/decode error
 539 .RE
 540
 541 .sp
 542 .ne 2
 543 .na
 544 \fB\fBENOTSUP\fR\fR
 545 .ad
 546 .RS 11n
 547 encode/decode method not supported
 548 .RE
 549
 550 .sp
 551 .LP
 552 For \fBnvlist_size()\fR:
 553 .sp
 554 .ne 2
 555 .na
 556 \fB\fB0\fR\fR
 557 .ad
 558 .RS 10n
 559 success
 560 .RE
 561
 562 .sp
 563 .ne 2
 564 .na
 565 \fB\fBEINVAL\fR\fR
 566 .ad
 567 .RS 10n
 568 invalid argument
 569 .RE
 570
 571 .sp
 572 .LP
 573 For \fBnvlist_lookup_nv_alloc()\fR:
 574 .sp
 575 .LP
 576 pointer to the allocator
 577 .SH USAGE
 578 .LP
 579 The fixed-buffer allocator is very simple allocator. It uses a pre-allocated
 580 buffer for memory allocations and it can be used in interrupt context. You are
 581 responsible for allocation and de-allocation for the pre-allocated buffer.
 582 .SH EXAMPLES
 583 .in +2
 584 .nf
 585   /*
 586    * using the fixed-buffer allocator.
 587    */
 588    #include <sys/nvpair.h>
 589
 590   /* initialize the nvpair allocator framework */
 591   static nv_alloc_t *
 592   init(char *buf, size_t size)
 593   {
 594        nv_alloc_t *nvap;
 595
 596        if ((nvap = kmem_alloc(sizeof(nv_alloc_t), KM_SLEEP)) == NULL)
 597            return (NULL);
 598
 599        if (nv_alloc_init(nvap, nv_fixed_ops, buf, size) == 0)
 600            return (nvap);
 601
 602        return (NULL);
 603    }
 604
 605    static void
 606    fini(nv_alloc_t *nvap)
 607    {
 608          nv_alloc_fini(nvap);
 609          kmem_free(nvap, sizeof(nv_alloc_t));
 610    }
 611     static int
 612     interrupt_context(nv_alloc_t *nva)
 613     {
 614        nvlist_t *nvl;
 615        int error;
 616
 617        if ((error = nvlist_xalloc(&nvl, NV_UNIQUE_NAME, nva)) != 0)
 618             return (-1);
 619
 620        if ((error = nvlist_add_int32(nvl, "name", 1234)) == 0)
 621             error = send_nvl(nvl);
 622
 623        nvlist_free(nvl);
 624        return (error);
 625       }
 626 .fi
 627 .in -2
 628
 629 .SH CONTEXT
 630 .LP
 631 The \fBnvlist_alloc()\fR, \fBnvlist_pack()\fR, \fBnvlist_unpack()\fR, and
 632 \fBnvlist_dup()\fR functions can be called from interrupt context only if the
 633 \fBKM_NOSLEEP\fR flag is set. They can be called from user context with any
 634 valid flag.
 635 .sp
 636 .LP
 637 The \fBnvlist_xalloc()\fR, \fBnvlist_xpack()\fR, \fBnvlist_xunpack()\fR, and
 638 \fBnvlist_xdup()\fR functions can be called from interrupt context only if (1)
 639 the default allocator is used and the \fBKM_NOSLEEP\fR flag is set or (2) the
 640 specified allocator did not sleep for free memory (for example, it uses a
 641 pre-allocated buffer for memory allocations).
 642 .sp
 643 .LP
 644 These functions can be called from user or kernel context with any valid flag.