1.\" Copyright (c) 1994-2021 Simon J. Gerraty 2.\" 3.\" SPDX-License-Identifier: BSD-2-Clause 4.\" 5.\" This file is provided in the hope that it will 6.\" be of use. There is absolutely NO WARRANTY. 7.\" Permission to copy, redistribute or otherwise 8.\" use this file is hereby granted provided that 9.\" the above copyright notice and this notice are 10.\" left intact. 11.\" 12.\" Please send copies of changes and bug-fixes to: 13.\" sjg@crufty.net 14.\" 15.Dd January 31, 2024 16.Dt DEBUG.SH 8 17.Os 18.Sh NAME 19.Nm debug.sh 20.Nd selectively debug scripts 21.Sh SYNOPSIS 22.Bl -item -compact 23.It 24.Ic $_DEBUG_SH .\& Pa debug.sh 25.Pp 26.It 27.Ic DebugOn Oo Fl eo Oc Ar tag ... 28.It 29.Ic DebugOff Oo Fl eo Oc Oo Cm rc= Ns Ar rc Oc Ar tag ... 30.It 31.Ic Debugging 32.It 33.Ic DebugEcho Op Ar message 34.It 35.Ic DebugLog Op Ar message 36.It 37.Ic DebugShell Ar tag ... 38.It 39.Ic DebugTrace Ar message 40.It 41.Ic Debug Ar tag ... 42.El 43.Sh DESCRIPTION 44.Nm 45provides the following functions to facilitate flexible 46run-time tracing of complicated shell scripts. 47.Bl -tag -width 4n 48.It Ic DebugOn Oo Fl eo Oc Ar tag ... 49turns tracing on if any 50.Ar tag 51is found in 52.Va DEBUG_SH 53(a comma separated list of tags). 54.Pp 55It turns tracing off if 56.Ar !tag 57is found in 58.Va DEBUG_SH . 59.Pp 60It sets 61.Va DEBUG_ON 62to the 63.Ar tag 64that caused tracing to be enabled, or 65.Va DEBUG_OFF 66if we matched 67.Ar !tag . 68.Pp 69If 70.Fl e 71option is present, returns 1 if no 72.Ar tag 73matched. 74.Pp 75If 76.Fl o 77option is present, tracing is turned off unless there 78was a matched 79.Ar tag , 80useful for functions too noisy to tace. 81.It Ic DebugOff Oo Fl eo Oc Oo Cm rc= Ns Ar rc Oc Ar tag ... 82turns tracing on if any 83.Ar tag 84matches 85.Va DEBUG_OFF 86or off if any 87.Ar tag 88matches 89.Va DEBUG_ON . 90This allows nested functions to not interfere with each other. 91.Pp 92The flags 93.Fl e 94and 95.Fl o 96are ignored, they just allow for symmetry with calls to 97.Fn DebugOn . 98.Pp 99The optional 100.Ar rc 101value will be returned rather than the default of 0. 102Thus if 103.Fn DebugOff 104is the last operation in a function, 105.Ar rc 106will be the return code of the function. 107.It Ic Debugging 108returns true if tracing is enabled. 109It is useful for bounding complex debug actions, rather than 110using lots of 111.Ic $DEBUG_DO 112lines. 113.It Ic DebugEcho 114is just shorthand for: 115.Bd -literal -offset indent 116$DEBUG_DO echo "$@" 117.Ed 118.It Ic DebugLog Op Ar message 119If debugging is enabled, output 120.Ar message 121prefixed with a time-stamp. 122.It Ic DebugShell Ar tag ... 123runs an interactive shell if any 124.Ar tag 125is found in 126.Va DEBUG_INTERACTIVE , 127and there is a tty available. 128The shell used is defined by 129.Va DEBUG_SHELL 130or 131.Va SHELL 132and defaults to 133.Pa /bin/sh . 134.It Ic DebugTrace Ar message 135Debug output can be very noisy, and it can be tricky 136to align with the script. 137This function outputs a very noticable banner indicating the value of 138.Va DEBUG_ON , 139and 140.Ar message 141is passed to 142.Fn DebugLog , 143finally the banner is repeated. 144.It Ic Debug Ar tag ... 145For backwards compatibility, calls 146.Fn DebugOn 147and if that does not turn tracing on, 148it calls 149.Fn DebugOff 150to turn it off. 151.El 152.Pp 153The variables 154.Va DEBUG_SKIP 155and 156.Va DEBUG_DO 157are set so as to enable/disable code that should be 158skipped/run when debugging is turned on. 159.Va DEBUGGING 160is the same as 161.Va DEBUG_SKIP 162for backwards compatability and is only set by 163.Fn Debug . 164.Pp 165The use of 166.Ic $_DEBUG_SH 167is to prevent multiple inclusion, 168though it does no harm in this case. 169.Sh BUGS 170Does not work with some versions of 171.Xr ksh 1 . 172If a function turns tracing on, ksh turns it off when the 173function returns - useless. 174.Pp 175PD ksh works ok ;-) 176.Sh AUTHOR 177.An -nosplit 178.Nm 179was written by 180.An Simon J Gerraty Aq Mt sjg@crufty.net . 181 182 183