patch more-manpage
patch cleanup

   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 "Jan 16, 2006"
   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 .sp
 108 .LP
 109 Solaris DDI specific (Solaris DDI)
 110 .SH PARAMETERS
 111 .sp
 112 .ne 2
 113 .na
 114 \fB\fInvlp\fR\fR
 115 .ad
 116 .RS 12n
 117 Address of a pointer to list of name-value pairs (\fBnvlist_t\fR).
 118 .RE
 119 
 120 .sp
 121 .ne 2
 122 .na
 123 \fB\fInvflag\fR\fR
 124 .ad
 125 .RS 12n
 126 Specify bit fields defining \fBnvlist_t\fR properties:
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fBNV_UNIQUE_NAME\fR\fR
 131 .ad
 132 .RS 23n
 133 \fBnvpair\fR names are unique.
 134 .RE
 135 
 136 .sp
 137 .ne 2
 138 .na
 139 \fB\fBNV_UNIQUE_NAME_TYPE\fR\fR
 140 .ad
 141 .RS 23n
 142 Name-data type combination is unique
 143 .RE
 144 
 145 .RE
 146 
 147 .sp
 148 .ne 2
 149 .na
 150 \fB\fIkmflag\fR\fR
 151 .ad
 152 .RS 12n
 153 Kernel memory allocation policy, either \fBKM_SLEEP\fR or \fBKM_NOSLEEP\fR.
 154 .RE
 155 
 156 .sp
 157 .ne 2
 158 .na
 159 \fB\fInvl\fR\fR
 160 .ad
 161 .RS 12n
 162 \fBnvlist_t\fR to be processed.
 163 .RE
 164 
 165 .sp
 166 .ne 2
 167 .na
 168 \fB\fIdst\fR\fR
 169 .ad
 170 .RS 12n
 171 Destination \fBnvlist_t\fR.
 172 .RE
 173 
 174 .sp
 175 .ne 2
 176 .na
 177 \fB\fIsize\fR\fR
 178 .ad
 179 .RS 12n
 180 Pointer to buffer to contain the encoded size.
 181 .RE
 182 
 183 .sp
 184 .ne 2
 185 .na
 186 \fB\fIbufp\fR\fR
 187 .ad
 188 .RS 12n
 189 Address of buffer to pack \fBnvlist\fR into. Must be 8-byte aligned. If NULL,
 190 library will allocate memory.
 191 .RE
 192 
 193 .sp
 194 .ne 2
 195 .na
 196 \fB\fIbuf\fR\fR
 197 .ad
 198 .RS 12n
 199 Buffer containing packed \fBnvlist_t\fR.
 200 .RE
 201 
 202 .sp
 203 .ne 2
 204 .na
 205 \fB\fIbuflen\fR\fR
 206 .ad
 207 .RS 12n
 208 Size of buffer \fIbufp\fR or \fIbuf\fR points to.
 209 .RE
 210 
 211 .sp
 212 .ne 2
 213 .na
 214 \fB\fIencoding\fR\fR
 215 .ad
 216 .RS 12n
 217 Encoding method for packing.
 218 .RE
 219 
 220 .sp
 221 .ne 2
 222 .na
 223 \fB\fInvo\fR\fR
 224 .ad
 225 .RS 12n
 226 Pluggable allocator operations pointer (nv_alloc_ops_t).
 227 .RE
 228 
 229 .sp
 230 .ne 2
 231 .na
 232 \fB\fInva\fR\fR
 233 .ad
 234 .RS 12n
 235 Points to a nv_alloc_t structure to be used for the specified \fBnvlist_t\fR.
 236 .RE
 237 
 238 .SH DESCRIPTION
 239 .sp
 240 .LP
 241 List Manipulation:
 242 .sp
 243 .LP
 244 The \fBnvlist_alloc()\fR function allocates a new name-value pair list and
 245 updates \fInvlp\fR to point to the handle. The argument \fInvflag\fR specifies
 246 \fBnvlist_t\fR properties to remain persistent across packing, unpacking, and
 247 duplication.
 248 .sp
 249 .LP
 250 If \fBNV_UNIQUE_NAME\fR is specified for nvflag, existing nvpairs with matching
 251 names are removed before the new nvpair is added. If \fBNV_UNIQUE_NAME_TYPE\fR
 252 is specified for nvflag, existing nvpairs with matching names and data types
 253 are removed before the new nvpair is added. See \fBnvlist_add_byte\fR(9F) for
 254 more details.
 255 .sp
 256 .LP
 257 The \fBnvlist_xalloc()\fR function differs from \fBnvlist_alloc()\fR in that
 258 \fBnvlist_xalloc()\fR can use a different allocator, as described in the
 259 Pluggable Allocators section.
 260 .sp
 261 .LP
 262 The \fBnvlist_free()\fR function frees a name-value pair list.

 263 .sp
 264 .LP
 265 The \fBnvlist_size()\fR function returns the minimum size of a contiguous
 266 buffer large enough to pack \fInvl\fR. The \fIencoding\fR parameter specifies
 267 the method of encoding when packing \fInvl\fR. Supported encoding methods are:
 268 .sp
 269 .ne 2
 270 .na
 271 \fB\fBNV_ENCODE_NATIVE\fR\fR
 272 .ad
 273 .RS 20n
 274 Straight \fBbcopy()\fR as described in \fBbcopy\fR(9F).
 275 .RE
 276 
 277 .sp
 278 .ne 2
 279 .na
 280 \fB\fBNV_ENCODE_XDR\fR\fR
 281 .ad
 282 .RS 20n
 283 Use XDR encoding, suitable for sending to another host.
 284 .RE
 285 
 286 .sp
 287 .LP
 288 The \fBnvlist_pack()\fR function packs \fInvl\fR into contiguous memory
 289 starting at *\fIbufp\fR. The \fIencoding\fR parameter specifies the method of
 290 encoding (see above).
 291 .RS +4
 292 .TP
 293 .ie t \(bu
 294 .el o
 295 If *\fIbufp\fR is not NULL, *\fIbufp\fR is expected to be a caller-allocated
 296 buffer of size *\fIbuflen\fR. The \fIkmflag\fR argument is ignored.
 297 .RE
 298 .RS +4
 299 .TP
 300 .ie t \(bu
 301 .el o
 302 If *\fIbufp\fR is NULL, the library allocates memory and updates *\fIbufp\fR to
 303 point to the memory and updates *\fIbuflen\fR to contain the size of the
 304 allocated memory. The value of \fIkmflag\fR indicates the memory allocation
 305 policy
 306 .RE
 307 .sp
 308 .LP
 309 The \fBnvlist_xpack()\fR function differs from \fBnvlist_pack()\fR in that
 310 \fBnvlist_xpack()\fR can use a different allocator.
 311 .sp
 312 .LP
 313 The \fBnvlist_unpack()\fR function takes a buffer with a packed \fBnvlist_t\fR
 314 and unpacks it into a searchable \fBnvlist_t\fR. The library allocates memory
 315 for \fBnvlist_t\fR. The caller is responsible for freeing the memory by calling
 316 \fBnvlist_free()\fR.
 317 .sp
 318 .LP
 319 The \fBnvlist_xunpack()\fR function differs from \fBnvlist_unpack()\fR in that
 320 \fBnvlist_xunpack()\fR can use a different allocator.
 321 .sp
 322 .LP
 323 The \fBnvlist_dup()\fR function makes a copy of \fInvl\fR and updates
 324 \fInvlp\fR to point to the copy.
 325 .sp
 326 .LP
 327 The \fBnvlist_xdup()\fR function differs from \fBnvlist_dup()\fR in that
 328 \fBnvlist_xdup()\fR can use a different allocator.
 329 .sp
 330 .LP
 331 The \fBnvlist_merge()\fR function adds copies of all name-value pairs from
 332 \fBnvlist_t\fR \fInvl\fR to \fBnvlist_t dst\fR. Name-value pairs in dst are
 333 replaced with name-value pairs from \fBnvl\fR which have identical names (if
 334 dst has the type \fBNV_UNIQUE_NAME\fR), or identical names and types (if dst
 335 has the type \fBNV_UNIQUE_NAME_TYPE\fR).
 336 .sp
 337 .LP
 338 The \fBnvlist_lookup_nv_alloc()\fR function retrieves the pointer to the
 339 allocator used when manipulating a name-value pair list.
 340 .SS "PLUGGABLE ALLOCATORS"
 341 .sp
 342 .LP
 343 Using Pluggable Allocators:
 344 .sp
 345 .LP
 346 The \fBnv_alloc_init()\fR, \fBnv_alloc_reset()\fR and \fBnv_alloc_fini()\fR
 347 functions provide an interface that specifies the allocator to be used when
 348 manipulating a name-value pair list.
 349 .sp
 350 .LP
 351 The \fBnv_alloc_init()\fR determines allocator properties and puts them into
 352 the \fInva\fR argument. You need to specify the \fInv_arg\fR argument, the
 353 \fInvo\fR argument and an optional variable argument list.  The optional
 354 arguments are passed to the (*\fBnv_ao_init()\fR) function.
 355 .sp
 356 .LP
 357 The \fInva\fR argument must be passed to \fBnvlist_xalloc()\fR,
 358 \fBnvlist_xpack()\fR, \fBnvlist_xunpack()\fR and \fBnvlist_xdup()\fR.
 359 .sp
 360 .LP
 361 The \fBnv_alloc_reset()\fR function resets the allocator properties to the data
 362 specified by \fBnv_alloc_init()\fR. When no (*\fBnv_ao_reset()\fR) function is
 363 specified, \fBnv_alloc_reset()\fR is without effect.
 364 .sp
 365 .LP
 366 The \fBnv_alloc_fini()\fR destroys the allocator properties determined by
 367 \fBnv_alloc_init()\fR. When a (*\fBnv_ao_fini()\fR) routine is specified, it is
 368 called from \fBnv_alloc_fini()\fR.
 369 .sp
 370 .LP
 371 The disposition of the allocated objects and the memory used to store them is
 372 left to the allocator implementation.
 373 .sp
 374 .LP
 375 The `nv_alloc_sleep' and `nv_alloc_nosleep' nv_alloc_t pointers may be used
 376 with nvlist_xalloc to mimic the behavior of nvlist_alloc with KM_SLEEP and
 377 KM_NOSLEEP, respectively.
 378 .sp
 379 .in +2
 380 .nf
 381 o  nv_alloc_nosleep
 382 o  nv_alloc_sleep
 383 .fi
 384 .in -2
 385 
 386 .sp
 387 .LP
 388 The nvpair framework provides a fixed-buffer allocator, accessible via
 389 nv_fixed_ops.
 390 .sp
 391 .in +2
 392 .nf
 393 o  nv_fixed_ops
 394 .fi
 395 .in -2
 396 
 397 .sp
 398 .LP
 399 Given a buffer size and address, the fixed-buffer allocator allows for the
 400 creation of nvlists in contexts where malloc or kmem_alloc services may not be
 401 available. The fixed-buffer allocator is designed primarily to support the
 402 creation of nvlists.
 403 .sp
 404 .LP
 405 Memory freed using \fBnvlist_free()\fR, pair-removal, or similar routines is
 406 not reclaimed.
 407 .sp
 408 .LP
 409 When used to initialize the fixed-buffer allocator, nv_alloc_init should be
 410 called as follows:
 411 .sp
 412 .in +2
 413 .nf
 414 int nv_alloc_init(nv_alloc_t *nva, const nv_alloc_ops_t *nvo,
 415     void *bufptr, size_t sz);
 416 .fi
 417 .in -2
 418 
 419 .sp
 420 .LP
 421 When invoked on a fixed-buffer, the \fBnv_alloc_reset()\fR function resets the
 422 fixed buffer and prepares it for re-use. The framework consumer is responsible
 423 for freeing the buffer passed to \fBnv_alloc_init()\fR.
 424 .SS "CREATING PLUGGABLE ALLOCATORS"
 425 .sp
 426 .LP
 427 Any producer of name-value pairs may possibily specify his own allocator
 428 routines. You must provide the following pluggable allocator operations in the
 429 allocator implementation.
 430 .sp
 431 .in +2
 432 .nf
 433 int (*nv_ao_init)(nv_alloc_t *nva, va_list nv_valist);
 434 void (*nv_ao_fini)(nv_alloc_t *nva);
 435 void *(*nv_ao_alloc)(nv_alloc_t *nva, size_t sz);
 436 void (*nv_ao_reset)(nv_alloc_t *nva);
 437 void (*nv_ao_free)(nv_alloc_t *nva, void *buf, size_t sz);
 438 .fi
 439 .in -2
 440 
 441 .sp
 442 .LP
 443 The \fInva\fR argument of the allocator implementation is always the first
 444 argument.
 445 .sp
 446 .LP
 447 The optional (*\fBnv_ao_init()\fR ) function is responsible for filling the
 448 data specified by \fBnv_alloc_init()\fR into the \fBnva_arg()\fR argument.  The
 449 (*\fBnv_ao_init()\fR) function is called only when \fBnv_alloc_init()\fR is
 450 executed.
 451 .sp
 452 .LP
 453 The optional (*\fBnv_ao_fini()\fR) function is responsible for the cleanup of
 454 the allocator implementation. It is called by \fBnv_alloc_fini()\fR.
 455 .sp
 456 .LP
 457 The required (*\fBnv_ao_alloc()\fR) function is used in the nvpair allocation
 458 framework for memory allocation. The sz argument specifies the size of the
 459 requested buffer.
 460 .sp
 461 .LP
 462 The optional (*\fBnv_ao_reset()\fR) function is responsible for resetting the
 463 nva_arg argument to the data specified by \fBnv_alloc_init()\fR.
 464 .sp
 465 .LP
 466 The required (*\fBnv_ao_free()\fR) function is used in the nvpair allocator
 467 framework for memory de-allocation. The argument buf is a pointer to a block
 468 previously allocated by (*\fBnv_ao_alloc()\fR) function. The size argument sz
 469 must exactly match the original allocation.
 470 .sp
 471 .LP
 472 The disposition of the allocated objects and the memory used to store them is
 473 left to the allocator implementation.
 474 .SH RETURN VALUES
 475 .sp
 476 .LP
 477 For \fBnvlist_alloc()\fR, \fBnvlist_dup()\fR, \fBnvlist_xalloc()\fR, and
 478 \fBnvlist_xdup()\fR:
 479 .sp
 480 .ne 2
 481 .na
 482 \fB\fB0\fR\fR
 483 .ad
 484 .RS 10n
 485 success
 486 .RE
 487 
 488 .sp
 489 .ne 2
 490 .na
 491 \fB\fBEINVAL\fR\fR
 492 .ad
 493 .RS 10n
 494 invalid argument
 495 .RE
 496 
 497 .sp
 498 .ne 2
 499 .na
 500 \fB\fBENOMEM\fR\fR
 501 .ad
 502 .RS 10n
 503 insufficient memory
 504 .RE
 505 
 506 .sp
 507 .LP
 508 For \fBnvlist_pack()\fR, \fBnvlist_unpack()\fR, \fBnvlist_xpack()\fR, and
 509 \fBnvlist_xunpack()\fR:
 510 .sp
 511 .ne 2
 512 .na
 513 \fB\fB0\fR\fR
 514 .ad
 515 .RS 11n
 516 success
 517 .RE
 518 
 519 .sp
 520 .ne 2
 521 .na
 522 \fB\fBEINVAL\fR\fR
 523 .ad
 524 .RS 11n
 525 invalid argument
 526 .RE
 527 
 528 .sp
 529 .ne 2
 530 .na
 531 \fB\fBENOMEM\fR\fR
 532 .ad
 533 .RS 11n
 534 insufficient memory
 535 .RE
 536 
 537 .sp
 538 .ne 2
 539 .na
 540 \fB\fBEFAULT\fR\fR
 541 .ad
 542 .RS 11n
 543 encode/decode error
 544 .RE
 545 
 546 .sp
 547 .ne 2
 548 .na
 549 \fB\fBENOTSUP\fR\fR
 550 .ad
 551 .RS 11n
 552 encode/decode method not supported
 553 .RE
 554 
 555 .sp
 556 .LP
 557 For \fBnvlist_size()\fR:
 558 .sp
 559 .ne 2
 560 .na
 561 \fB\fB0\fR\fR
 562 .ad
 563 .RS 10n
 564 success
 565 .RE
 566 
 567 .sp
 568 .ne 2
 569 .na
 570 \fB\fBEINVAL\fR\fR
 571 .ad
 572 .RS 10n
 573 invalid argument
 574 .RE
 575 
 576 .sp
 577 .LP
 578 For \fBnvlist_lookup_nv_alloc()\fR:
 579 .sp
 580 .LP
 581 pointer to the allocator
 582 .SH USAGE
 583 .sp
 584 .LP
 585 The fixed-buffer allocator is very simple allocator. It uses a pre-allocated
 586 buffer for memory allocations and it can be used in interrupt context. You are
 587 responsible for allocation and de-allocation for the pre-allocated buffer.
 588 .SH EXAMPLES
 589 .sp
 590 .in +2
 591 .nf
 592   /*
 593    * using the fixed-buffer allocator.
 594    */
 595    #include <sys/nvpair.h>
 596 
 597   /* initialize the nvpair allocator framework */
 598   static nv_alloc_t *
 599   init(char *buf, size_t size)
 600   {
 601        nv_alloc_t *nvap;
 602 
 603        if ((nvap = kmem_alloc(sizeof(nv_alloc_t), KM_SLEEP)) == NULL)
 604            return (NULL);
 605 
 606        if (nv_alloc_init(nvap, nv_fixed_ops, buf, size) == 0)
 607            return (nvap);
 608 
 609        return (NULL);
 610    }
 611 
 612    static void
 613    fini(nv_alloc_t *nvap)
 614    {
 615          nv_alloc_fini(nvap);
 616          kmem_free(nvap, sizeof(nv_alloc_t));
 617    }
 618     static int
 619     interrupt_context(nv_alloc_t *nva)
 620     {
 621        nvlist_t *nvl;
 622        int error;
 623 
 624        if ((error = nvlist_xalloc(&nvl, NV_UNIQUE_NAME, nva)) != 0)
 625             return (-1);
 626 
 627        if ((error = nvlist_add_int32(nvl, "name", 1234)) == 0)
 628             error = send_nvl(nvl);
 629 
 630        nvlist_free(nvl);
 631        return (error);
 632       }
 633 .fi
 634 .in -2
 635 
 636 .SH CONTEXT
 637 .sp
 638 .LP
 639 The \fBnvlist_alloc()\fR, \fBnvlist_pack()\fR, \fBnvlist_unpack()\fR, and
 640 \fBnvlist_dup()\fR functions can be called from interrupt context only if the
 641 \fBKM_NOSLEEP\fR flag is set. They can be called from user context with any
 642 valid flag.
 643 .sp
 644 .LP
 645 The \fBnvlist_xalloc()\fR, \fBnvlist_xpack()\fR, \fBnvlist_xunpack()\fR, and
 646 \fBnvlist_xdup()\fR functions can be called from interrupt context only if (1)
 647 the default allocator is used and the \fBKM_NOSLEEP\fR flag is set or (2) the
 648 specified allocator did not sleep for free memory (for example, it uses a
 649 pre-allocated buffer for memory allocations).
 650 .sp
 651 .LP
 652 These functions can be called from user or kernel context with any valid flag.
--- EOF ---