[src/trunk]: src/share/man/man9 document M_CANFAIL

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

details:   https://anonhg.NetBSD.org/src/rev/40d8bfda886d
branches:  trunk
changeset: 518720:40d8bfda886d
user:      jdolecek <jdolecek%NetBSD.org@localhost>
date:      Tue Dec 04 20:39:02 2001 +0000

description:
document M_CANFAIL

diffstat:

 share/man/man9/malloc.9 |  25 ++++++++++++++++++++-----
 1 files changed, 20 insertions(+), 5 deletions(-)

diffs (58 lines):

diff -r c93e93986fab -r 40d8bfda886d share/man/man9/malloc.9
--- a/share/man/man9/malloc.9   Tue Dec 04 20:13:19 2001 +0000
+++ b/share/man/man9/malloc.9   Tue Dec 04 20:39:02 2001 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: malloc.9,v 1.18 2001/11/18 23:00:10 wiz Exp $
+.\"    $NetBSD: malloc.9,v 1.19 2001/12/04 20:39:02 jdolecek Exp $
 .\"
 .\" Copyright (c) 1996 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -34,7 +34,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd November 17, 2001
+.Dd December 4, 2001
 .Dt MALLOC 9
 .Os
 .Sh NAME
@@ -81,9 +81,9 @@
 The
 .Fa flags
 argument further qualifies
-.Fn malloc No Ns 's
+.Fn malloc
 operational characteristics as follows:
-.Bl -tag -offset indent -width M_NOWAIT
+.Bl -tag -offset indent -width M_CANFAIL
 .It Dv M_NOWAIT
 Causes
 .Fn malloc
@@ -105,11 +105,26 @@
 flag represents this behaviour.
 Note that
 .Dv M_WAITOK
-is conveniently defined to be 0, and hence maybe or'ed into the
+is conveniently defined to be 0, and hence may be or'ed into the
 .Fa flags
 argument to indicate that it's Ok to wait for resources.
 .It Dv M_ZERO
 Causes the allocated memory to be set to all zeros.
+.It Dv M_CANFAIL
+Changes behaviour for
+.Dv M_WAITOK
+case - if the requested memory size is bigger than
+.Fn malloc
+can ever allocate, return failure, rather than calling
+.Xr panic 9 . This is different to M_NOWAIT, since
+the call can still wait for resources.
+.Pp
+Rather than depending on
+.Dv M_CANFAIL ,
+kernel code should do proper bound checking itself. This
+flag should only be used in cases where this is not feasible.
+Since it can hide real kernel bugs, it's usage is
+.Em strongly discouraged .
 .El
 .Pp
 The