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