diff options
Diffstat (limited to 'usr/src/man/man3malloc')
| -rw-r--r-- | usr/src/man/man3malloc/Makefile | 5 | ||||
| -rw-r--r-- | usr/src/man/man3malloc/umem_debug.3malloc | 16 | ||||
| -rw-r--r-- | usr/src/man/man3malloc/umem_setmtbf.3malloc | 74 |
3 files changed, 86 insertions, 9 deletions
diff --git a/usr/src/man/man3malloc/Makefile b/usr/src/man/man3malloc/Makefile index d39f180742..d7f3718e81 100644 --- a/usr/src/man/man3malloc/Makefile +++ b/usr/src/man/man3malloc/Makefile @@ -16,15 +16,16 @@ include $(SRC)/Makefile.master -MANSECT= 3malloc +MANSECT= 3malloc -MANFILES= bsdmalloc.3malloc \ +MANFILES= bsdmalloc.3malloc \ malloc.3malloc \ mapmalloc.3malloc \ mtmalloc.3malloc \ umem_alloc.3malloc \ umem_cache_create.3malloc \ umem_debug.3malloc \ + umem_setmtbf.3malloc \ watchmalloc.3malloc MANLINKS= calloc.3malloc \ diff --git a/usr/src/man/man3malloc/umem_debug.3malloc b/usr/src/man/man3malloc/umem_debug.3malloc index 89fda62a80..411d15e6f0 100644 --- a/usr/src/man/man3malloc/umem_debug.3malloc +++ b/usr/src/man/man3malloc/umem_debug.3malloc @@ -7,14 +7,12 @@ .SH NAME umem_debug \- debugging features of the umem library .SH SYNOPSIS -.LP .nf \fBcc\fR [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lumem\fR [ \fIlibrary\fR\&.\|.\|. ] #include <\fBumem.h\fR> .fi .SH DESCRIPTION -.LP The \fBlibumem\fR library provides debugging features that detect memory leaks, buffer overruns, multiple frees, use of uninitialized data, use of freed data, and many other common programming errors. The activation of the run-time @@ -24,6 +22,13 @@ debugging features is controlled by environment variables. When the library detects an error, it writes a description of the error to an internal buffer that is readable with the \fB::umem_status\fR \fBmdb\fR(1) \fIdcmd\fR and then calls \fBabort\fR(3C). +.sp +.LP +When using the debugging features of the library, a program may opt into +changing the failure rate of memory allocation. This is often useful for +test code that would like to force memory allocation failures in a +controlled fashion. See the \fBumem_setmtbf\fR(3MALLOC) function for +more information. .SH ENVIRONMENT VARIABLES .ne 2 .na @@ -166,7 +171,6 @@ cannot be allocated. .RE .SH ATTRIBUTES -.LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp @@ -183,9 +187,9 @@ MT-Level MT-Safe .TE .SH SEE ALSO -.LP \fBmdb\fR(1), \fBabort\fR(3C), \fBsignal\fR(3C), -\fBumem_cache_create\fR(3MALLOC), \fBattributes\fR(5) +\fBumem_cache_create\fR(3MALLOC), \fBumem_setmtbf\fR(3MALLOC), +\fBattributes\fR(5) .sp .LP \fIModular Debugger Guide\fR: @@ -193,12 +197,10 @@ MT-Level MT-Safe .LP https://illumos.org/books/mdb/ .SH WARNINGS -.LP When \fBlibumem\fR aborts the process using \fBabort\fR(3C), any existing signal handler for \fBSIGABRT\fR is called. If the signal handler performs allocations, undefined behavior can result. .SH NOTES -.LP Some of the debugging features work only for allocations smaller than 16 kilobytes in size. Allocations larger than 16 kilobytes could have reduced support. diff --git a/usr/src/man/man3malloc/umem_setmtbf.3malloc b/usr/src/man/man3malloc/umem_setmtbf.3malloc new file mode 100644 index 0000000000..5e2a8bb7db --- /dev/null +++ b/usr/src/man/man3malloc/umem_setmtbf.3malloc @@ -0,0 +1,74 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2020 Robert Mustacchi +.\" +.Dd February 23, 2020 +.Dt UMEM_SETMTBF 3MALLOC +.Os +.Sh NAME +.Nm umem_setmtbf +.Nd set umem failure threshold +.Sh SYNOPSIS +.Lb libumem +.In umem.h +.Ft void +.Fo umem_setmtbf +.Fa "uint_t thresh" +.Fc +.Sh DESCRIPTION +The +.Fn umem_setmtbf +function can be used to modify the run-time behavior of the +.Xr libumem 3LIB +library to set a threshold to cause injected memory allocation failures. +.Pp +By default, no failures are injected. +When a non-zero value is passed in +.Fa thresh +then error injection is enabled, if the umem debugging features +described in +.Xr umem_debug 3MALLOC +are enabled through the +.Ev UMEM_DEBUG +environment variable. +If a process has not enabled the debugging functionality of +.Xr libumem 3LIB +then no errors will be injected, no matter what +.Fa thresh +is set to. +.Pp +Passing the value +.Sy 0 +disables error injection. +To cause every allocation to fail, pass the value +.Sy 1 . +The larger the value passed, the more time that will pass between error +injections. +Currently, an error is injected if the current time in nanoseconds since +boot modulus the mtbf is zero. +Concretely: +.Bd -literal -offset indent +if (gethrtime() % thresh) == 0) { + <inject error> +} +.Ed +.Pp +This mechanism is not guaranteed over time; however, the meanings of a +threshold of zero, one, and the general tendency of larger numbers to +indicate less errors is. +.Sh MT-LEVEL +.Sy Unsafe +.Sh INTERFACE STABILITY +.Sy Uncommitted +.Sh SEE ALSO +.Xr libumem 3LIB , +.Xr umem_debug 3MALLOC |