1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2020 Robert Mustacchi 13.\" 14.Dd February 23, 2020 15.Dt UMEM_SETMTBF 3MALLOC 16.Os 17.Sh NAME 18.Nm umem_setmtbf 19.Nd set umem failure threshold 20.Sh SYNOPSIS 21.Lb libumem 22.In umem.h 23.Ft void 24.Fo umem_setmtbf 25.Fa "uint_t thresh" 26.Fc 27.Sh DESCRIPTION 28The 29.Fn umem_setmtbf 30function can be used to modify the run-time behavior of the 31.Xr libumem 3LIB 32library to set a threshold to cause injected memory allocation failures. 33.Pp 34By default, no failures are injected. 35When a non-zero value is passed in 36.Fa thresh 37then error injection is enabled, if the umem debugging features 38described in 39.Xr umem_debug 3MALLOC 40are enabled through the 41.Ev UMEM_DEBUG 42environment variable. 43If a process has not enabled the debugging functionality of 44.Xr libumem 3LIB 45then no errors will be injected, no matter what 46.Fa thresh 47is set to. 48.Pp 49Passing the value 50.Sy 0 51disables error injection. 52To cause every allocation to fail, pass the value 53.Sy 1 . 54The larger the value passed, the more time that will pass between error 55injections. 56Currently, an error is injected if the current time in nanoseconds since 57boot modulus the mtbf is zero. 58Concretely: 59.Bd -literal -offset indent 60if (gethrtime() % thresh) == 0) { 61 <inject error> 62} 63.Ed 64.Pp 65This mechanism is not guaranteed over time; however, the meanings of a 66threshold of zero, one, and the general tendency of larger numbers to 67indicate less errors is. 68.Sh MT-LEVEL 69.Sy Unsafe 70.Sh INTERFACE STABILITY 71.Sy Uncommitted 72.Sh SEE ALSO 73.Xr libumem 3LIB , 74.Xr umem_debug 3MALLOC 75