12359 Want a means to set the umem mtbf at runtine

Reviewed by: John Levon <john.levon@joyent.com>
Reviewed by: Yuri Pankov <ypankov@fastmail.com>
Approved by: Dan McDonald <danmcd@joyent.com>

9 files changed, 110 insertions, 30 deletions

diff --git a/usr/src/cmd/mandoc/lib.in b/usr/src/cmd/mandoc/lib.in
index 79f249fb5f..0d65eeb086 100644
--- a/usr/src/cmd/mandoc/lib.in
+++ b/usr/src/cmd/mandoc/lib.in
@@ -76,6 +76,7 @@ LINE("libsysevet",	"System Event Inteface Library (libsysevent, \\-lsysevent)")
 LINE("libtecla",	"Interactive Command Line Input Library (libtecla, \\-ltecla)")
 LINE("libtnfctl",	"TNF Probe Control Library (libtnfctl, \\-ltnfctl)")
 LINE("libtsol",		"Trusted Extensions Library (libtsol, \\-ltsol)")
+LINE("libumem",		"Object-Caching Memory Allocation Library (libumem, \\-lumem")
 LINE("libuuid",		"UUID Library (libuuid, \\-luuid)")
 LINE("libvolmgt",	"Volume Management Library (libvolmgt, \\-lvolmgt)")
 LINE("libxcurses",	"X/Open Curses Library (libxcurses, \\-lxcurses)")
diff --git a/usr/src/lib/libumem/common/mapfile-vers b/usr/src/lib/libumem/common/mapfile-vers
index e95e666885..c2cdadf993 100644
--- a/usr/src/lib/libumem/common/mapfile-vers
+++ b/usr/src/lib/libumem/common/mapfile-vers
@@ -49,6 +49,10 @@ LOAD_SEGMENT umem {
 };
 $endif
 
+SYMBOL_VERSION ILLUMOS_0.1 {
+    global:
+	umem_setmtbf;
+} SUNW_1.1;
 
 SYMBOL_VERSION SUNW_1.1 {
     global:
diff --git a/usr/src/lib/libumem/common/umem.c b/usr/src/lib/libumem/common/umem.c
index 7f31529852..598a45eb39 100644
--- a/usr/src/lib/libumem/common/umem.c
+++ b/usr/src/lib/libumem/common/umem.c
@@ -395,8 +395,8 @@
  * umem_t that looks like:
  *
  * typedef struct {
- * 	size_t	tm_size;
- * 	void	*tm_roots[NTMEMBASE];  (Currently 16)
+ *	size_t	tm_size;
+ *	void	*tm_roots[NTMEMBASE];  (Currently 16)
  * } tmem_t;
  *
  * Each of the roots is treated as the head of a linked list. Each entry in the
@@ -560,10 +560,10 @@
  *
  *	o. _tmem_get_base(void)
  *
- * 	Returns the offset from the ulwp_t (curthread) to the tmem_t structure.
- * 	This is a constant for all threads and is effectively a way to to do
- * 	::offsetof ulwp_t ul_tmem without having to know the specifics of the
- * 	structure outside of libc.
+ *	Returns the offset from the ulwp_t (curthread) to the tmem_t structure.
+ *	This is a constant for all threads and is effectively a way to to do
+ *	::offsetof ulwp_t ul_tmem without having to know the specifics of the
+ *	structure outside of libc.
  *
  *	o. _tmem_get_nentries(void)
  *
@@ -3560,3 +3560,9 @@ fail:
 	(void) mutex_unlock(&umem_init_lock);
 	return (0);
 }
+
+void
+umem_setmtbf(uint32_t mtbf)
+{
+	umem_mtbf = mtbf;
+}
diff --git a/usr/src/lib/libumem/common/umem.h b/usr/src/lib/libumem/common/umem.h
index f8dc475297..62297be431 100644
--- a/usr/src/lib/libumem/common/umem.h
+++ b/usr/src/lib/libumem/common/umem.h
@@ -27,8 +27,6 @@
 #ifndef _UMEM_H
 #define	_UMEM_H
 
-#pragma ident	"%Z%%M%	%I%	%E% SMI"
-
 #include <sys/types.h>
 #include <sys/vmem.h>
 #include <stdlib.h>
