Add some comments around tainting

3 files changed, 18 insertions, 7 deletions

diff --git a/intrpvar.h b/intrpvar.h
index e33036601b..41aa364329 100644
--- a/intrpvar.h
+++ b/intrpvar.h
@@ -75,7 +75,7 @@ PERLVAR(I, multideref_pc, UNOP_AUX_item *)
 PERLVAR(I, curpm,	PMOP *)		/* what to do \ interps in REs from */
 PERLVAR(I, curpm_under,        PMOP *)                /* what to do \ interps in REs from */
 
-PERLVAR(I, tainting,	bool)		/* doing taint checks */
+PERLVAR(I, tainting,	bool)		/* ? doing taint checks */
 PERLVARI(I, tainted,	bool, FALSE)	/* using variables controlled by $< */
 
 /* PL_delaymagic is currently used for two purposes: to assure simultaneous
diff --git a/perl.h b/perl.h
index e5a55850f1..a4d8ab656a 100644
--- a/perl.h
+++ b/perl.h
@@ -623,16 +623,24 @@
 #   define TAINT_WARN_get       0
 #   define TAINT_WARN_set(s)    NOOP
 #else
+    /* Set to tainted if we are running under tainting mode */
 #   define TAINT		(PL_tainted = PL_tainting)
-#   define TAINT_NOT	(PL_tainted = FALSE)
-#   define TAINT_IF(c)	if (UNLIKELY(c)) { PL_tainted = PL_tainting; }
+
+#   define TAINT_NOT	(PL_tainted = FALSE)        /* Untaint */
+#   define TAINT_IF(c)	if (UNLIKELY(c)) { TAINT; } /* Conditionally taint */
 #   define TAINT_ENV()	if (UNLIKELY(PL_tainting)) { taint_env(); }
-#   define TAINT_PROPER(s)	if (UNLIKELY(PL_tainting)) { taint_proper(NULL, s); }
+                                /* croak or warn if tainting */
+#   define TAINT_PROPER(s)	if (UNLIKELY(PL_tainting)) {                \
+                                    taint_proper(NULL, s);                  \
+                                }
 #   define TAINT_set(s)		(PL_tainted = (s))
 #   define TAINT_get		(PL_tainted)
-#   define TAINTING_get		(PL_tainting)
+#   define TAINTING_get		(PL_tainting)   /* Is taint checking enabled? */
 #   define TAINTING_set(s)	(PL_tainting = (s))
-#   define TAINT_WARN_get       (PL_taint_warn)
+#   define TAINT_WARN_get       (PL_taint_warn) /* FALSE => tainting violations
+                                                            are fatal
+                                                   TRUE =>  they're just
+                                                            warnings */
 #   define TAINT_WARN_set(s)    (PL_taint_warn = (s))
 #endif
 
diff --git a/taint.c b/taint.c
index 72216f85de..871d89f48b 100644
--- a/taint.c
+++ b/taint.c
@@ -26,6 +26,9 @@
 void
 Perl_taint_proper(pTHX_ const char *f, const char *const s)
 {
+    /* Output a tainting violation, croaking unless we're just to warn.
+     * '_proper' is just to throw you off the scent */
+
 #if defined(HAS_SETEUID) && defined(DEBUGGING)
     PERL_ARGS_ASSERT_TAINT_PROPER;
 
@@ -60,7 +63,7 @@ Perl_taint_proper(pTHX_ const char *f, const char *const s)
 	    ug = " while running with -T switch";
 
         /* XXX because taint_proper adds extra format args, we can't
-         * get the caller to check properly; o we just silence the warning
+         * get the caller to check properly; so we just silence the warning
          * and hope the callers aren't naughty */
         GCC_DIAG_IGNORE_STMT(-Wformat-nonliteral);
 	if (PL_unsafe || TAINT_WARN_get) {