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