@@ -79,6 +77,8 @@ extern void umem_cache_free(umem_cache_t *, void *);
 
 extern void umem_reap(void);
 
+extern void umem_setmtbf(uint32_t);
+
 #ifdef	__cplusplus
 }
 #endif
diff --git a/usr/src/man/man3lib/libumem.3lib b/usr/src/man/man3lib/libumem.3lib
index 70df5a790d..a4cbd6ebbf 100644
--- a/usr/src/man/man3lib/libumem.3lib
+++ b/usr/src/man/man3lib/libumem.3lib
@@ -3,19 +3,16 @@
 .\" 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.
 .\" 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.
 .\" 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]
-.TH LIBUMEM 3LIB "May 22, 2003"
+.TH LIBUMEM 3LIB "February 23, 2020"
 .SH NAME
 libumem \- object-caching memory allocation library
 .SH SYNOPSIS
-.LP
 .nf
 cc [ \fIflag\fR... ] \fIfile\fR... \fB-lumem\fR [ \fIlibrary\fR... ]
 #include <\fBumem.h\fR>
 .fi
 
 .SH DESCRIPTION
-.sp
-.LP
 Functions in this library provide fast, scalable object-caching memory
 allocation with multithreaded application support. In addition to the standard
 \fBmalloc\fR(3C) family of functions and the more flexible
@@ -28,8 +25,6 @@ detection of memory leaks, buffer overruns, multiple frees, use of
 uninitialized data, use of freed data, and many other common programming
 errors. See \fBumem_debug\fR(3MALLOC).
 .SH INTERFACES
-.sp
-.LP
 The shared object \fBlibumem.so.1\fR provides the public interfaces defined
 below. See \fBIntro\fR(3) for additional information on shared object
 interfaces.
@@ -45,11 +40,11 @@ l l .
 \fBumem_cache_alloc\fR	\fBumem_cache_create\fR
 \fBumem_cache_destroy\fR	\fBumem_cache_free\fR
 \fBumem_free\fR	\fBumem_nofail_callback\fR
-\fBumem_zalloc\fR	\fBvalloc\fR
+\fBumem_setmtbf\fR	\fBumem_zalloc\fR
+\fBvalloc\fR
 .TE
 
 .SH FILES
-.sp
 .ne 2
 .na
 \fB\fB/usr/lib/libumem.so.1\fR\fR
@@ -68,8 +63,6 @@ shared object
 .RE
 
 .SH ATTRIBUTES
-.sp
-.LP
 See \fBattributes\fR(5) for descriptions of the following attributes:
 .sp
 
@@ -86,8 +79,6 @@ MT-Level	MT-Safe
 .TE
 
 .SH SEE ALSO
-.sp
-.LP
 \fBIntro\fR(3), \fBmalloc\fR(3C), \fBumem_alloc\fR(3MALLOC),
 \fBumem_cache_create\fR(3MALLOC), \fBumem_debug\fR(3MALLOC),
-\fBattributes\fR(5)
+\fBumem_setmtbf\fR(3MALLOC), \fBattributes\fR(5)
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
diff --git a/usr/src/pkg/manifests/system-library.man3malloc.inc b/usr/src/pkg/manifests/system-library.man3malloc.inc
index 7ef761c79a..94f4e1b49d 100644
--- a/usr/src/pkg/manifests/system-library.man3malloc.inc
+++ b/usr/src/pkg/manifests/system-library.man3malloc.inc
@@ -21,6 +21,7 @@ file path=usr/share/man/man3malloc/mtmalloc.3malloc
 file path=usr/share/man/man3malloc/umem_alloc.3malloc
 file path=usr/share/man/man3malloc/umem_cache_create.3malloc
 file path=usr/share/man/man3malloc/umem_debug.3malloc
+file path=usr/share/man/man3malloc/umem_setmtbf.3malloc
 file path=usr/share/man/man3malloc/watchmalloc.3malloc
 link path=usr/share/man/man3malloc/calloc.3malloc target=malloc.3malloc
 link path=usr/share/man/man3malloc/free.3malloc target=malloc.3malloc