[src/trunk]: src/share/man/man9 Spell out that KM_SLEEP allocations can fail.

[christos <christos%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/45c1f39bf207
branches:  trunk
changeset: 342178:45c1f39bf207
user:      christos <christos%NetBSD.org@localhost>
date:      Fri Dec 11 04:11:23 2015 +0000

description:
Spell out that KM_SLEEP allocations can fail.

diffstat:

 share/man/man9/kmem.9 |  20 ++++++++++++++++++--
 1 files changed, 18 insertions(+), 2 deletions(-)

diffs (55 lines):

diff -r 1d8d9a25cc47 -r 45c1f39bf207 share/man/man9/kmem.9
--- a/share/man/man9/kmem.9     Fri Dec 11 04:05:54 2015 +0000
+++ b/share/man/man9/kmem.9     Fri Dec 11 04:11:23 2015 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: kmem.9,v 1.17 2015/07/28 09:52:43 wiz Exp $
+.\"    $NetBSD: kmem.9,v 1.18 2015/12/11 04:11:23 christos Exp $
 .\"
 .\" Copyright (c)2006 YAMAMOTO Takashi,
 .\" All rights reserved.
@@ -25,7 +25,7 @@
 .\" SUCH DAMAGE.
 .\"
 .\" ------------------------------------------------------------
-.Dd July 28, 2015
+.Dd December 10, 2015
 .Dt KMEM 9
 .Os
 .\" ------------------------------------------------------------
@@ -77,6 +77,15 @@
 .It Dv KM_SLEEP
 If the allocation cannot be satisfied immediately, sleep until enough
 memory is available.
+Note that this does not mean that if
+.Dv KM_SLEEP 
+is specified, then the allocation cannot fail.
+Under resource stress conditions, the allocation can fail and the
+function will return
+.Dv NULL .
+One such scenario is when the allocation size is larger than it can ever
+be allocated; another is when the system memory resources are exhausted
+to even allocate pools of pages.
 .It Dv KM_NOSLEEP
 Don't sleep.
 Immediately return
@@ -134,6 +143,9 @@
 .Fn kmem_alloc
 or
 .Fn kmem_zalloc .
+One such scenario is when the allocation size is larger than it can ever
+be allocated; another is when the system memory resources are exhausted
+to even allocate pools of pages.
 .It Fa size
 The size of the memory being freed, in bytes.
 It must be the same as the
@@ -173,6 +185,10 @@
 .Fn kmem_free
 may also block.
 .Pp
+Always check the return value of the allocators, even when
+.Dv KM_SLEEP
+is specified to avoid kernel crashes during resource stress conditions.
+.Pp
 For some locks this is permissible or even unavoidable.
 For others, particularly locks that may be taken from soft interrupt context,
 it is a serious problem.